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