snmp_common.h

00001 /**
00002  * @file snmp_common.h
00003  * @brief Functions common to SNMP agent and SNMP manager
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_COMMON_H
00030 #define _SNMP_COMMON_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 
00035 //SNMPv1 support
00036 #ifndef SNMP_V1_SUPPORT
00037    #define SNMP_V1_SUPPORT ENABLED
00038 #elif (SNMP_V1_SUPPORT != ENABLED && SNMP_V1_SUPPORT != DISABLED)
00039    #error SNMP_V1_SUPPORT parameter is not valid
00040 #endif
00041 
00042 //SNMPv2c support
00043 #ifndef SNMP_V2C_SUPPORT
00044    #define SNMP_V2C_SUPPORT ENABLED
00045 #elif (SNMP_V2C_SUPPORT != ENABLED && SNMP_V2C_SUPPORT != DISABLED)
00046    #error SNMP_V2C_SUPPORT parameter is not valid
00047 #endif
00048 
00049 //SNMPv3 support
00050 #ifndef SNMP_V3_SUPPORT
00051    #define SNMP_V3_SUPPORT DISABLED
00052 #elif (SNMP_V3_SUPPORT != ENABLED && SNMP_V3_SUPPORT != DISABLED)
00053    #error SNMP_V3_SUPPORT parameter is not valid
00054 #endif
00055 
00056 //Maximum size of SNMP messages
00057 #ifndef SNMP_MAX_MSG_SIZE
00058    #define SNMP_MAX_MSG_SIZE 484
00059 #elif (SNMP_MAX_MSG_SIZE < 484 || SNMP_MAX_MSG_SIZE > 65535)
00060    #error SNMP_MAX_MSG_SIZE parameter is not valid
00061 #endif
00062 
00063 //Maximum size for context engine identifier
00064 #ifndef SNMP_MAX_CONTEXT_ENGINE_SIZE
00065    #define SNMP_MAX_CONTEXT_ENGINE_SIZE 32
00066 #elif (SNMP_MAX_CONTEXT_ENGINE_SIZE < 8)
00067    #error SNMP_MAX_CONTEXT_ENGINE_SIZE parameter is not valid
00068 #endif
00069 
00070 //Maximum length for context name
00071 #ifndef SNMP_MAX_CONTEXT_NAME_LEN
00072    #define SNMP_MAX_CONTEXT_NAME_LEN 16
00073 #elif (SNMP_MAX_CONTEXT_NAME_LEN < 8)
00074    #error SNMP_MAX_CONTEXT_NAME_LEN parameter is not valid
00075 #endif
00076 
00077 //Maximum length for user names and community names
00078 #ifndef SNMP_MAX_USER_NAME_LEN
00079    #define SNMP_MAX_USER_NAME_LEN 16
00080 #elif (SNMP_MAX_USER_NAME_LEN < 8)
00081    #error SNMP_MAX_USER_NAME_LEN parameter is not valid
00082 #endif
00083 
00084 //Maximum size for object identifiers
00085 #ifndef SNMP_MAX_OID_SIZE
00086    #define SNMP_MAX_OID_SIZE 16
00087 #elif (SNMP_MAX_OID_SIZE < 1)
00088    #error SNMP_MAX_OID_SIZE parameter is not valid
00089 #endif
00090 
00091 //SNMP port number
00092 #define SNMP_PORT 161
00093 //SNMP trap port number
00094 #define SNMP_TRAP_PORT 162
00095 
00096 //SNMPv1 message header overhead
00097 #define SNMP_V1_MSG_HEADER_OVERHEAD 48
00098 //SNMPv2c message header overhead
00099 #define SNMP_V2C_MSG_HEADER_OVERHEAD 37
00100 //SNMPv3 message header overhead
00101 #define SNMP_V3_MSG_HEADER_OVERHEAD 105
00102 
00103 
00104 /**
00105  * @brief SNMP version identifiers
00106  **/
00107 
00108 typedef enum
00109 {
00110    SNMP_VERSION_1  = 0,
00111    SNMP_VERSION_2C = 1,
00112    SNMP_VERSION_3  = 3
00113 } SnmpVersion;
00114 
00115 
00116 /**
00117  * @brief SNMP PDU types
00118  **/
00119 
00120 typedef enum
00121 {
00122    SNMP_PDU_GET_REQUEST      = 0,
00123    SNMP_PDU_GET_NEXT_REQUEST = 1,
00124    SNMP_PDU_GET_RESPONSE     = 2,
00125    SNMP_PDU_SET_REQUEST      = 3,
00126    SNMP_PDU_TRAP             = 4,
00127    SNMP_PDU_GET_BULK_REQUEST = 5,
00128    SNMP_PDU_INFORM_REQUEST   = 6,
00129    SNMP_PDU_TRAP_V2          = 7,
00130    SNMP_PDU_REPORT           = 8
00131 } SnmpPduType;
00132 
00133 
00134 /**
00135  * @brief SNMP generic trap types
00136  **/
00137 
00138 typedef enum
00139 {
00140    SNMP_TRAP_COLD_START          = 0,
00141    SNMP_TRAP_WARM_START          = 1,
00142    SNMP_TRAP_LINK_DOWN           = 2,
00143    SNMP_TRAP_LINK_UP             = 3,
00144    SNMP_TRAP_AUTH_FAILURE        = 4,
00145    SNMP_TRAP_EGP_NEIGHBOR_LOSS   = 5,
00146    SNMP_TRAP_ENTERPRISE_SPECIFIC = 6
00147 } SnmpGenericTrapType;
00148 
00149 
00150 /**
00151  * @brief SNMP error status
00152  **/
00153 
00154 typedef enum
00155 {
00156    SNMP_ERROR_NONE                 = 0,
00157    SNMP_ERROR_TOO_BIG              = 1,
00158    SNMP_ERROR_NO_SUCH_NAME         = 2,
00159    SNMP_ERROR_BAD_VALUE            = 3,
00160    SNMP_ERROR_READ_ONLY            = 4,
00161    SNMP_ERROR_GENERIC              = 5,
00162    SNMP_ERROR_NO_ACCESS            = 6,
00163    SNMP_ERROR_WRONG_TYPE           = 7,
00164    SNMP_ERROR_WRONG_LENGTH         = 8,
00165    SNMP_ERROR_WRONG_ENCODING       = 9,
00166    SNMP_ERROR_WRONG_VALUE          = 10,
00167    SNMP_ERROR_NO_CREATION          = 11,
00168    SNMP_ERROR_INCONSISTENT_VALUE   = 12,
00169    SNMP_ERROR_RESOURCE_UNAVAILABLE = 13,
00170    SNMP_ERROR_COMMIT_FAILED        = 14,
00171    SNMP_ERROR_UNDO_FAILED          = 15,
00172    SNMP_ERROR_AUTHORIZATION        = 16,
00173    SNMP_ERROR_NOT_WRITABLE         = 17,
00174    SNMP_ERROR_INCONSISTENT_NAME    = 18
00175 } SnmpErrorStatus;
00176 
00177 
00178 /**
00179  * @brief SNMP exceptions
00180  **/
00181 
00182 typedef enum
00183 {
00184    SNMP_EXCEPTION_NO_SUCH_OBJECT   = 0,
00185    SNMP_EXCEPTION_NO_SUCH_INSTANCE = 1,
00186    SNMP_EXCEPTION_END_OF_MIB_VIEW  = 2
00187 } SnmpException;
00188 
00189 
00190 /**
00191  * @brief SNMP engine ID format
00192  **/
00193 
00194 typedef enum
00195 {
00196    SNMP_ENGINE_ID_FORMAT_IPV4   = 1,
00197    SNMP_ENGINE_ID_FORMAT_IPV6   = 2,
00198    SNMP_ENGINE_ID_FORMAT_MAC    = 3,
00199    SNMP_ENGINE_ID_FORMAT_TEXT   = 4,
00200    SNMP_ENGINE_ID_FORMAT_OCTETS = 5,
00201 } SnmpEngineIdFormat;
00202 
00203 
00204 /**
00205  * @brief SNMP message
00206  **/
00207 
00208 typedef struct
00209 {
00210    uint8_t buffer[SNMP_MAX_MSG_SIZE]; ///<Buffer that holds the message
00211    size_t bufferLen;                  ///<Original length of the message
00212    uint8_t *pos;                      ///<Current position
00213    size_t length;                     ///<Length of the message
00214    int32_t version;                   ///<SNMP version identifier
00215 #if (SNMP_V1_SUPPORT == ENABLED || SNMP_V2C_SUPPORT == ENABLED)
00216    const char_t *community;           ///<Community name
00217    size_t communityLen;               ///<Length of the community name
00218 #endif
00219 #if (SNMP_V3_SUPPORT == ENABLED)
00220    int32_t msgId;                     ///<Message identifier
00221    int32_t msgMaxSize;                ///<Maximum message size supported by the sender
00222    uint8_t msgFlags;                  ///<Bit fields which control processing of the message
00223    int32_t msgSecurityModel;          ///<Security model used by the sender
00224    const uint8_t *msgAuthEngineId;    ///<Authoritative engine identifier
00225    size_t msgAuthEngineIdLen;         ///<Length of the authoritative engine identifier
00226    int32_t msgAuthEngineBoots;        ///<Number of times the SNMP engine has rebooted
00227    int32_t msgAuthEngineTime;         ///<Number of seconds since last reboot
00228    const char_t *msgUserName;         ///<User name
00229    size_t msgUserNameLen;             ///<Length of the user name
00230    uint8_t *msgAuthParameters;        ///<Authentication parameters
00231    size_t msgAuthParametersLen;       ///<Length of the authentication parameters
00232    const uint8_t *msgPrivParameters;  ///<Privacy parameters
00233    size_t msgPrivParametersLen;       ///<Length of the privacy parameters
00234    const uint8_t *contextEngineId;    ///<Context engine identifier
00235    size_t contextEngineIdLen;         ///<Length of the context engine identifier
00236    const uint8_t *contextName;        ///<Context name
00237    size_t contextNameLen;             ///<Length of the context name
00238 #endif
00239    SnmpPduType pduType;               ///<PDU type
00240    int32_t requestId;                 ///<Request identifier
00241    int32_t errorStatus;               ///<Error status
00242    int32_t errorIndex;                ///<Error index
00243 #if (SNMP_V1_SUPPORT == ENABLED)
00244    const uint8_t *enterpriseOid;      ///<Type of object generating trap
00245    size_t enterpriseOidLen;           ///<Length of the enterprise OID
00246    Ipv4Addr agentAddr;                ///<Address of object generating trap
00247    int32_t genericTrapType;           ///<Generic trap type
00248    int32_t specificTrapCode;          ///<Specific trap code
00249    uint32_t timestamp;                ///<Timestamp
00250 #endif
00251 #if (SNMP_V2C_SUPPORT == ENABLED || SNMP_V3_SUPPORT == ENABLED)
00252    int32_t nonRepeaters;              ///<GetBulkRequest-PDU specific parameter
00253    int32_t maxRepetitions;            ///<GetBulkRequest-PDU specific parameter
00254 #endif
00255    uint8_t *varBindList;              ///<List of variable bindings
00256    size_t varBindListLen;             ///<Length of the list in bytes
00257    size_t varBindListMaxLen;          ///<Maximum length of the list in bytes
00258    size_t oidLen;                     ///<Length of the object identifier
00259 } SnmpMessage;
00260 
00261 
00262 /**
00263  * @brief Variable binding
00264  **/
00265 
00266 typedef struct
00267 {
00268    const uint8_t *oid;
00269    size_t oidLen;
00270    uint_t objClass;
00271    uint_t objType;
00272    const uint8_t *value;
00273    size_t valueLen;
00274 } SnmpVarBind;
00275 
00276 
00277 //SNMP related functions
00278 void snmpInitMessage(SnmpMessage *message);
00279 error_t snmpComputeMessageOverhead(SnmpMessage *message);
00280 
00281 error_t snmpParseMessageHeader(SnmpMessage *message);
00282 error_t snmpWriteMessageHeader(SnmpMessage *message);
00283 
00284 error_t snmpParseCommunity(SnmpMessage *message);
00285 error_t snmpWriteCommunity(SnmpMessage *message);
00286 
00287 error_t snmpParseGlobalData(SnmpMessage *message);
00288 error_t snmpWriteGlobalData(SnmpMessage *message);
00289 
00290 error_t snmpParseSecurityParameters(SnmpMessage *message);
00291 error_t snmpWriteSecurityParameters(SnmpMessage *message);
00292 
00293 error_t snmpParseScopedPdu(SnmpMessage *message);
00294 error_t snmpWriteScopedPdu(SnmpMessage *message);
00295 
00296 error_t snmpParsePduHeader(SnmpMessage *message);
00297 error_t snmpWritePduHeader(SnmpMessage *message);
00298 
00299 error_t snmpEncodeInt32(int32_t value, uint8_t *dest, size_t *length);
00300 error_t snmpEncodeUnsignedInt32(uint32_t value, uint8_t *dest, size_t *length);
00301 error_t snmpEncodeUnsignedInt64(uint64_t value, uint8_t *dest, size_t *length);
00302 
00303 error_t snmpDecodeInt32(const uint8_t *src, size_t length, int32_t *value);
00304 error_t snmpDecodeUnsignedInt32(const uint8_t *src, size_t length, uint32_t *value);
00305 error_t snmpDecodeUnsignedInt64(const uint8_t *src, size_t length, uint64_t *value);
00306 
00307 #endif
00308