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-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_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
184 extern "C" {
185 #endif
186 
187 
188 /**
189  * @brief Message flags
190  **/
191 
192 typedef enum
193 {
198 
199 
200 /**
201  * @brief Security models
202  **/
203 
204 typedef enum
205 {
207  SNMP_SECURITY_MODEL_V1 = 1, ///<SNMPv1
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 
218 typedef enum
219 {
224 
225 
226 /**
227  * @brief Access modes
228  **/
229 
230 typedef enum
231 {
236 } SnmpAccess;
237 
238 
239 /**
240  * SNMP authentication protocols
241  **/
242 
243 typedef 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 
259 typedef 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 
271 typedef 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
277 } SnmpKeyFormat;
278 
279 
280 /**
281  * @brief SNMP secret key
282  **/
283 
284 typedef struct
285 {
287 } SnmpKey;
288 
289 
290 /**
291  * @brief User table entry
292  **/
293 
294 typedef struct
295 {
296  MibRowStatus status; ///<Status of the user
297  char_t name[SNMP_MAX_USER_NAME_LEN + 1]; ///<User name
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
309 } SnmpUserEntry;
310 
311 
312 //USM related constants
313 extern const uint8_t usmStatsUnsupportedSecLevelsObject[10];
314 extern const uint8_t usmStatsNotInTimeWindowsObject[10];
315 extern const uint8_t usmStatsUnknownUserNamesObject[10];
316 extern const uint8_t usmStatsUnknownEngineIdsObject[10];
317 extern const uint8_t usmStatsWrongDigestsObject[10];
318 extern const uint8_t usmStatsDecryptionErrorsObject[10];
319 
320 //USM related functions
322 
324  const char_t *name, size_t length);
325 
326 error_t snmpGenerateKey(SnmpAuthProtocol authProtocol, const char_t *password,
327  SnmpKey *key);
328 
329 error_t snmpLocalizeKey(SnmpAuthProtocol authProtocol, const uint8_t *engineId,
330  size_t engineIdLen, SnmpKey *key, SnmpKey *localizedKey);
331 
332 void 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 
352 const HashAlgo *snmpGetHashAlgo(SnmpAuthProtocol authProtocol);
353 size_t snmpGetMacLength(SnmpAuthProtocol authProtocol);
354 
355 
356 //C++ guard
357 #ifdef __cplusplus
358 }
359 #endif
360 
361 #endif
SnmpUserEntry * snmpFindUserEntry(SnmpAgentContext *context, const char_t *name, size_t length)
Search the user table for a given user name.
@ SNMP_SECURITY_MODEL_ANY
Any.
@ SNMP_AUTH_PROTOCOL_MD5
HMAC-MD5-96.
@ SNMP_SECURITY_MODEL_V1
SNMPv1.
uint8_t length
Definition: dtls_misc.h:149
#define SNMP_MAX_KEY_SIZE
error_t snmpGenerateKey(SnmpAuthProtocol authProtocol, const char_t *password, SnmpKey *key)
Password to key algorithm.
@ SNMP_KEY_FORMAT_LOCALIZED
Localized key.
@ SNMP_KEY_FORMAT_NONE
Unspecified key format.
error_t snmpAuthIncomingMessage(const SnmpUserEntry *user, SnmpMessage *message)
Authenticate incoming SNMP message.
@ SNMP_ACCESS_READ_WRITE
SnmpKey localizedPrivKey
Localized privacy key.
SnmpSecurityModel
Security models.
error_t snmpAuthOutgoingMessage(const SnmpUserEntry *user, SnmpMessage *message)
Authenticate outgoing SNMP message.
uint8_t delta
Definition: coap_common.h:198
void snmpRefreshEngineTime(SnmpAgentContext *context)
Refresh SNMP engine time.
@ SNMP_AUTH_PROTOCOL_SHA224
HMAC-SHA-224-128.
SnmpAccess mode
Access mode.
const uint8_t usmStatsNotInTimeWindowsObject[10]
uint8_t b[6]
Definition: dtls_misc.h:139
SHA-1 (Secure Hash Algorithm 1)
SnmpKeyFormat
SNMP key format.
@ SNMP_AUTH_PROTOCOL_SHA384
HMAC-SHA-384-256.
error_t snmpLocalizeKey(SnmpAuthProtocol authProtocol, const uint8_t *engineId, size_t engineIdLen, SnmpKey *key, SnmpKey *localizedKey)
Key localization algorithm.
SHA-512 (Secure Hash Algorithm 512)
void snmpChangeKey(const HashAlgo *hashAlgo, const uint8_t *random, const uint8_t *delta, SnmpKey *key)
Change secret key.
const uint8_t usmStatsUnknownUserNamesObject[10]
char_t name[]
@ SNMP_SECURITY_MODEL_USM
User-based security model.
User table entry.
const HashAlgo * snmpGetHashAlgo(SnmpAuthProtocol authProtocol)
Get the hash algorithm to be used for a given authentication protocol.
SNMP agent (Simple Network Management Protocol)
const uint8_t usmStatsUnknownEngineIdsObject[10]
@ SNMP_MSG_FLAG_PRIV
@ SNMP_SECURITY_MODEL_TSM
Transport security model.
size_t publicValueLen
Length of the public value.
SnmpKey localizedAuthKey
Localized authentication key.
@ SNMP_PRIV_PROTOCOL_NONE
No privacy.
error_t
Error codes.
Definition: error.h:42
@ SNMP_ACCESS_READ_ONLY
#define SNMP_MAX_USER_NAME_LEN
Definition: snmp_common.h:81
SnmpPrivProtocol
@ SNMP_KEY_FORMAT_TEXT
ASCII password.
AES (Advanced Encryption Standard)
const uint8_t usmStatsUnsupportedSecLevelsObject[10]
@ SNMP_SECURITY_LEVEL_NO_AUTH_NO_PRIV
@ SNMP_MSG_FLAG_REPORTABLE
@ SNMP_AUTH_PROTOCOL_SHA256
HMAC-SHA-256-192.
const uint8_t usmStatsDecryptionErrorsObject[10]
General definitions for cryptographic algorithms.
@ SNMP_AUTH_PROTOCOL_SHA1
HMAC-SHA-1-96.
SnmpMessageFlags
Message flags.
@ SNMP_AUTH_PROTOCOL_SHA512
HMAC-SHA-512-384.
void snmpCloneSecurityParameters(SnmpUserEntry *user, const SnmpUserEntry *cloneFromUser)
Clone security parameters.
@ SNMP_SECURITY_LEVEL_AUTH_PRIV
@ SNMP_MSG_FLAG_AUTH
SHA-384 (Secure Hash Algorithm 384)
#define SNMP_MAX_PUBLIC_VALUE_SIZE
Definition: snmp_common.h:88
@ SNMP_ACCESS_WRITE_ONLY
Cipher Block Chaining (CBC) mode.
DES (Data Encryption Standard)
MibRowStatus status
Status of the user.
SNMP secret key.
char char_t
Definition: compiler_port.h:43
error_t snmpDecryptData(const SnmpUserEntry *user, SnmpMessage *message)
Data decryption.
SHA-256 (Secure Hash Algorithm 256)
SnmpAuthProtocol authProtocol
Authentication protocol.
MibRowStatus
Row status.
Definition: mib_common.h:100
Common definitions for MIB modules.
@ SNMP_ACCESS_NONE
error_t snmpCheckSecurityParameters(const SnmpUserEntry *user, SnmpMessage *message, const uint8_t *engineId, size_t engineIdLen)
Check security parameters.
MD5 (Message-Digest Algorithm)
const uint8_t usmStatsWrongDigestsObject[10]
error_t snmpCheckEngineTime(SnmpAgentContext *context, SnmpMessage *message)
Replay protection.
SnmpKey rawAuthKey
Raw authentication key.
uint8_t message[]
Definition: chap.h:152
error_t snmpEncryptData(const SnmpUserEntry *user, SnmpMessage *message, uint64_t *salt)
Data encryption.
SnmpAuthProtocol
SNMP message.
SnmpPrivProtocol privProtocol
Privacy protocol.
#define SnmpAgentContext
Definition: snmp_agent.h:36
SnmpSecurityLevel
Security levels.
uint8_t random[32]
Definition: tls.h:1614
Common interface for hash algorithms.
Definition: crypto.h:1128
size_t snmpGetMacLength(SnmpAuthProtocol authProtocol)
Get the length of the truncated MAC for a given authentication protocol.
@ SNMP_SECURITY_MODEL_V2C
SNMPv2c.
@ SNMP_PRIV_PROTOCOL_AES
AES-128-CFB.
TCP/IP stack core.
@ SNMP_AUTH_PROTOCOL_NONE
No authentication.
Cipher Feedback (CFB) mode.
@ SNMP_KEY_FORMAT_RAW
Raw key.
SnmpUserEntry * snmpCreateUserEntry(SnmpAgentContext *context)
Create a new user entry.
SnmpKey rawPrivKey
Raw privacy key.
@ SNMP_PRIV_PROTOCOL_DES
DES-CBC.
SnmpAccess
Access modes.
@ SNMP_SECURITY_LEVEL_AUTH_NO_PRIV
SHA-224 (Secure Hash Algorithm 224)