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-2021 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 2.1.2
29 **/
30
31#ifndef _SNMP_AGENT_H
32#define _SNMP_AGENT_H
33
34//Forward declaration of SnmpAgentContext structure
36#define SnmpAgentContext struct _SnmpAgentContext
37
38//Dependencies
39#include "core/net.h"
40#include "snmp/snmp_common.h"
44#include "snmp/snmp_agent_usm.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
111extern "C" {
112#endif
113
114
115/**
116 * @brief Random data generation callback function
117 **/
118
119typedef error_t (*SnmpAgentRandCallback)(uint8_t *data, size_t length);
120
121
122/**
123 * @brief SNMP agent settings
124 **/
125
126typedef 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 bool_t running; ///<Operational state of the SNMP agent
145 bool_t stop; ///<Stop request
146 OsMutex mutex; ///<Mutex preventing simultaneous access to SNMP agent context
147 OsEvent event; ///<Event object used to poll the underlying socket
148 OsTaskId taskId; ///<Task identifier
149#if (OS_STATIC_TASK_SUPPORT == ENABLED)
150 OsTaskTcb taskTcb; ///<Task control block
152#endif
153 uint8_t enterpriseOid[SNMP_MAX_OID_SIZE]; ///<Enterprise OID
154 size_t enterpriseOidLen; ///<Length of the enterprise OID
155 const MibModule *mibTable[SNMP_AGENT_MAX_MIBS]; ///<MIB modules
156#if (SNMP_V1_SUPPORT == ENABLED || SNMP_V2C_SUPPORT == ENABLED)
158#endif
159#if (SNMP_V3_SUPPORT == ENABLED)
161#endif
162#if (SNMP_AGENT_VACM_SUPPORT == ENABLED)
165 SnmpViewEntry viewTable[SNMP_AGENT_VIEW_TABLE_SIZE]; ///<Families of subtrees within MIB views
166#endif
167 Socket *socket; ///<Underlying socket
168 NetInterface *localInterface; ///<Network interface the SNMP request was received on
169 IpAddr localIpAddr; ///<Destination IP address of the received SNMP request
170 IpAddr remoteIpAddr; ///<Source IP address of the received SNMP request
171 uint16_t remotePort; ///<Source port of the received SNMP request
172 int32_t requestId; ///<Request identifier
173 SnmpMessage request; ///<SNMP request message
174 SnmpMessage response; ///<SNMP response message
175 SnmpUserEntry user; ///<Security profile of current user
176#if (SNMP_V3_SUPPORT == ENABLED)
177 uint8_t contextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]; ///<Context engine identifier
178 size_t contextEngineLen; ///<Length of the context engine identifier
180 systime_t systemTime; ///<System time
181 int32_t engineBoots; ///<Number of times that the SNMP engine has rebooted
182 int32_t engineTime; ///<SNMP engine time
183 int32_t msgId; ///<Message identifier
184 uint64_t salt; ///<Integer initialized to a random value at boot time
185 uint8_t privParameters[8]; ///<Privacy parameters
186#endif
187#if (SNMP_AGENT_INFORM_SUPPORT == ENABLED)
188 SnmpAgentState informState; ///<State of the inform sending process
189 int32_t informRequestId; ///<Inform request identifier
190 systime_t informTimestamp; ///<Timestamp to manage retransmissions
191 uint_t informRetransmitCount; ///<Retransmission counter
192 OsEvent informEvent; ///<Event object
193#if (SNMP_V3_SUPPORT == ENABLED)
194 uint8_t informContextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]; ///<Context engine identifier of the remote application
195 size_t informContextEngineLen; ///<Length of the context engine identifier
196 int32_t informEngineBoots; ///<Number of times that the remote SNMP engine has rebooted
197 int32_t informEngineTime; ///<SNMP engine time of the remote application
198 int32_t informMsgId; ///<Message identifier
199#endif
200#endif
201};
202
203
204//SNMP agent related functions
206
208 const SnmpAgentSettings *settings);
209
212
213error_t snmpAgentLoadMib(SnmpAgentContext *context, const MibModule *module);
215
217 SnmpVersion versionMin, SnmpVersion versionMax);
218
219error_t snmpAgentSetEngineBoots(SnmpAgentContext *context, int32_t engineBoots);
220error_t snmpAgentGetEngineBoots(SnmpAgentContext *context, int32_t *engineBoots);
221
223 const uint8_t *enterpriseOid, size_t enterpriseOidLen);
224
226 const void *contextEngine, size_t contextEngineLen);
227
229 const char_t *contextName);
230
232 const char_t *community, SnmpAccess mode);
233
235 const char_t *community);
236
238 const char_t *userName, SnmpAccess mode, SnmpKeyFormat keyFormat,
239 SnmpAuthProtocol authProtocol, const void *authKey,
240 SnmpPrivProtocol privProtocol, const void *privKey);
241
242error_t snmpAgentDeleteUser(SnmpAgentContext *context, const char_t *userName);
243
244error_t snmpAgentJoinGroup(SnmpAgentContext *context, const char_t *userName,
245 SnmpSecurityModel securityModel, const char_t *groupName);
246
248 const char_t *userName, SnmpSecurityModel securityModel);
249
251 const char_t *groupName, SnmpSecurityModel securityModel,
252 SnmpSecurityLevel securityLevel, const char_t *contextPrefix,
253 SnmpContextMatch contextMatch, const char_t *readViewName,
254 const char_t *writeViewName, const char_t *notifyViewName);
255
257 const char_t *groupName, SnmpSecurityModel securityModel,
258 SnmpSecurityLevel securityLevel, const char_t *contextPrefix);
259
261 const char_t *viewName, const uint8_t *subtree, size_t subtreeLen,
262 const uint8_t *mask, size_t maskLen, SnmpViewType type);
263
265 const char_t *viewName, const uint8_t *subtree, size_t subtreeLen);
266
268 const IpAddr *destIpAddr, SnmpVersion version, const char_t *userName,
269 uint_t genericTrapType, uint_t specificTrapCode,
270 const SnmpTrapObject *objectList, uint_t objectListSize);
271
273 const IpAddr *destIpAddr, SnmpVersion version, const char_t *userName,
274 uint_t genericTrapType, uint_t specificTrapCode,
275 const SnmpTrapObject *objectList, uint_t objectListSize);
276
277void snmpAgentTask(SnmpAgentContext *context);
278
279void snmpAgentDeinit(SnmpAgentContext *context);
280
281//C++ guard
282#ifdef __cplusplus
283}
284#endif
285
286#endif
unsigned int uint_t
Definition: compiler_port.h:45
char char_t
Definition: compiler_port.h:43
int bool_t
Definition: compiler_port.h:49
uint32_t systime_t
Definition: compiler_port.h:46
uint16_t version
Definition: dtls_misc.h:172
error_t
Error codes.
Definition: error.h:43
Ipv4Addr destIpAddr
Definition: ipcp.h:78
Common definitions for MIB modules.
Ipv6Addr contextPrefix
Definition: ndp.h:517
TCP/IP stack core.
#define NetInterface
Definition: net.h:36
uint8_t mode
Definition: ntp_common.h:149
uint32_t OsStackType
Stack data type.
thread_t * OsTaskId
Task identifier.
char_t type
uint8_t data[]
Definition: sftp_common.h:228
uint32_t length
Definition: sftp_common.h:214
error_t snmpAgentLoadMib(SnmpAgentContext *context, const MibModule *module)
Load a MIB module.
Definition: snmp_agent.c:346
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:1662
error_t snmpAgentSetEngineBoots(SnmpAgentContext *context, int32_t engineBoots)
Set the value of the snmpEngineBoots variable.
Definition: snmp_agent.c:511
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:1425
error_t snmpAgentSetEnterpriseOid(SnmpAgentContext *context, const uint8_t *enterpriseOid, size_t enterpriseOidLen)
Set enterprise OID.
Definition: snmp_agent.c:581
error_t snmpAgentCreateCommunity(SnmpAgentContext *context, const char_t *community, SnmpAccess mode)
Create a new community string.
Definition: snmp_agent.c:692
error_t snmpAgentDeleteUser(SnmpAgentContext *context, const char_t *userName)
Remove existing user.
Definition: snmp_agent.c:1022
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:1527
error_t(* SnmpAgentRandCallback)(uint8_t *data, size_t length)
Random data generation callback function.
Definition: snmp_agent.h:119
#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:824
#define SnmpAgentContext
Definition: snmp_agent.h:36
#define SNMP_AGENT_GROUP_TABLE_SIZE
Definition: snmp_agent.h:90
#define SNMP_AGENT_STACK_SIZE
Definition: snmp_agent.h:57
void snmpAgentGetDefaultSettings(SnmpAgentSettings *settings)
Initialize settings with default values.
Definition: snmp_agent.c:73
error_t snmpAgentSetContextEngine(SnmpAgentContext *context, const void *contextEngine, size_t contextEngineLen)
Set context engine identifier.
Definition: snmp_agent.c:614
error_t snmpAgentDeleteCommunity(SnmpAgentContext *context, const char_t *community)
Remove a community string.
Definition: snmp_agent.c:766
#define SNMP_AGENT_MAX_MIBS
Definition: snmp_agent.h:69
error_t snmpAgentLeaveGroup(SnmpAgentContext *context, const char_t *userName, SnmpSecurityModel securityModel)
Leave a group of users.
Definition: snmp_agent.c:1169
error_t snmpAgentInit(SnmpAgentContext *context, const SnmpAgentSettings *settings)
SNMP agent initialization.
Definition: snmp_agent.c:100
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:1586
error_t snmpAgentStop(SnmpAgentContext *context)
Stop SNMP agent.
Definition: snmp_agent.c:306
#define SNMP_AGENT_MAX_USERS
Definition: snmp_agent.h:83
void snmpAgentTask(SnmpAgentContext *context)
SNMP agent task.
Definition: snmp_agent.c:1942
#define SNMP_AGENT_ACCESS_TABLE_SIZE
Definition: snmp_agent.h:97
error_t snmpAgentGetEngineBoots(SnmpAgentContext *context, int32_t *engineBoots)
Get the value of the snmpEngineBoots variable.
Definition: snmp_agent.c:550
error_t snmpAgentSetVersion(SnmpAgentContext *context, SnmpVersion versionMin, SnmpVersion versionMax)
Set minimum and maximum versions permitted.
Definition: snmp_agent.c:480
error_t snmpAgentJoinGroup(SnmpAgentContext *context, const char_t *userName, SnmpSecurityModel securityModel, const char_t *groupName)
Join a group of users.
Definition: snmp_agent.c:1076
void snmpAgentDeinit(SnmpAgentContext *context)
Release SNMP agent context.
Definition: snmp_agent.c:2071
error_t snmpAgentUnloadMib(SnmpAgentContext *context, const MibModule *module)
Unload a MIB module.
Definition: snmp_agent.c:422
error_t snmpAgentSetContextName(SnmpAgentContext *context, const char_t *contextName)
Set context name.
Definition: snmp_agent.c:651
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:1230
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:1365
#define SNMP_AGENT_MAX_COMMUNITIES
Definition: snmp_agent.h:76
error_t snmpAgentStart(SnmpAgentContext *context)
Start SNMP agent.
Definition: snmp_agent.c:211
SNMP inform notifications.
SnmpAgentState
State of the inform sending process.
SNMP trap notifications.
User-based Security Model (USM) for SNMPv3.
SnmpAuthProtocol
SnmpKeyFormat
SNMP key format.
SnmpAccess
Access modes.
SnmpSecurityLevel
Security levels.
SnmpSecurityModel
Security models.
SnmpPrivProtocol
View-based Access Control Model (VACM) for SNMP.
SnmpContextMatch
Context match.
SnmpViewType
View type.
Definitions common to SNMP agent and SNMP manager.
#define SNMP_MAX_CONTEXT_ENGINE_SIZE
Definition: snmp_common.h:67
#define SNMP_MAX_CONTEXT_NAME_LEN
Definition: snmp_common.h:74
#define SNMP_MAX_OID_SIZE
Definition: snmp_common.h:116
SnmpVersion
SNMP version identifiers.
Definition: snmp_common.h:137
#define Socket
Definition: socket.h:36
SNMP agent context.
Definition: snmp_agent.h:142
IpAddr remoteIpAddr
Source IP address of the received SNMP request.
Definition: snmp_agent.h:170
int32_t requestId
Request identifier.
Definition: snmp_agent.h:172
uint8_t enterpriseOid[SNMP_MAX_OID_SIZE]
Enterprise OID.
Definition: snmp_agent.h:153
int32_t informRequestId
Inform request identifier.
Definition: snmp_agent.h:189
SnmpAgentState informState
State of the inform sending process.
Definition: snmp_agent.h:188
SnmpMessage response
SNMP response message.
Definition: snmp_agent.h:174
IpAddr localIpAddr
Destination IP address of the received SNMP request.
Definition: snmp_agent.h:169
uint16_t remotePort
Source port of the received SNMP request.
Definition: snmp_agent.h:171
systime_t informTimestamp
Timestamp to manage retransmissions.
Definition: snmp_agent.h:190
OsEvent informEvent
Event object.
Definition: snmp_agent.h:192
SnmpMessage request
SNMP request message.
Definition: snmp_agent.h:173
SnmpUserEntry userTable[SNMP_AGENT_MAX_USERS]
List of users.
Definition: snmp_agent.h:160
bool_t stop
Stop request.
Definition: snmp_agent.h:145
char_t contextName[SNMP_MAX_CONTEXT_NAME_LEN+1]
Context name.
Definition: snmp_agent.h:179
uint8_t contextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]
Context engine identifier.
Definition: snmp_agent.h:177
size_t contextEngineLen
Length of the context engine identifier.
Definition: snmp_agent.h:178
int32_t engineBoots
Number of times that the SNMP engine has rebooted.
Definition: snmp_agent.h:181
SnmpAccessEntry accessTable[SNMP_AGENT_ACCESS_TABLE_SIZE]
Access rights for groups.
Definition: snmp_agent.h:164
int32_t engineTime
SNMP engine time.
Definition: snmp_agent.h:182
int32_t msgId
Message identifier.
Definition: snmp_agent.h:183
OsTaskId taskId
Task identifier.
Definition: snmp_agent.h:148
uint64_t salt
Integer initialized to a random value at boot time.
Definition: snmp_agent.h:184
size_t informContextEngineLen
Length of the context engine identifier.
Definition: snmp_agent.h:195
bool_t running
Operational state of the SNMP agent.
Definition: snmp_agent.h:144
uint_t informRetransmitCount
Retransmission counter.
Definition: snmp_agent.h:191
systime_t systemTime
System time.
Definition: snmp_agent.h:180
uint8_t informContextEngine[SNMP_MAX_CONTEXT_ENGINE_SIZE]
Context engine identifier of the remote application.
Definition: snmp_agent.h:194
SnmpUserEntry user
Security profile of current user.
Definition: snmp_agent.h:175
SnmpViewEntry viewTable[SNMP_AGENT_VIEW_TABLE_SIZE]
Families of subtrees within MIB views.
Definition: snmp_agent.h:165
OsTaskTcb taskTcb
Task control block.
Definition: snmp_agent.h:150
int32_t informMsgId
Message identifier.
Definition: snmp_agent.h:198
uint8_t privParameters[8]
Privacy parameters.
Definition: snmp_agent.h:185
OsStackType taskStack[SNMP_AGENT_STACK_SIZE]
Task stack.
Definition: snmp_agent.h:151
Socket * socket
Underlying socket.
Definition: snmp_agent.h:167
NetInterface * localInterface
Network interface the SNMP request was received on.
Definition: snmp_agent.h:168
OsEvent event
Event object used to poll the underlying socket.
Definition: snmp_agent.h:147
int32_t informEngineTime
SNMP engine time of the remote application.
Definition: snmp_agent.h:197
int32_t informEngineBoots
Number of times that the remote SNMP engine has rebooted.
Definition: snmp_agent.h:196
size_t enterpriseOidLen
Length of the enterprise OID.
Definition: snmp_agent.h:154
const MibModule * mibTable[SNMP_AGENT_MAX_MIBS]
MIB modules.
Definition: snmp_agent.h:155
OsMutex mutex
Mutex preventing simultaneous access to SNMP agent context.
Definition: snmp_agent.h:146
SnmpGroupEntry groupTable[SNMP_AGENT_GROUP_TABLE_SIZE]
List of groups.
Definition: snmp_agent.h:163
SnmpUserEntry communityTable[SNMP_AGENT_MAX_COMMUNITIES]
Community strings.
Definition: snmp_agent.h:157
SnmpAgentSettings settings
SNMP agent settings.
Definition: snmp_agent.h:143
IP network address.
Definition: ip.h:79
MIB module.
Definition: mib_common.h:288
Event object.
Mutex object.
Task control block.
Access table entry.
SNMP agent settings.
Definition: snmp_agent.h:127
SnmpVersion versionMin
Minimum version accepted by the SNMP agent.
Definition: snmp_agent.h:129
SnmpVersion versionMax
Maximum version accepted by the SNMP agent.
Definition: snmp_agent.h:130
uint16_t trapPort
SNMP trap port number.
Definition: snmp_agent.h:132
uint16_t port
SNMP port number.
Definition: snmp_agent.h:131
SnmpAgentRandCallback randCallback
Random data generation callback function.
Definition: snmp_agent.h:133
NetInterface * interface
Network interface to configure.
Definition: snmp_agent.h:128
Group table entry.
SNMP message.
Object descriptor for trap notifications.
User table entry.
View table entry.
uint8_t mask
Definition: web_socket.h:317