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