1.2.1.19 SNMP Module

SNMP is one of the key components of a Network Management System (NMS). SNMP is an application layer protocol that facilitates the exchange of management information among network devices. It is a part of the TCP/IP protocol suite.

SNMP is an Internet protocol that was originally designed to manage different network devices, such as file servers, hubs, routers and so on. It can also be used to manage and control an ever increasing number of small embedded systems connected to one another over any IP network. Systems can communicate with each other using SNMP to transfer control and status information, creating a truly distributed system.

SNMP is used in a variety of devices where remote monitoring and controlling of the network node is desired, such as a network printer, online Uninterrupted Power Supply (UPS), security cameras, home and industrial appliances monitor and control, automatic energy meter readings, etc.

Unlike more familiar human-oriented protocols, like HTTP, SNMP is considered a machine-to-machine protocol.

Note: The related application note, AN870 "SNMP V2c Agent for Microchip TCP/IP Stack" (DS8000870) is available for download from the Microchip web site at: http://ww1.microchip.com/downloads/en/AppNotes/00870b.pdf

Abstraction Model

SNMP Server (Agent)

SNMP is an Internet protocol that was originally designed to manage different network devices, such as file servers, hubs, routers, and so on. It can also be used to manage and control an ever increasing number of small embedded systems connected to one another over any IP network. Systems can communicate with each other using SNMP to transfer control and status information, creating a truly distributed system

Location of the SNMP Stack in the TCP/IP Protocol Stack:

The Microchip SNMP Server is a multi-lingual implementation, which supports SNMPv1, V2c, and V3 server features simultaneously. The SNMP Server is implemented to address the requirements of embedded applications and works with both IPv4 and IPv6 addresses. SNMPv1 and V2c are enabled by TCPIP_STACK_USE_SNMP_SERVER. SNMPv3 support is enabled by TCPIP_STACK_USE_SNMPV3_SERVER. Since the SNMPv3 stack requires the support of SNMPv1 and SNMPv2c, TCPIP_STACK_USE_SNMPV3_SERVER should be enabled with TCPIP_STACK_USE_SNMP_SERVER.

Note: Currently, the SNMP agent will be able to communicate with one manager at a time, and it will be connected to either an IPv4 address or an IPv6 address.

V2c

V2c is implemented with support for the configuration of multiple community names and the community names can be configured through the HTTP web interface. An access-restricted web page is provided with the demonstration application to allow dynamic configuration of SNMP communities.

SNMPv3

SNMPv3 RFC specifies different types of access mechanisms, user security model (USM), authentication and privacy protocols. The Microchip SNMPv3 Server is implemented with support for the AES 128 CFB 128 and DES-CBC privacy protocols, and the MD5 and SHA1 message authentication protocols. The demonstration implementation of the server is configured with three types of user names with respective authentication and privacy credentials and authentication types. These credentials and other user information are stored in the global array. The user of the SNMPv3 stack can decide on the number of user names in the User’s database to be stored with the SNMPv3 Server. According to the SNMPv3 recommendation, the SNMPv3 Server should not be configured with the authentication and privacy passwords. Instead, it could be configured with the respective localized keys of the password. The Microchip SNMPv3 agent is provided with the password information in the database for "Getting Started" and for understanding purposes only. It is recommended that the SNMPv3 stack be modified to restrict access to the password OIDs declared in the user database.

Note: Even though SNMPv3 also requires SNMPv1 and SNMPv2c, a layer in the SNMP Stack will prevent access to the variables that should be secured by SNMPv3. SNMP variables are structures in a tree in the MIB. Access to parts of this tree is determined by version. For example, SYSTEM-type variables can be accessed regardless of the SNMP version, while SNMPv2c requests can access part of the tree, and authenticated SNMPv3 requests can access the complete tree.

MIB Files

SNMP describes the hierarchal storage of management objects (referred to with object IDs or OIDs) with MIB files. The Microchip SNMP server demonstration includes two MIB files:

