snmp_agent.h

00001 /**
00002  * @file snmp_agent.h
00003  * @brief SNMP agent (Simple Network Management Protocol)
00004  *
00005  * @section License
00006  *
00007  * Copyright (C) 2010-2017 Oryx Embedded SARL. All rights reserved.
00008  *
00009  * This file is part of CycloneTCP Open.
00010  *
00011  * This program is free software; you can redistribute it and/or
00012  * modify it under the terms of the GNU General Public License
00013  * as published by the Free Software Foundation; either version 2
00014  * of the License, or (at your option) any later version.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software Foundation,
00023  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00024  *
00025  * @author Oryx Embedded SARL (www.oryx-embedded.com)
00026  * @version 1.7.6
00027  **/
00028 
00029 #ifndef _SNMP_AGENT_H
00030 #define _SNMP_AGENT_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 #include "snmp/snmp_common.h"
00035 #include "snmp/snmp_usm.h"
00036 #include "mibs/mib_common.h"
00037 
00038 //SNMP agent support
00039 #ifndef SNMP_AGENT_SUPPORT
00040    #define SNMP_AGENT_SUPPORT DISABLED
00041 #elif (SNMP_AGENT_SUPPORT != ENABLED && SNMP_AGENT_SUPPORT != DISABLED)
00042    #error SNMP_AGENT_SUPPORT parameter is not valid
00043 #endif
00044 
00045 //Stack size required to run the SNMP agent
00046 #ifndef SNMP_AGENT_STACK_SIZE
00047    #define SNMP_AGENT_STACK_SIZE 550
00048 #elif (SNMP_AGENT_STACK_SIZE < 1)
00049    #error SNMP_AGENT_STACK_SIZE parameter is not valid
00050 #endif
00051 
00052 //Priority at which the SNMP agent should run
00053 #ifndef SNMP_AGENT_PRIORITY
00054    #define SNMP_AGENT_PRIORITY OS_TASK_PRIORITY_NORMAL
00055 #endif
00056 
00057 //Maximum number of users
00058 #ifndef SNMP_AGENT_MAX_USER_COUNT
00059    #define SNMP_AGENT_MAX_USER_COUNT 4
00060 #elif (SNMP_AGENT_MAX_USER_COUNT < 1)
00061    #error SNMP_AGENT_MAX_USER_COUNT parameter is not valid
00062 #endif
00063 
00064 //Maximum number of MIBs
00065 #ifndef SNMP_AGENT_MAX_MIB_COUNT
00066    #define SNMP_AGENT_MAX_MIB_COUNT 4
00067 #elif (SNMP_AGENT_MAX_MIB_COUNT < 1)
00068    #error SNMP_AGENT_MAX_MIB_COUNT parameter is not valid
00069 #endif
00070 
00071 
00072 /**
00073  * @brief Random data generation callback function
00074  **/
00075 
00076 typedef error_t (*SnmpAgentRandCallback)(uint8_t *data, size_t length);
00077 
00078 
00079 /**
00080  * @brief SNMP agent settings
00081  **/
00082 
00083 typedef struct
00084 {
00085    NetInterface *interface;                        ///<Network interface to configure
00086    SnmpVersion versionMin;                         ///<Minimum version accepted by the SNMP agent
00087    SnmpVersion versionMax;                         ///<Maximum version accepted by the SNMP agent
00088    uint16_t port;                                  ///<SNMP port number
00089    uint16_t trapPort;                              ///<SNMP trap port number
00090    SnmpAgentRandCallback randCallback;             ///<Random data generation callback function
00091 } SnmpAgentSettings;
00092 
00093 
00094 /**
00095  * @brief SNMP agent context
00096  **/
00097 
00098 typedef struct
00099 {
00100    SnmpAgentSettings settings;                           ///<SNMP agent settings
00101    OsMutex mutex;                                        ///<Mutex preventing simultaneous access to SNMP agent context
00102    uint8_t enterpriseOid[SNMP_MAX_OID_SIZE];             ///<Enterprise OID
00103    size_t enterpriseOidLen;                              ///<Length of the enterprise OID
00104    SnmpUserInfo userTable[SNMP_AGENT_MAX_USER_COUNT];    ///<List of users
00105    const MibModule *mibModule[SNMP_AGENT_MAX_MIB_COUNT]; ///<MIB modules
00106    uint_t mibModuleCount;                                ///<Number of MIB modules
00107    Socket *socket;                                       ///<Underlying socket
00108    IpAddr remoteIpAddr;                                  ///<IP address of the remote SNMP engine
00109    uint16_t remotePort;                                  ///<Source port used by the remote SNMP engine
00110    SnmpMessage request;                                  ///<SNMP request message
00111    SnmpMessage response;                                 ///<SNMP response message
00112    const SnmpUserInfo *user;                             ///<Security profile of current user
00113 #if (SNMP_V3_SUPPORT == ENABLED)
00114    uint8_t contextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE];  ///<Context engine identifier
00115    size_t contextEngineLen;                              ///<Length of the context engine identifier
00116    char_t contextName[SNMP_MAX_CONTEXT_NAME_LEN + 1];    ///<Context name
00117    systime_t systemTime;                                 ///<System time
00118    int32_t engineBoots;                                  ///<Number of times that the SNMP engine has rebooted
00119    int32_t engineTime;                                   ///<SNMP engine time
00120    uint64_t salt;                                        ///<Integer initialized to a random value at boot time
00121    uint8_t privParameters[8];                            ///<Privacy parameters
00122 #endif
00123 } SnmpAgentContext;
00124 
00125 
00126 /**
00127  * @brief Object descriptor
00128  **/
00129 
00130 typedef struct
00131 {
00132    uint8_t oid[SNMP_MAX_OID_SIZE];
00133    size_t oidLen;
00134 } SnmpTrapObject;
00135 
00136 
00137 //SNMP agent related functions
00138 void snmpAgentGetDefaultSettings(SnmpAgentSettings *settings);
00139 error_t snmpAgentInit(SnmpAgentContext *context, const SnmpAgentSettings *settings);
00140 error_t snmpAgentStart(SnmpAgentContext *context);
00141 
00142 error_t snmpAgentLoadMib(SnmpAgentContext *context, const MibModule *module);
00143 error_t snmpAgentUnloadMib(SnmpAgentContext *context, const MibModule *module);
00144 
00145 error_t snmpAgentSetEngineBoots(SnmpAgentContext *context, int32_t engineBoots);
00146 error_t snmpAgentGetEngineBoots(SnmpAgentContext *context, int32_t *engineBoots);
00147 
00148 error_t snmpAgentSetEnterpriseOid(SnmpAgentContext *context,
00149    const uint8_t *enterpriseOid, size_t enterpriseOidLen);
00150 
00151 error_t snmpAgentSetContextEngine(SnmpAgentContext *context,
00152    const void *contextEngine, size_t contextEngineLen);
00153 
00154 error_t snmpAgentSetContextName(SnmpAgentContext *context,
00155    const char_t *contextName);
00156 
00157 error_t snmpAgentCreateCommunity(SnmpAgentContext *context,
00158    const char_t *community, SnmpAccess mode);
00159 
00160 error_t snmpAgentDeleteCommunity(SnmpAgentContext *context,
00161    const char_t *community);
00162 
00163 error_t snmpAgentCreateUser(SnmpAgentContext *context,
00164    const char_t *username, SnmpAccess mode, SnmpKeyFormat keyFormat,
00165    SnmpAuthProtocol authProtocol, const void *authKey,
00166    SnmpPrivProtocol privProtocol, const void *privKey);
00167 
00168 error_t snmpAgentDeleteUser(SnmpAgentContext *context, const char_t *username);
00169 
00170 error_t snmpAgentSendTrap(SnmpAgentContext *context, const IpAddr *destIpAddr,
00171    SnmpVersion version, const char_t *username, uint_t genericTrapType,
00172    uint_t specificTrapCode, const SnmpTrapObject *objectList, uint_t objectListSize);
00173 
00174 void snmpAgentTask(SnmpAgentContext *context);
00175 
00176 #endif
00177