snmp_agent.h
Go to the documentation of this file.
1 /**
2  * @file snmp_agent.h
3  * @brief SNMP agent (Simple Network Management Protocol)
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _SNMP_AGENT_H
30 #define _SNMP_AGENT_H
31 
32 //Forward declaration of SnmpAgentContext structure
33 struct _SnmpAgentContext;
34 #define SnmpAgentContext struct _SnmpAgentContext
35 
36 //Dependencies
37 #include "core/net.h"
38 #include "snmp/snmp_common.h"
40 #include "snmp/snmp_agent_trap.h"
41 #include "snmp/snmp_agent_inform.h"
42 #include "snmp/snmp_agent_usm.h"
43 #include "snmp/snmp_agent_vacm.h"
44 #include "mibs/mib_common.h"
45 
46 //SNMP agent support
47 #ifndef SNMP_AGENT_SUPPORT
48  #define SNMP_AGENT_SUPPORT DISABLED
49 #elif (SNMP_AGENT_SUPPORT != ENABLED && SNMP_AGENT_SUPPORT != DISABLED)
50  #error SNMP_AGENT_SUPPORT parameter is not valid
51 #endif
52 
53 //Stack size required to run the SNMP agent
54 #ifndef SNMP_AGENT_STACK_SIZE
55  #define SNMP_AGENT_STACK_SIZE 550
56 #elif (SNMP_AGENT_STACK_SIZE < 1)
57  #error SNMP_AGENT_STACK_SIZE parameter is not valid
58 #endif
59 
60 //Priority at which the SNMP agent should run
61 #ifndef SNMP_AGENT_PRIORITY
62  #define SNMP_AGENT_PRIORITY OS_TASK_PRIORITY_NORMAL
63 #endif
64 
65 //Maximum number of MIBs
66 #ifndef SNMP_AGENT_MAX_MIBS
67  #define SNMP_AGENT_MAX_MIBS 8
68 #elif (SNMP_AGENT_MAX_MIBS < 1)
69  #error SNMP_AGENT_MAX_MIBS parameter is not valid
70 #endif
71 
72 //Maximum number of community strings
73 #ifndef SNMP_AGENT_MAX_COMMUNITIES
74  #define SNMP_AGENT_MAX_COMMUNITIES 3
75 #elif (SNMP_AGENT_MAX_COMMUNITIES < 1)
76  #error SNMP_AGENT_MAX_COMMUNITIES parameter is not valid
77 #endif
78 
79 //Maximum number of users
80 #ifndef SNMP_AGENT_MAX_USERS
81  #define SNMP_AGENT_MAX_USERS 8
82 #elif (SNMP_AGENT_MAX_USERS < 1)
83  #error SNMP_AGENT_MAX_USERS parameter is not valid
84 #endif
85 
86 //Size of the group table
87 #ifndef SNMP_AGENT_GROUP_TABLE_SIZE
88  #define SNMP_AGENT_GROUP_TABLE_SIZE 8
89 #elif (SNMP_AGENT_GROUP_TABLE_SIZE < 1)
90  #error SNMP_AGENT_GROUP_TABLE_SIZE parameter is not valid
91 #endif
92 
93 //Size of the access table
94 #ifndef SNMP_AGENT_ACCESS_TABLE_SIZE
95  #define SNMP_AGENT_ACCESS_TABLE_SIZE 8
96 #elif (SNMP_AGENT_ACCESS_TABLE_SIZE < 1)
97  #error SNMP_AGENT_ACCESS_TABLE_SIZE parameter is not valid
98 #endif
99 
100 //Size of the view table
101 #ifndef SNMP_AGENT_VIEW_TABLE_SIZE
102  #define SNMP_AGENT_VIEW_TABLE_SIZE 8
103 #elif (SNMP_AGENT_VIEW_TABLE_SIZE < 1)
104  #error SNMP_AGENT_VIEW_TABLE_SIZE parameter is not valid
105 #endif
106 
107 //C++ guard
108 #ifdef __cplusplus
109  extern "C" {
110 #endif
111 
112 
113 /**
114  * @brief Random data generation callback function
115  **/
116 
117 typedef error_t (*SnmpAgentRandCallback)(uint8_t *data, size_t length);
118 
119 
120 /**
121  * @brief SNMP agent settings
122  **/
123 
124 typedef struct
125 {
126  NetInterface *interface; ///<Network interface to configure
127  SnmpVersion versionMin; ///<Minimum version accepted by the SNMP agent
128  SnmpVersion versionMax; ///<Maximum version accepted by the SNMP agent
129  uint16_t port; ///<SNMP port number
130  uint16_t trapPort; ///<SNMP trap port number
131  SnmpAgentRandCallback randCallback; ///<Random data generation callback function
133 
134 
135 /**
136  * @brief SNMP agent context
137  **/
138 
140 {
141  SnmpAgentSettings settings; ///<SNMP agent settings
142  OsMutex mutex; ///<Mutex preventing simultaneous access to SNMP agent context
143  uint8_t enterpriseOid[SNMP_MAX_OID_SIZE]; ///<Enterprise OID
144  size_t enterpriseOidLen; ///<Length of the enterprise OID
145  const MibModule *mibTable[SNMP_AGENT_MAX_MIBS]; ///<MIB modules
146 #if (SNMP_V1_SUPPORT == ENABLED || SNMP_V2C_SUPPORT == ENABLED)
148 #endif
149 #if (SNMP_V3_SUPPORT == ENABLED)
151 #endif
152 #if (SNMP_AGENT_VACM_SUPPORT == ENABLED)
155  SnmpViewEntry viewTable[SNMP_AGENT_VIEW_TABLE_SIZE]; ///<Families of subtrees within MIB views
156 #endif
157  Socket *socket; ///<Underlying socket
158  IpAddr remoteIpAddr; ///<IP address of the remote SNMP engine
159  uint16_t remotePort; ///<Source port used by the remote SNMP engine
160  int32_t requestId; ///<Request identifier
161  SnmpMessage request; ///<SNMP request message
162  SnmpMessage response; ///<SNMP response message
163  SnmpUserEntry user; ///<Security profile of current user
164 #if (SNMP_V3_SUPPORT == ENABLED)
165  uint8_t contextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]; ///<Context engine identifier
166  size_t contextEngineLen; ///<Length of the context engine identifier
168  systime_t systemTime; ///<System time
169  int32_t engineBoots; ///<Number of times that the SNMP engine has rebooted
170  int32_t engineTime; ///<SNMP engine time
171  int32_t msgId; ///<Message identifier
172  uint64_t salt; ///<Integer initialized to a random value at boot time
173  uint8_t privParameters[8]; ///<Privacy parameters
174 #endif
175 #if (SNMP_AGENT_INFORM_SUPPORT == ENABLED)
176  SnmpAgentState informState; ///<State of the inform sending process
177  int32_t informRequestId; ///<Inform request identifier
178  systime_t informTimestamp; ///<Timestamp to manage retransmissions
179  uint_t informRetransmitCount; ///<Retransmission counter
180  OsEvent informEvent; ///<Event object
181 #if (SNMP_V3_SUPPORT == ENABLED)
182  uint8_t informContextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]; ///<Context engine identifier of the remote application
183  size_t informContextEngineLen; ///<Length of the context engine identifier
184  int32_t informEngineBoots; ///<Number of times that the remote SNMP engine has rebooted
185  int32_t informEngineTime; ///<SNMP engine time of the remote application
186  int32_t informMsgId; ///<Message identifier
187 #endif
188 #endif
189 };
190 
191 
192 //SNMP agent related functions
194 error_t snmpAgentInit(SnmpAgentContext *context, const SnmpAgentSettings *settings);
196 
197 error_t snmpAgentLoadMib(SnmpAgentContext *context, const MibModule *module);
198 error_t snmpAgentUnloadMib(SnmpAgentContext *context, const MibModule *module);
199 
201  SnmpVersion versionMin, SnmpVersion versionMax);
202 
203 error_t snmpAgentSetEngineBoots(SnmpAgentContext *context, int32_t engineBoots);
204 error_t snmpAgentGetEngineBoots(SnmpAgentContext *context, int32_t *engineBoots);
205 
207  const uint8_t *enterpriseOid, size_t enterpriseOidLen);
208 
210  const void *contextEngine, size_t contextEngineLen);
211 
213  const char_t *contextName);
214 
216  const char_t *community, SnmpAccess mode);
217 
219  const char_t *community);
220 
222  const char_t *userName, SnmpAccess mode, SnmpKeyFormat keyFormat,
223  SnmpAuthProtocol authProtocol, const void *authKey,
224  SnmpPrivProtocol privProtocol, const void *privKey);
225 
226 error_t snmpAgentDeleteUser(SnmpAgentContext *context, const char_t *userName);
227 
228 error_t snmpAgentJoinGroup(SnmpAgentContext *context, const char_t *userName,
229  SnmpSecurityModel securityModel, const char_t *groupName);
230 
232  const char_t *userName, SnmpSecurityModel securityModel);
233 
235  const char_t *groupName, SnmpSecurityModel securityModel,
236  SnmpSecurityLevel securityLevel, const char_t *contextPrefix,
237  SnmpContextMatch contextMatch, const char_t *readViewName,
238  const char_t *writeViewName, const char_t *notifyViewName);
239 
241  const char_t *groupName, SnmpSecurityModel securityModel,
242  SnmpSecurityLevel securityLevel, const char_t *contextPrefix);
243 
245  const char_t *viewName, const uint8_t *subtree, size_t subtreeLen,
246  const uint8_t *mask, size_t maskLen, SnmpViewType type);
247 
249  const char_t *viewName, const uint8_t *subtree, size_t subtreeLen);
250 
252  SnmpVersion version, const char_t *userName, uint_t genericTrapType,
253  uint_t specificTrapCode, const SnmpTrapObject *objectList, uint_t objectListSize);
254 
256  SnmpVersion version, const char_t *userName, uint_t genericTrapType,
257  uint_t specificTrapCode, const SnmpTrapObject *objectList, uint_t objectListSize);
258 
259 void snmpAgentTask(SnmpAgentContext *context);
260 
261 //C++ guard
262 #ifdef __cplusplus
263  }
264 #endif
265 
266 #endif
error_t snmpAgentDeleteCommunity(SnmpAgentContext *context, const char_t *community)
Remove a community string.
Definition: snmp_agent.c:675
uint16_t version
Definition: dtls_misc.h:163
SnmpUserEntry userTable[SNMP_AGENT_MAX_USERS]
List of users.
Definition: snmp_agent.h:150
error_t snmpAgentSetContextName(SnmpAgentContext *context, const char_t *contextName)
Set context name.
Definition: snmp_agent.c:560
uint32_t systime_t
Definition: compiler_port.h:44
char char_t
Definition: compiler_port.h:41
int32_t requestId
Request identifier.
Definition: snmp_agent.h:160
error_t snmpAgentLeaveGroup(SnmpAgentContext *context, const char_t *userName, SnmpSecurityModel securityModel)
Leave a group of users.
Definition: snmp_agent.c:1078
Socket * socket
Underlying socket.
Definition: snmp_agent.h:157
#define SNMP_AGENT_ACCESS_TABLE_SIZE
Definition: snmp_agent.h:95
SnmpUserEntry communityTable[SNMP_AGENT_MAX_COMMUNITIES]
Community strings.
Definition: snmp_agent.h:147
SnmpAccess
Access modes.
TCP/IP stack core.
int32_t msgId
Message identifier.
Definition: snmp_agent.h:171
OsMutex mutex
Mutex preventing simultaneous access to SNMP agent context.
Definition: snmp_agent.h:142
#define SNMP_MAX_OID_SIZE
Definition: snmp_common.h:114
error_t snmpAgentDeleteUser(SnmpAgentContext *context, const char_t *userName)
Remove existing user.
Definition: snmp_agent.c:931
error_t snmpAgentDeleteAccess(SnmpAgentContext *context, const char_t *groupName, SnmpSecurityModel securityModel, SnmpSecurityLevel securityLevel, const char_t *contextPrefix)
Delete an existing access policy.
Definition: snmp_agent.c:1274
SNMP inform notifications.
#define SNMP_AGENT_MAX_USERS
Definition: snmp_agent.h:81
SNMP trap notifications.
SnmpAuthProtocol
#define SNMP_MAX_CONTEXT_NAME_LEN
Definition: snmp_common.h:72
IP network address.
Definition: ip.h:57
SnmpViewType
View type.
uint8_t contextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]
Context engine identifier.
Definition: snmp_agent.h:165
SnmpVersion versionMin
Minimum version accepted by the SNMP agent.
Definition: snmp_agent.h:127
#define SNMP_MAX_CONTEXT_ENGINE_SIZE
Definition: snmp_common.h:65
Access table entry.
error_t snmpAgentLoadMib(SnmpAgentContext *context, const MibModule *module)
Load a MIB module.
Definition: snmp_agent.c:255
uint16_t trapPort
SNMP trap port number.
Definition: snmp_agent.h:130
error_t snmpAgentSetVersion(SnmpAgentContext *context, SnmpVersion versionMin, SnmpVersion versionMax)
Set minimum and maximum versions permitted.
Definition: snmp_agent.c:389
char_t type
error_t snmpAgentUnloadMib(SnmpAgentContext *context, const MibModule *module)
Unload a MIB module.
Definition: snmp_agent.c:331
OsEvent informEvent
Event object.
Definition: snmp_agent.h:180
error_t snmpAgentStart(SnmpAgentContext *context)
Start SNMP agent.
Definition: snmp_agent.c:224
SnmpMessage request
SNMP request message.
Definition: snmp_agent.h:161
int32_t informEngineBoots
Number of times that the remote SNMP engine has rebooted.
Definition: snmp_agent.h:184
User table entry.
Event object.
SnmpMessage response
SNMP response message.
Definition: snmp_agent.h:162
SnmpVersion
SNMP version identifiers.
Definition: snmp_common.h:134
int32_t engineTime
SNMP engine time.
Definition: snmp_agent.h:170
SnmpViewEntry viewTable[SNMP_AGENT_VIEW_TABLE_SIZE]
Families of subtrees within MIB views.
Definition: snmp_agent.h:155
#define Socket
Definition: socket.h:34
uint8_t mask
Definition: web_socket.h:315
View-based Access Control Model (VACM) for SNMP.
#define SNMP_AGENT_VIEW_TABLE_SIZE
Definition: snmp_agent.h:102
void snmpAgentTask(SnmpAgentContext *context)
SNMP agent task.
Definition: snmp_agent.c:1849
Group table entry.
error_t snmpAgentSendTrap(SnmpAgentContext *context, const IpAddr *destIpAddr, SnmpVersion version, const char_t *userName, uint_t genericTrapType, uint_t specificTrapCode, const SnmpTrapObject *objectList, uint_t objectListSize)
Send SNMP trap notification.
Definition: snmp_agent.c:1495
#define SNMP_AGENT_MAX_MIBS
Definition: snmp_agent.h:67
int32_t informMsgId
Message identifier.
Definition: snmp_agent.h:186
SnmpAgentState
State of the inform sending process.
uint16_t port
SNMP port number.
Definition: snmp_agent.h:129
uint8_t enterpriseOid[SNMP_MAX_OID_SIZE]
Enterprise OID.
Definition: snmp_agent.h:143
error_t snmpAgentSetEnterpriseOid(SnmpAgentContext *context, const uint8_t *enterpriseOid, size_t enterpriseOidLen)
Set enterprise OID.
Definition: snmp_agent.c:490
systime_t informTimestamp
Timestamp to manage retransmissions.
Definition: snmp_agent.h:178
SnmpContextMatch
Context match.
Definitions common to SNMP agent and SNMP manager.
int32_t informRequestId
Inform request identifier.
Definition: snmp_agent.h:177
SNMP agent context.
Definition: snmp_agent.h:139
error_t snmpAgentCreateCommunity(SnmpAgentContext *context, const char_t *community, SnmpAccess mode)
Create a new community string.
Definition: snmp_agent.c:601
SNMP agent settings.
Definition: snmp_agent.h:124
int32_t informEngineTime
SNMP engine time of the remote application.
Definition: snmp_agent.h:185
void snmpAgentGetDefaultSettings(SnmpAgentSettings *settings)
Initialize settings with default values.
Definition: snmp_agent.c:71
systime_t systemTime
System time.
Definition: snmp_agent.h:168
SnmpUserEntry user
Security profile of current user.
Definition: snmp_agent.h:163
SnmpAgentState informState
State of the inform sending process.
Definition: snmp_agent.h:176
error_t snmpAgentJoinGroup(SnmpAgentContext *context, const char_t *userName, SnmpSecurityModel securityModel, const char_t *groupName)
Join a group of users.
Definition: snmp_agent.c:985
Ipv6Addr contextPrefix
Definition: ndp.h:515
SnmpKeyFormat
SNMP key format.
error_t
Error codes.
Definition: error.h:40
SNMP message.
size_t contextEngineLen
Length of the context engine identifier.
Definition: snmp_agent.h:166
SnmpAccessEntry accessTable[SNMP_AGENT_ACCESS_TABLE_SIZE]
Access rights for groups.
Definition: snmp_agent.h:154
SnmpPrivProtocol
Ipv4Addr destIpAddr
Definition: ipcp.h:76
unsigned int uint_t
Definition: compiler_port.h:43
User-based Security Model (USM) for SNMPv3.
error_t snmpAgentInit(SnmpAgentContext *context, const SnmpAgentSettings *settings)
SNMP agent initialization.
Definition: snmp_agent.c:98
SnmpVersion versionMax
Maximum version accepted by the SNMP agent.
Definition: snmp_agent.h:128
Object descriptor for trap notifications.
uint8_t data[]
Definition: dtls_misc.h:167
#define NetInterface
Definition: net.h:34
#define SNMP_AGENT_GROUP_TABLE_SIZE
Definition: snmp_agent.h:88
IpAddr remoteIpAddr
IP address of the remote SNMP engine.
Definition: snmp_agent.h:158
error_t snmpAgentCreateUser(SnmpAgentContext *context, const char_t *userName, SnmpAccess mode, SnmpKeyFormat keyFormat, SnmpAuthProtocol authProtocol, const void *authKey, SnmpPrivProtocol privProtocol, const void *privKey)
Create a new user.
Definition: snmp_agent.c:733
error_t snmpAgentGetEngineBoots(SnmpAgentContext *context, int32_t *engineBoots)
Get the value of the snmpEngineBoots variable.
Definition: snmp_agent.c:459
uint8_t mode
Definition: sntp_client.h:143
#define SNMP_AGENT_MAX_COMMUNITIES
Definition: snmp_agent.h:74
Common definitions for MIB modules.
uint64_t salt
Integer initialized to a random value at boot time.
Definition: snmp_agent.h:172
SnmpAgentRandCallback randCallback
Random data generation callback function.
Definition: snmp_agent.h:131
SnmpSecurityModel
Security models.
Mutex object.
SnmpGroupEntry groupTable[SNMP_AGENT_GROUP_TABLE_SIZE]
List of groups.
Definition: snmp_agent.h:153
uint8_t informContextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]
Context engine identifier of the remote application.
Definition: snmp_agent.h:182
size_t informContextEngineLen
Length of the context engine identifier.
Definition: snmp_agent.h:183
error_t snmpAgentDeleteView(SnmpAgentContext *context, const char_t *viewName, const uint8_t *subtree, size_t subtreeLen)
Delete an existing MIB view.
Definition: snmp_agent.c:1436
error_t(* SnmpAgentRandCallback)(uint8_t *data, size_t length)
Random data generation callback function.
Definition: snmp_agent.h:117
#define SnmpAgentContext
Definition: snmp_agent.h:34
const MibModule * mibTable[SNMP_AGENT_MAX_MIBS]
MIB modules.
Definition: snmp_agent.h:145
MIB module.
Definition: mib_common.h:285
int32_t engineBoots
Number of times that the SNMP engine has rebooted.
Definition: snmp_agent.h:169
size_t enterpriseOidLen
Length of the enterprise OID.
Definition: snmp_agent.h:144
uint8_t length
Definition: dtls_misc.h:140
SnmpAgentSettings settings
SNMP agent settings.
Definition: snmp_agent.h:141
error_t snmpAgentCreateView(SnmpAgentContext *context, const char_t *viewName, const uint8_t *subtree, size_t subtreeLen, const uint8_t *mask, size_t maskLen, SnmpViewType type)
Create a new MIB view.
Definition: snmp_agent.c:1334
uint8_t privParameters[8]
Privacy parameters.
Definition: snmp_agent.h:173
error_t snmpAgentSendInform(SnmpAgentContext *context, const IpAddr *destIpAddr, SnmpVersion version, const char_t *userName, uint_t genericTrapType, uint_t specificTrapCode, const SnmpTrapObject *objectList, uint_t objectListSize)
Send SNMP inform request.
Definition: snmp_agent.c:1570
error_t snmpAgentSetEngineBoots(SnmpAgentContext *context, int32_t engineBoots)
Set the value of the snmpEngineBoots variable.
Definition: snmp_agent.c:420
NetInterface * interface
Network interface to configure.
Definition: snmp_agent.h:126
View table entry.
uint_t informRetransmitCount
Retransmission counter.
Definition: snmp_agent.h:179
error_t snmpAgentCreateAccess(SnmpAgentContext *context, const char_t *groupName, SnmpSecurityModel securityModel, SnmpSecurityLevel securityLevel, const char_t *contextPrefix, SnmpContextMatch contextMatch, const char_t *readViewName, const char_t *writeViewName, const char_t *notifyViewName)
Create access policy for the specified group name.
Definition: snmp_agent.c:1139
SnmpSecurityLevel
Security levels.
uint16_t remotePort
Source port used by the remote SNMP engine.
Definition: snmp_agent.h:159
char_t contextName[SNMP_MAX_CONTEXT_NAME_LEN+1]
Context name.
Definition: snmp_agent.h:167
error_t snmpAgentSetContextEngine(SnmpAgentContext *context, const void *contextEngine, size_t contextEngineLen)
Set context engine identifier.
Definition: snmp_agent.c:523