mchip.mib - This is an Abstract Syntax Notation One (ASN.1) formatted MIB file containing information about the variables used in the demonstration snmp.mib - This is a custom-formatted file that can be parsed to create Web page and header resources that can be accessed with a MCHP device The TCP/IP Stack includes the mib2bib utility, which will compile the custom Microchip MIB script (snmp.mib) to generate two files named snmp.bib and mib.h. The snmp.bib file is a compressed record of management objects that will be stored with web pages and the mib.h file contains C defines for each OID. These files are included in the appropriate directories for the TCP/IP Demonstration Applications, but for a custom application the snmp.bib must be copied to the web page directory, mib.h copied to the application directory and included in the project. Rebuild your project, and then rebuild and re-upload the web page. This will bundle the BIB file into the web page image, which will allow the SNMP agent to search for the required variable information with the MPFS file system.

MIB Browsers

Several SNMP MIB browsers are available. Users can also install a customized MIB browser specific to their application.

This documentation describes how to use the iREASONING Networks MIB Browser to run the TCP/IP SNMP demonstration applications. The MIB Browser can be obtained from: http://www.ireasoning.com/downloadmibbrowserlicense.shtml. The MIB script upload, the MIB tree structure display, and the SNMP query mechanism procedures vary from browser to browser.

Important! The use of a MIB browser or other third-party products may require that users review and agree to the terms of a license. Microchip's reference to the iREASONING Networks MIB Browser is for the users' convenience. It is the user's responsibility to obtain information about, and comply with the terms of, any applicable licenses.

Refer to the Microchip application note, AN870 "SNMP V2c Agent for Microchip TCP/IP Stack" (DS00000870) for more details on the MIB scripts, community names, and demonstration SNMP MIB variable tree structure.

The ASN.1 format mchip.mib file is defined with a private variable tree structure for the MIB variables. Also the mchip.mib is added with the number of OIDs that could be accessed only with SNMPv3 request. The browser can access every variable in the MIB database provided the community name matches. The access to the MIB variables is restricted to the type of the request. The RFC1213 MIB variables could be accessed with SNMPv2c/v3 request. But the SNMP-FRAMEWORK-MIB.mib variables could only be accessed with a SNMPv3 request if the credentials are matched and the message is authenticated. To modify these MIB variables, corresponding changes must be made to both MIB scripts (snmp.mib and mchip.mib).

• For SNMP V2c services , The V2c agent is configured by default with three Read communities ("public", "read", "") and three Write communities ("private","write","public")

• At run-time, the community names can be dynamically configured using the HTTP interface for SNMP community name configuration

• If the V2c agent receives an SNMP request with an unknown community name, the agent will generate an Authentication trap

The V2c agent's multiple community support feature enables the user application to provide limited access to the requesting browser based on the community name used by the browser to access the MIB database variables of the agent.

For SNMPv3 services:

If SNMPv3 services are required, SNMPv3 browser is required to be configured with the user name, authentication and privacy password, message authentication hash type, privacy protocol type. The SNMP server would respond only if one of the user credentials and user security parameters in the following table is configured at the manager. The previous table is stored in the global structure with the SNMPv3 server stack. The SNMPv3 server would only respond if the request credentials of the MIB browser matches to that of the stored user data base of the SNMP server.

The Microchip SNMPv3 stack does support only one Context Engine ID with the server. Leave the "Context Name" option in the "Advanced" tab empty. It is ignored on the server.

According to the user and the auth and privacy protocols configured with the SNMP browser, the UDP authenticated and encrypted message would be exchanged between server and the client.

• If the USER 1 values, as shown in the table, are configured in the MIB browser, the data exchange between the client and server is encrypted and authenticated. The PDU could be captured in the Ethernet packet sniffer, such as WireShark, and examined. As the data is encrypted and authenticated, the data integrity and the privacy is achieved.

• If USER 2 values, as shown in the table, are configured in the MIB browser, the data exchange between client and server is authenticated. The data integrity would be checked once the data is received at either end. The message authentication mechanism protects from the possible data sniffing and modification threat, and also guarantees that the data is received from the authenticated and guaranteed source.

• If USER 3 values, as shown in the table, are configured in the MIB browser, the data exchange between client and server is neither authenticated nor encrypted

• Considering the three USER configurations, if the SNMP server is to be accessed over WAN, in the Internet cloud, the data should be encrypted and authenticated to have the highest level of data privacy and integrity

SNMP Traps

The MPLAB Harmony TCP/IP Stack supports Trap version1 and Trap version2 formatted traps. Traps are notifications from the agent to the manager that are used when a predefined event occurs at the agent.

