snmp_agent_usm.h
Go to the documentation of this file.
1/**
2 * @file snmp_agent_usm.h
3 * @brief User-based Security Model (USM) for SNMPv3
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_USM_H
32#define _SNMP_AGENT_USM_H
33
34//Dependencies
35#include "core/net.h"
36#include "snmp/snmp_agent.h"
37#include "mibs/mib_common.h"
38#include "core/crypto.h"
39
40//Time window for replay protection
41#ifndef SNMP_TIME_WINDOW
42 #define SNMP_TIME_WINDOW 150
43#elif (SNMP_TIME_WINDOW < 1)
44 #error SNMP_TIME_WINDOW parameter is not valid
45#endif
46
47//MD5 authentication support
48#ifndef SNMP_MD5_SUPPORT
49 #define SNMP_MD5_SUPPORT ENABLED
50#elif (SNMP_MD5_SUPPORT != ENABLED && SNMP_MD5_SUPPORT != DISABLED)
51 #error SNMP_MD5_SUPPORT parameter is not valid
52#endif
53
54//SHA-1 authentication support
55#ifndef SNMP_SHA1_SUPPORT
56 #define SNMP_SHA1_SUPPORT ENABLED
57#elif (SNMP_SHA1_SUPPORT != ENABLED && SNMP_SHA1_SUPPORT != DISABLED)
58 #error SNMP_SHA1_SUPPORT parameter is not valid
59#endif
60
61//SHA-224 authentication support
62#ifndef SNMP_SHA224_SUPPORT
63 #define SNMP_SHA224_SUPPORT DISABLED
64#elif (SNMP_SHA224_SUPPORT != ENABLED && SNMP_SHA224_SUPPORT != DISABLED)
65 #error SNMP_SHA224_SUPPORT parameter is not valid
66#endif
67
68//SHA-256 authentication support
69#ifndef SNMP_SHA256_SUPPORT
70 #define SNMP_SHA256_SUPPORT DISABLED
71#elif (SNMP_SHA256_SUPPORT != ENABLED && SNMP_SHA256_SUPPORT != DISABLED)
72 #error SNMP_SHA256_SUPPORT parameter is not valid
73#endif
74
75//SHA-384 authentication support
76#ifndef SNMP_SHA384_SUPPORT
77 #define SNMP_SHA384_SUPPORT DISABLED
78#elif (SNMP_SHA384_SUPPORT != ENABLED && SNMP_SHA384_SUPPORT != DISABLED)
79 #error SNMP_SHA384_SUPPORT parameter is not valid
80#endif
81
82//SHA-512 authentication support
83#ifndef SNMP_SHA512_SUPPORT
84 #define SNMP_SHA512_SUPPORT DISABLED
85#elif (SNMP_SHA512_SUPPORT != ENABLED && SNMP_SHA512_SUPPORT != DISABLED)
86 #error SNMP_SHA512_SUPPORT parameter is not valid
87#endif
88
89//DES encryption support
90#ifndef SNMP_DES_SUPPORT
91 #define SNMP_DES_SUPPORT ENABLED
92#elif (SNMP_DES_SUPPORT != ENABLED && SNMP_DES_SUPPORT != DISABLED)
93 #error SNMP_DES_SUPPORT parameter is not valid
94#endif
95
96//AES encryption support
97#ifndef SNMP_AES_SUPPORT
98 #define SNMP_AES_SUPPORT ENABLED
99#elif (SNMP_AES_SUPPORT != ENABLED && SNMP_AES_SUPPORT != DISABLED)
100 #error SNMP_AES_SUPPORT parameter is not valid
101#endif
102
103//Support for MD5 authentication?
104#if (SNMP_MD5_SUPPORT == ENABLED)
105 #include "hash/md5.h"
106#endif
107
108//Support for SHA-1 authentication?
109#if (SNMP_SHA1_SUPPORT == ENABLED)
110 #include "hash/sha1.h"
111#endif
112
113//Support for SHA-224 authentication?
114#if (SNMP_SHA224_SUPPORT == ENABLED)
115 #include "hash/sha224.h"
116#endif
117
118//Support for SHA-256 authentication?
119#if (SNMP_SHA256_SUPPORT == ENABLED)
120 #include "hash/sha256.h"
121#endif
122
123//Support for SHA-384 authentication?
124#if (SNMP_SHA384_SUPPORT == ENABLED)
125 #include "hash/sha384.h"
126#endif
127
128//Support for SHA-512 authentication?
129#if (SNMP_SHA512_SUPPORT == ENABLED)
130 #include "hash/sha512.h"
131#endif
132
133//Support for DES encryption?
134#if (SNMP_DES_SUPPORT == ENABLED)
135 #include "cipher/des.h"
136 #include "cipher_mode/cbc.h"
137#endif
138
139//Support for AES encryption ?
140#if (SNMP_AES_SUPPORT == ENABLED)
141 #include "cipher/aes.h"
142 #include "cipher_mode/cfb.h"
143#endif
144
145//Maximum size for authentication and privacy keys
146#if (SNMP_SHA512_SUPPORT == ENABLED)
147 #define SNMP_MAX_KEY_SIZE 64
148#elif (SNMP_SHA384_SUPPORT == ENABLED)
149 #define SNMP_MAX_KEY_SIZE 48
150#elif (SNMP_SHA256_SUPPORT == ENABLED)
151 #define SNMP_MAX_KEY_SIZE 32
152#elif (SNMP_SHA224_SUPPORT == ENABLED)
153 #define SNMP_MAX_KEY_SIZE 28
154#elif (SNMP_SHA1_SUPPORT == ENABLED)
155 #define SNMP_MAX_KEY_SIZE 20
156#else
157 #define SNMP_MAX_KEY_SIZE 16
158#endif
159
160//Maximum size for truncated MACs
161#if (SNMP_SHA512_SUPPORT == ENABLED)
162 #define SNMP_MAX_TRUNCATED_MAC_SIZE 48
163#elif (SNMP_SHA384_SUPPORT == ENABLED)
164 #define SNMP_MAX_TRUNCATED_MAC_SIZE 32
165#elif (SNMP_SHA256_SUPPORT == ENABLED)
166 #define SNMP_MAX_TRUNCATED_MAC_SIZE 24
167#elif (SNMP_SHA224_SUPPORT == ENABLED)
168 #define SNMP_MAX_TRUNCATED_MAC_SIZE 16
169#elif (SNMP_SHA1_SUPPORT == ENABLED)
170 #define SNMP_MAX_TRUNCATED_MAC_SIZE 12
171#else
172 #define SNMP_MAX_TRUNCATED_MAC_SIZE 12
173#endif
174
175//SNMP message encryption overhead
176#if (SNMP_DES_SUPPORT == ENABLED)
177 #define SNMP_MSG_ENCRYPTION_OVERHEAD 8
178#else
179 #define SNMP_MSG_ENCRYPTION_OVERHEAD 0
180#endif
181
182//C++ guard
183#ifdef __cplusplus
184extern "C" {
185#endif
186
187
188/**
189 * @brief Message flags
190 **/
191
192typedef enum
193{
198
199
200/**
201 * @brief Security models
202 **/
203
204typedef enum
205{
208 SNMP_SECURITY_MODEL_V2C = 2, ///<SNMPv2c
209 SNMP_SECURITY_MODEL_USM = 3, ///<User-based security model
210 SNMP_SECURITY_MODEL_TSM = 4 ///<Transport security model
212
213
214/**
215 * @brief Security levels
216 **/
217
218typedef enum
219{
224
225
226/**
227 * @brief Access modes
228 **/
229
230typedef enum
231{
237
238
239/**
240 * SNMP authentication protocols
241 **/
242
243typedef enum
244{
245 SNMP_AUTH_PROTOCOL_NONE = 0, ///<No authentication
246 SNMP_AUTH_PROTOCOL_MD5 = 1, ///<HMAC-MD5-96
247 SNMP_AUTH_PROTOCOL_SHA1 = 2, ///<HMAC-SHA-1-96
248 SNMP_AUTH_PROTOCOL_SHA224 = 3, ///<HMAC-SHA-224-128
249 SNMP_AUTH_PROTOCOL_SHA256 = 4, ///<HMAC-SHA-256-192
250 SNMP_AUTH_PROTOCOL_SHA384 = 5, ///<HMAC-SHA-384-256
251 SNMP_AUTH_PROTOCOL_SHA512 = 6 ///<HMAC-SHA-512-384
253
254
255/**
256 * SNMP privacy protocols
257 **/
258
259typedef enum
260{
261 SNMP_PRIV_PROTOCOL_NONE = 0, ///<No privacy
262 SNMP_PRIV_PROTOCOL_DES = 1, ///<DES-CBC
263 SNMP_PRIV_PROTOCOL_AES = 2 ///<AES-128-CFB
265
266
267/**
268 * @brief SNMP key format
269 **/
270
271typedef enum
272{
273 SNMP_KEY_FORMAT_NONE = 0, ///<Unspecified key format
274 SNMP_KEY_FORMAT_TEXT = 1, ///<ASCII password
275 SNMP_KEY_FORMAT_RAW = 2, ///<Raw key
276 SNMP_KEY_FORMAT_LOCALIZED = 3 ///<Localized key
278
279
280/**
281 * @brief SNMP secret key
282 **/
283
284typedef struct
285{
287} SnmpKey;
288
289
290/**
291 * @brief User table entry
292 **/
293
294typedef struct
295{
296 MibRowStatus status; ///<Status of the user
298 SnmpAccess mode; ///<Access mode
299#if (SNMP_V3_SUPPORT == ENABLED)
300 SnmpAuthProtocol authProtocol; ///<Authentication protocol
301 SnmpKey rawAuthKey; ///<Raw authentication key
302 SnmpKey localizedAuthKey; ///<Localized authentication key
303 SnmpPrivProtocol privProtocol; ///<Privacy protocol
304 SnmpKey rawPrivKey; ///<Raw privacy key
305 SnmpKey localizedPrivKey; ///<Localized privacy key
306 uint8_t publicValue[SNMP_MAX_PUBLIC_VALUE_SIZE]; ///<Public value
307 size_t publicValueLen; ///<Length of the public value
308#endif
310
311
312//USM related constants
313extern const uint8_t usmStatsUnsupportedSecLevelsObject[10];
314extern const uint8_t usmStatsNotInTimeWindowsObject[10];
315extern const uint8_t usmStatsUnknownUserNamesObject[10];
316extern const uint8_t usmStatsUnknownEngineIdsObject[10];
317extern const uint8_t usmStatsWrongDigestsObject[10];
318extern const uint8_t usmStatsDecryptionErrorsObject[10];
319
320//USM related functions
322
324 const char_t *name, size_t length);
325
326error_t snmpGenerateKey(SnmpAuthProtocol authProtocol, const char_t *password,
327 SnmpKey *key);
328
329error_t snmpLocalizeKey(SnmpAuthProtocol authProtocol, const uint8_t *engineId,
330 size_t engineIdLen, SnmpKey *key, SnmpKey *localizedKey);
331
332void snmpChangeKey(const HashAlgo *hashAlgo, const uint8_t *random,
333 const uint8_t *delta, SnmpKey *key);
334
336 const SnmpUserEntry *cloneFromUser);
337
339 SnmpMessage *message, const uint8_t *engineId, size_t engineIdLen);
340
343
346
348 uint64_t *salt);
349
351
352const HashAlgo *snmpGetHashAlgo(SnmpAuthProtocol authProtocol);
353size_t snmpGetMacLength(SnmpAuthProtocol authProtocol);
354
355
356//C++ guard
357#ifdef __cplusplus
358}
359#endif
360
361#endif
AES (Advanced Encryption Standard)
Cipher Block Chaining (CBC) mode.
Cipher Feedback (CFB) mode.
uint8_t message[]
Definition: chap.h:152
uint8_t delta
Definition: coap_common.h:192
char char_t
Definition: compiler_port.h:43
General definitions for cryptographic algorithms.
DES (Data Encryption Standard)
uint8_t b[6]
Definition: dtls_misc.h:139
error_t
Error codes.
Definition: error.h:43
MD5 (Message-Digest Algorithm)
Common definitions for MIB modules.
MibRowStatus
Row status.
Definition: mib_common.h:101
TCP/IP stack core.
char_t name[]
uint32_t length
Definition: sftp_common.h:214
SHA-1 (Secure Hash Algorithm 1)
SHA-224 (Secure Hash Algorithm 224)
SHA-256 (Secure Hash Algorithm 256)
SHA-384 (Secure Hash Algorithm 384)
SHA-512 (Secure Hash Algorithm 512)
SNMP agent (Simple Network Management Protocol)
#define SnmpAgentContext
Definition: snmp_agent.h:36
SnmpAuthProtocol
@ SNMP_AUTH_PROTOCOL_SHA512
HMAC-SHA-512-384.
@ SNMP_AUTH_PROTOCOL_NONE
No authentication.
@ SNMP_AUTH_PROTOCOL_SHA224
HMAC-SHA-224-128.
@ SNMP_AUTH_PROTOCOL_MD5
HMAC-MD5-96.
@ SNMP_AUTH_PROTOCOL_SHA384
HMAC-SHA-384-256.
@ SNMP_AUTH_PROTOCOL_SHA1
HMAC-SHA-1-96.
@ SNMP_AUTH_PROTOCOL_SHA256
HMAC-SHA-256-192.
void snmpChangeKey(const HashAlgo *hashAlgo, const uint8_t *random, const uint8_t *delta, SnmpKey *key)
Change secret key.
error_t snmpLocalizeKey(SnmpAuthProtocol authProtocol, const uint8_t *engineId, size_t engineIdLen, SnmpKey *key, SnmpKey *localizedKey)
Key localization algorithm.
#define SNMP_MAX_KEY_SIZE
SnmpUserEntry * snmpCreateUserEntry(SnmpAgentContext *context)
Create a new user entry.
SnmpKeyFormat
SNMP key format.
@ SNMP_KEY_FORMAT_TEXT
ASCII password.
@ SNMP_KEY_FORMAT_NONE
Unspecified key format.
@ SNMP_KEY_FORMAT_LOCALIZED
Localized key.
@ SNMP_KEY_FORMAT_RAW
Raw key.
const uint8_t usmStatsUnknownUserNamesObject[10]
error_t snmpEncryptData(const SnmpUserEntry *user, SnmpMessage *message, uint64_t *salt)
Data encryption.
error_t snmpGenerateKey(SnmpAuthProtocol authProtocol, const char_t *password, SnmpKey *key)
Password to key algorithm.
SnmpAccess
Access modes.
@ SNMP_ACCESS_READ_ONLY
@ SNMP_ACCESS_WRITE_ONLY
@ SNMP_ACCESS_READ_WRITE
@ SNMP_ACCESS_NONE
error_t snmpCheckEngineTime(SnmpAgentContext *context, SnmpMessage *message)
Replay protection.
size_t snmpGetMacLength(SnmpAuthProtocol authProtocol)
Get the length of the truncated MAC for a given authentication protocol.
SnmpSecurityLevel
Security levels.
@ SNMP_SECURITY_LEVEL_AUTH_PRIV
@ SNMP_SECURITY_LEVEL_AUTH_NO_PRIV
@ SNMP_SECURITY_LEVEL_NO_AUTH_NO_PRIV
SnmpSecurityModel
Security models.
@ SNMP_SECURITY_MODEL_USM
User-based security model.
@ SNMP_SECURITY_MODEL_ANY
Any.
@ SNMP_SECURITY_MODEL_TSM
Transport security model.
@ SNMP_SECURITY_MODEL_V2C
SNMPv2c.
@ SNMP_SECURITY_MODEL_V1
SNMPv1.
const HashAlgo * snmpGetHashAlgo(SnmpAuthProtocol authProtocol)
Get the hash algorithm to be used for a given authentication protocol.
const uint8_t usmStatsUnsupportedSecLevelsObject[10]
const uint8_t usmStatsNotInTimeWindowsObject[10]
error_t snmpDecryptData(const SnmpUserEntry *user, SnmpMessage *message)
Data decryption.
void snmpRefreshEngineTime(SnmpAgentContext *context)
Refresh SNMP engine time.
void snmpCloneSecurityParameters(SnmpUserEntry *user, const SnmpUserEntry *cloneFromUser)
Clone security parameters.
SnmpUserEntry * snmpFindUserEntry(SnmpAgentContext *context, const char_t *name, size_t length)
Search the user table for a given user name.
const uint8_t usmStatsUnknownEngineIdsObject[10]
error_t snmpAuthIncomingMessage(const SnmpUserEntry *user, SnmpMessage *message)
Authenticate incoming SNMP message.
error_t snmpCheckSecurityParameters(const SnmpUserEntry *user, SnmpMessage *message, const uint8_t *engineId, size_t engineIdLen)
Check security parameters.
const uint8_t usmStatsDecryptionErrorsObject[10]
error_t snmpAuthOutgoingMessage(const SnmpUserEntry *user, SnmpMessage *message)
Authenticate outgoing SNMP message.
SnmpPrivProtocol
@ SNMP_PRIV_PROTOCOL_DES
DES-CBC.
@ SNMP_PRIV_PROTOCOL_NONE
No privacy.
@ SNMP_PRIV_PROTOCOL_AES
AES-128-CFB.
const uint8_t usmStatsWrongDigestsObject[10]
SnmpMessageFlags
Message flags.
@ SNMP_MSG_FLAG_PRIV
@ SNMP_MSG_FLAG_REPORTABLE
@ SNMP_MSG_FLAG_AUTH
#define SNMP_MAX_PUBLIC_VALUE_SIZE
Definition: snmp_common.h:88
#define SNMP_MAX_USER_NAME_LEN
Definition: snmp_common.h:81
Common interface for hash algorithms.
Definition: crypto.h:852
SNMP secret key.
SNMP message.
User table entry.
MibRowStatus status
Status of the user.
SnmpKey localizedAuthKey
Localized authentication key.
SnmpPrivProtocol privProtocol
Privacy protocol.
SnmpAuthProtocol authProtocol
Authentication protocol.
SnmpKey localizedPrivKey
Localized privacy key.
SnmpAccess mode
Access mode.
size_t publicValueLen
Length of the public value.
SnmpKey rawPrivKey
Raw privacy key.
SnmpKey rawAuthKey
Raw authentication key.
uint8_t random[32]
Definition: tls.h:1647