From mchip.mib, the ipv4TrapTable and ipv6TrapTable are the two tabular sections, which are used to configure HOST IPv4 and IPv6 address and this will help the HOST trap receiver to receive the traps.

Several preprocessor macros in the snmp_config.h variant header file can be used to enable or disable traps in the agent. Commenting and uncommenting these macros in the file will have different results. The SNMP_TRAP_DISABLED macro will disable traps entirely if it is not commented:

#define SNMP_TRAP_DISABLED

The user must configure the expected trap format at the SNMP Manager. SNMPv2 entities acting as an agent should be able to generate and transmit SNMP V2 trap PDUs when the manager is configured to receive and process SNMP V2 trap PDUs. To configure the trap format, comment or uncomment the SNMP_STACK_USE_V2_TRAP macro in the snmp_config.h header file:

#define SNMP_STACK_USE_V2_TRAP

If the macro has been commented out, the SNMP agent will send V1 formatted trap PDUs; otherwise, it will send V2 formatted trap PDUs. By default, the SNMP agent is configured to send V2 formatted traps. Note that the SNMP V2c agent should only send V2 formatted traps.

To enable traps in SNMPv3, the #define SNMP_V1_V2_TRAP_WITH_SNMPv3 macro must be uncommented.

The following table illustrates how to enable/disable traps for different versions of SNMP.

Demonstrations Two trap demonstrations APIs are included with the TCP/IP Stack. The task functions for these demonstrations are called in the main application function:

• SNMPTrapDemo - This API demonstrates V1 or V2 trap formats (depending of the status of the SNMP_STACK_USE_V2_TRAP macro). The trap PDU will only have one demonstration variable binding on the varbind list.

• SNMPV2TrapDemo - This API provides V2 format notifications with multiple (4) variable bindings. The user should modify or use this routine as a reference for sending V2 trap format notifications with multiple bindings on the varbind list.

Note: The user should only enable one SNMP demonstration API at a time. By default, the SNMPV2TrapDemo API is enabled and SNMPTrapDemo is commented out (disabled).

V1/V2 Formatted Traps with a Single Variable Binding In the snmp_config.h header file:

• Uncomment #define SNMP_TRAP_DISABLED

• Comment //#define SNMP_STACK_USE_V2_TRAP

For the Trap demonstration, two events are defined within the V2c agent:

• If the Analog Potentiometer value is greater than 14, the agent will send a Trap every 5 seconds to the configured 'IPv4TrapReceiverIP address'.

• If Button 3 on the demonstration board is pressed, an organization-specific PUSH_BUTTON trap will be sent.

The current implementation of the V2c agent also generates a standard "Authentication Failure Trap":

• If a request is received to modify (Set) a private MIB variable, or

• If the value of the variable is requested (Get) by a browser with the wrong community name

HTTP Configuration

If a HTTP server is used with the Harmony TCP/IP stack, it is possible to dynamically configure the Read and Write community names through the SNMP Configuration web page. Access the web page using http://mchpboard_c/mpfsupload or http://(for IPv6 it should be http://:80/index.html), and then access the SNMP Configuration web page through the navigation bar. Use "admin" for the username and "microchip" for the password.

Library Interface

Name	Description
Macros
TCPIP_SNMP_BIB_FILE_NAME	The Microchip mib2bib.jar compiler is used to convert the Microchip MIB script to binary format and it is compatible with the Microchip SNMP agent. which is written in ASCII format. Name of the bib file for SNMP is snmp.bib.
TCPIP_SNMP_COMMUNITY_MAX_LEN	This is the maximum length for community string. Application must ensure that this length is observed. SNMP module adds one byte extra after TCPIP_SNMP_COMMUNITY_MAX_LEN for adding '0' NULL character.
TCPIP_SNMP_MAX_COMMUNITY_SUPPORT	Specifying more strings than TCPIP_SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying fewer strings is legal, as long as at least one is present.
TCPIP_SNMP_MAX_MSG_SIZE	The maximum length in octets of an SNMP message which this SNMP agent able to process. As per RFC 3411 snmpEngineMaxMessageSize and RFC 1157 ( section 4- protocol specification ) and implementation supports more than 480 whenever feasible. It should be divisible by 16
TCPIP_SNMP_MAX_NON_REC_ID_OID	Update the Non record id OID value which is part of CustomSnmpDemoApp.c file. This is the maximum size for gSnmpNonMibRecInfo which is the list of static variable Parent OIDs which are not part of mib.h file. This structure is used to restrict access to static variables of SNMPv3 OIDs from SNMPv2c and SNMPv1 version. With SNMPv3 all the OIDs accessible but when we are using SNMPv2c version , static variables of the SNMPv3 cannot be accessible with SNMP version v2c. SNMP agent supports both SMIv1 and SMIv2 standard and snmp.mib has been updated with respect to SMIV2 standard and it... more
TCPIP_SNMP_NOTIFY_COMMUNITY_LEN	Maximum length for SNMP Trap community name
TCPIP_SNMP_OID_MAX_LEN	Maximum length for the OID String. Change this to match your OID string length.
TCPIP_SNMP_TASK_PROCESS_RATE	SNMP task processing rate, in milli-seconds. The SNMP module will process a timer event with this rate for processing its own state machine, etc. The default value is 200 milliseconds. The lower the rate (higher the frequency) the higher the module priority and higher module performance can be obtained The value cannot be lower than the TCPIP_STACK_TICK_RATE.
TCPIP_SNMP_TRAP_COMMUNITY_MAX_LEN	The maximum size of TRAP community string length
TCPIP_SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE	Trap information. This macro will be used to avoid SNMP OID memory buffer corruption
TCPIP_SNMP_TRAP_TABLE_SIZE	This table maintains list of interested receivers who should receive notifications when some interesting event occurs.
TCPIP_SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN	SNMPv3 Authentication Localized password key length size
TCPIP_SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE	SNMPv3 authentication localized Key length for memory validation
TCPIP_SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN	SNMPv3 Privacy Password key length size
TCPIP_SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE	SNMPv3 privacy key length size for memory validation
TCPIP_SNMPV3_USER_SECURITY_NAME_LEN	Maximum size for SNMPv3 User Security Name length.
TCPIP_SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE	User security name length for memory validation
TCPIP_SNMPV3_USM_MAX_USER	Maximum number of SNMPv3 users. User Security Model should have at least 1 user. Default is 3.
**SNMP Module Functions **
TCPIP_SNMP_NotifyIsReady	Resolves given remoteHost IP address into MAC address.
TCPIP_SNMP_NotifyPrepare	Collects trap notification info and send ARP to remote host.
TCPIP_SNMP_TrapTimeGet	Gets SNMP Trap UDP client open socket time-out.
TCPIP_SNMP_ClientGetNet	Get a network interface for SNMP TRAP.
TCPIP_SNMP_ExactIndexGet	To search for exact index node in case of a Sequence variable.
TCPIP_SNMP_IsValidCommunity	Validates community name for access control.
TCPIP_SNMP_IsValidLength	Validates the set variable data length to data type.
TCPIP_SNMP_MibIDSet	Sets the agent MIB ID for SNP notification.
TCPIP_SNMP_NextIndexGet	To search for next index node in case of a Sequence variable.
TCPIP_SNMP_ReadCommunityGet	Gets the readCommunity String with SNMP index.
TCPIP_SNMP_RecordIDValidation	Used to restrict the access dynamic and non dynamic OID string for a particular SNMP Version.
TCPIP_SNMP_SendFailureTrap	Prepares and validates the remote node that will receive a trap and send the trap PDU.
TCPIP_SNMP_TrapInterFaceSet	Sets the TRAP interface for SNMP notification.
TCPIP_SNMP_TRAPMibIDGet	Gets the agent MIB ID for SNP notification.
TCPIP_SNMP_TrapSendFlagGet	Gets the status of trap send flag.
TCPIP_SNMP_TrapSendFlagSet	Sets the status of trap send flag.
TCPIP_SNMP_TrapSpecificNotificationGet	Gets the specific trap.
TCPIP_SNMP_TrapSpecificNotificationSet	Sets the specific trap, generic trap, and trap ID.
TCPIP_SNMP_VarbindGet	Used to get/collect OID variable information.
TCPIP_SNMP_VarbindSet	Sets the MIB variable with the requested value.
TCPIP_SNMP_WriteCommunityGet	Gets the writeCommunity String with SNMP index.
TCPIP_SNMP_AuthTrapFlagGet	Gets the status of authentication trap flag.
TCPIP_SNMP_AuthTrapFlagSet	Sets the status of authentication trap flag.
TCPIP_SNMP_IsTrapEnabled	Gets the SNMP Trap status.
TCPIP_SNMP_ReadCommunitySet	Sets the readCommunity String with SNMP index.
TCPIP_SNMP_SocketIDGet	Gets the Socket ID for SNMP Server socket.
TCPIP_SNMP_SocketIDSet	Sets the Socket ID for SNMP Server socket.
TCPIP_SNMP_Task	Standard TCP/IP stack module task function.
TCPIP_SNMP_TRAPTypeGet	Get SNMP Trap type for version v1 and v2c.
TCPIP_SNMP_TRAPv1Notify	Creates and Sends TRAPv1 pdu.
TCPIP_SNMP_TRAPv2Notify	Creates and sends TRAP PDU.
TCPIP_SNMP_ValidateTrapIntf	Gets the status of trap interface.
TCPIP_SNMP_WriteCommunitySet	Sets the writeCommunity String with SNMP index.
SNMPv3 Module Functions
TCPIP_SNMPV3_EngineUserDataBaseGet	Get SNMPv3 engine data base details.
TCPIP_SNMPV3_EngineUserDataBaseSet	Set SNMPv3 engine data base details.
TCPIP_SNMPv3_TrapConfigDataGet	Gets the SNMPv3 Trap configuration details using the user name index.
TCPIP_SNMPv3_Notify	Creates and Sends SNMPv3 TRAP PDU.
TCPIP_SNMPV3_TrapTypeGet	Gets SNMP Trap type for version v3.
SNMP Data Types and Constants
SNMP_COMMUNITY_TYPE	Definition to represent different type of SNMP communities.
SNMP_END_OF_VAR	This Macro is used for both SNMP SET and GET Variable processing to indicate the end of SNMP variable processing. For multi byte data request, the end byte will be always SNMP_END_OF_VAR.
SNMP_INDEX_INVALID	This Macro is used for both SNMP SET and GET Sequence Variable processing. SNMP starts processing the start of sequence variable with Invalid index. TCPIP_SNMP_ExactIndexGet and TCPIP_SNMP_NextIndexGet returns a valid index as per SNMP_INDEX_INVALID.
SNMP_NON_MIB_RECD_INFO	Restrict access for specific OIDs.
SNMP_START_OF_VAR	This Macro is used for both SNMP SET and GET Variable processing to indicate the start of SNMP variable processing. For multi byte data request, the first byte will be always SNMP_START_OF_VAR.
SNMP_TRAP_IP_ADDRESS_TYPE	Definition of the supported address types for SNMP trap.
SNMP_VAL	Definition to represent SNMP OID object values.
SNMP_ID	SNMP dynamic variable ID.
SNMP_INDEX	SNMP sequence variable index.
SNMP_V1	This macro is used for SNMP version 1
SNMP_V2C	This macro is used for SNMP version 2 with community
SNMP_V3	This macro is used for SNMP version 3 with authentication and privacy
SNMP_GENERIC_TRAP_NOTIFICATION_TYPE	Definition to represent different SNMP generic trap types.
SNMP_VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE	Definition to represent different SNMP vendor trap types.
SNMPv3 Data Types and Constants
SNMPV3_HMAC_HASH_TYPE	Different type of authentication for SNMPv3.
SNMPV3_PRIV_PROT_TYPE	Different type of encryption and decryption for SNMPv3.
STD_BASED_SNMP_MESSAGE_PROCESSING_MODEL	Different SNMP Message processing model
STD_BASED_SNMP_SECURITY_MODEL	Different Security services for SNMPv3 messages.
STD_BASED_SNMPV3_SECURITY_LEVEL	Different Security Level for SNMPv3 messages.
TCPIP_SNMPV3_USERDATABASECONFIG_TYPE	Different Configuration parameters of SNMPv3 operation
TCPIP_SNMP_COMMUNITY_CONFIG	SNMP community configuration.
TCPIP_SNMP_MODULE_CONFIG	SNMP module configuration.
TCPIP_SNMPV3_TARGET_ENTRY_CONFIG	SNMP module trap target address configuration.
TCPIP_SNMPV3_USM_USER_CONFIG	SNMPv3 USM configuration.