snmp_agent_usm.h File Reference

User-based Security Model (USM) for SNMPv3. More...

#include "core/net.h"
#include "snmp/snmp_agent.h"
#include "mibs/mib_common.h"
#include "core/crypto.h"
#include "hash/md5.h"
#include "hash/sha1.h"
#include "hash/sha224.h"
#include "hash/sha256.h"
#include "hash/sha384.h"
#include "hash/sha512.h"
#include "cipher/des.h"
#include "cipher_mode/cbc.h"
#include "cipher/aes.h"
#include "cipher_mode/cfb.h"

Go to the source code of this file.

Data Structures

struct  SnmpKey
 SNMP secret key. More...
 
struct  SnmpUserEntry
 User table entry. More...
 

Macros

#define SNMP_TIME_WINDOW   150
 
#define SNMP_MD5_SUPPORT   ENABLED
 
#define SNMP_SHA1_SUPPORT   ENABLED
 
#define SNMP_SHA224_SUPPORT   DISABLED
 
#define SNMP_SHA256_SUPPORT   DISABLED
 
#define SNMP_SHA384_SUPPORT   DISABLED
 
#define SNMP_SHA512_SUPPORT   DISABLED
 
#define SNMP_DES_SUPPORT   ENABLED
 
#define SNMP_AES_SUPPORT   ENABLED
 
#define SNMP_MAX_KEY_SIZE   64
 
#define SNMP_MAX_TRUNCATED_MAC_SIZE   48
 
#define SNMP_MSG_ENCRYPTION_OVERHEAD   8
 

Enumerations

enum  SnmpMessageFlags { SNMP_MSG_FLAG_AUTH = 1, SNMP_MSG_FLAG_PRIV = 2, SNMP_MSG_FLAG_REPORTABLE = 4 }
 Message flags. More...
 
enum  SnmpSecurityModel {
  SNMP_SECURITY_MODEL_ANY = 0, SNMP_SECURITY_MODEL_V1 = 1, SNMP_SECURITY_MODEL_V2C = 2, SNMP_SECURITY_MODEL_USM = 3,
  SNMP_SECURITY_MODEL_TSM = 4
}
 Security models. More...
 
enum  SnmpSecurityLevel { SNMP_SECURITY_LEVEL_NO_AUTH_NO_PRIV = 1, SNMP_SECURITY_LEVEL_AUTH_NO_PRIV = 2, SNMP_SECURITY_LEVEL_AUTH_PRIV = 3 }
 Security levels. More...
 
enum  SnmpAccess { SNMP_ACCESS_NONE = 0, SNMP_ACCESS_READ_ONLY = 1, SNMP_ACCESS_WRITE_ONLY = 2, SNMP_ACCESS_READ_WRITE = 3 }
 Access modes. More...
 
enum  SnmpAuthProtocol {
  SNMP_AUTH_PROTOCOL_NONE = 0, SNMP_AUTH_PROTOCOL_MD5 = 1, SNMP_AUTH_PROTOCOL_SHA1 = 2, SNMP_AUTH_PROTOCOL_SHA224 = 3,
  SNMP_AUTH_PROTOCOL_SHA256 = 4, SNMP_AUTH_PROTOCOL_SHA384 = 5, SNMP_AUTH_PROTOCOL_SHA512 = 6
}
 
enum  SnmpPrivProtocol { SNMP_PRIV_PROTOCOL_NONE = 0, SNMP_PRIV_PROTOCOL_DES = 1, SNMP_PRIV_PROTOCOL_AES = 2 }
 
enum  SnmpKeyFormat { SNMP_KEY_FORMAT_NONE = 0, SNMP_KEY_FORMAT_TEXT = 1, SNMP_KEY_FORMAT_RAW = 2, SNMP_KEY_FORMAT_LOCALIZED = 3 }
 SNMP key format. More...
 

Functions

SnmpUserEntrysnmpCreateUserEntry (SnmpAgentContext *context)
 Create a new user entry. More...
 
SnmpUserEntrysnmpFindUserEntry (SnmpAgentContext *context, const char_t *name, size_t length)
 Search the user table for a given user name. More...
 
error_t snmpGenerateKey (SnmpAuthProtocol authProtocol, const char_t *password, SnmpKey *key)
 Password to key algorithm. More...
 
error_t snmpLocalizeKey (SnmpAuthProtocol authProtocol, const uint8_t *engineId, size_t engineIdLen, SnmpKey *key, SnmpKey *localizedKey)
 Key localization algorithm. More...
 
void snmpChangeKey (const HashAlgo *hashAlgo, const uint8_t *random, const uint8_t *delta, SnmpKey *key)
 Change secret key. More...
 
void snmpCloneSecurityParameters (SnmpUserEntry *user, const SnmpUserEntry *cloneFromUser)
 Clone security parameters. More...
 
error_t snmpCheckSecurityParameters (const SnmpUserEntry *user, SnmpMessage *message, const uint8_t *engineId, size_t engineIdLen)
 Check security parameters. More...
 
void snmpRefreshEngineTime (SnmpAgentContext *context)
 Refresh SNMP engine time. More...
 
error_t snmpCheckEngineTime (SnmpAgentContext *context, SnmpMessage *message)
 Replay protection. More...
 
error_t snmpAuthOutgoingMessage (const SnmpUserEntry *user, SnmpMessage *message)
 Authenticate outgoing SNMP message. More...
 
error_t snmpAuthIncomingMessage (const SnmpUserEntry *user, SnmpMessage *message)
 Authenticate incoming SNMP message. More...
 
error_t snmpEncryptData (const SnmpUserEntry *user, SnmpMessage *message, uint64_t *salt)
 Data encryption. More...
 
error_t snmpDecryptData (const SnmpUserEntry *user, SnmpMessage *message)
 Data decryption. More...
 
const HashAlgosnmpGetHashAlgo (SnmpAuthProtocol authProtocol)
 Get the hash algorithm to be used for a given authentication protocol. More...
 
size_t snmpGetMacLength (SnmpAuthProtocol authProtocol)
 Get the length of the truncated MAC for a given authentication protocol. More...
 

Variables

const uint8_t usmStatsUnsupportedSecLevelsObject [10]
 
const uint8_t usmStatsNotInTimeWindowsObject [10]
 
const uint8_t usmStatsUnknownUserNamesObject [10]
 
const uint8_t usmStatsUnknownEngineIdsObject [10]
 
const uint8_t usmStatsWrongDigestsObject [10]
 
const uint8_t usmStatsDecryptionErrorsObject [10]
 

Detailed Description

User-based Security Model (USM) for SNMPv3.

License

Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
1.9.0

Definition in file snmp_agent_usm.h.

Macro Definition Documentation

◆ SNMP_AES_SUPPORT

#define SNMP_AES_SUPPORT   ENABLED

Definition at line 96 of file snmp_agent_usm.h.

◆ SNMP_DES_SUPPORT

#define SNMP_DES_SUPPORT   ENABLED

Definition at line 89 of file snmp_agent_usm.h.

◆ SNMP_MAX_KEY_SIZE

#define SNMP_MAX_KEY_SIZE   64

Definition at line 145 of file snmp_agent_usm.h.

◆ SNMP_MAX_TRUNCATED_MAC_SIZE

#define SNMP_MAX_TRUNCATED_MAC_SIZE   48

Definition at line 160 of file snmp_agent_usm.h.

◆ SNMP_MD5_SUPPORT

#define SNMP_MD5_SUPPORT   ENABLED

Definition at line 47 of file snmp_agent_usm.h.

◆ SNMP_MSG_ENCRYPTION_OVERHEAD

#define SNMP_MSG_ENCRYPTION_OVERHEAD   8

Definition at line 175 of file snmp_agent_usm.h.

◆ SNMP_SHA1_SUPPORT

#define SNMP_SHA1_SUPPORT   ENABLED

Definition at line 54 of file snmp_agent_usm.h.

◆ SNMP_SHA224_SUPPORT

#define SNMP_SHA224_SUPPORT   DISABLED

Definition at line 61 of file snmp_agent_usm.h.

◆ SNMP_SHA256_SUPPORT

#define SNMP_SHA256_SUPPORT   DISABLED

Definition at line 68 of file snmp_agent_usm.h.

◆ SNMP_SHA384_SUPPORT

#define SNMP_SHA384_SUPPORT   DISABLED

Definition at line 75 of file snmp_agent_usm.h.

◆ SNMP_SHA512_SUPPORT

#define SNMP_SHA512_SUPPORT   DISABLED

Definition at line 82 of file snmp_agent_usm.h.

◆ SNMP_TIME_WINDOW

#define SNMP_TIME_WINDOW   150

Definition at line 40 of file snmp_agent_usm.h.

Enumeration Type Documentation

◆ SnmpAccess

enum SnmpAccess

Access modes.

Enumerator
SNMP_ACCESS_NONE 
SNMP_ACCESS_READ_ONLY 
SNMP_ACCESS_WRITE_ONLY 
SNMP_ACCESS_READ_WRITE 

Definition at line 228 of file snmp_agent_usm.h.

◆ SnmpAuthProtocol

SNMP authentication protocols

Enumerator
SNMP_AUTH_PROTOCOL_NONE 

No authentication.

SNMP_AUTH_PROTOCOL_MD5 

HMAC-MD5-96.

SNMP_AUTH_PROTOCOL_SHA1 

HMAC-SHA-1-96.

SNMP_AUTH_PROTOCOL_SHA224 

HMAC-SHA-224-128.

SNMP_AUTH_PROTOCOL_SHA256 

HMAC-SHA-256-192.

SNMP_AUTH_PROTOCOL_SHA384 

HMAC-SHA-384-256.

SNMP_AUTH_PROTOCOL_SHA512 

HMAC-SHA-512-384.

Definition at line 241 of file snmp_agent_usm.h.

◆ SnmpKeyFormat

SNMP key format.

Enumerator
SNMP_KEY_FORMAT_NONE 

Unspecified key format.

SNMP_KEY_FORMAT_TEXT 

ASCII password.

SNMP_KEY_FORMAT_RAW 

Raw key.

SNMP_KEY_FORMAT_LOCALIZED 

Localized key.

Definition at line 269 of file snmp_agent_usm.h.

◆ SnmpMessageFlags

Message flags.

Enumerator
SNMP_MSG_FLAG_AUTH 
SNMP_MSG_FLAG_PRIV 
SNMP_MSG_FLAG_REPORTABLE 

Definition at line 190 of file snmp_agent_usm.h.

◆ SnmpPrivProtocol

SNMP privacy protocols

Enumerator
SNMP_PRIV_PROTOCOL_NONE 

No privacy.

SNMP_PRIV_PROTOCOL_DES 

DES-CBC.

SNMP_PRIV_PROTOCOL_AES 

AES-128-CFB.

Definition at line 257 of file snmp_agent_usm.h.

◆ SnmpSecurityLevel

Security levels.

Enumerator
SNMP_SECURITY_LEVEL_NO_AUTH_NO_PRIV 
SNMP_SECURITY_LEVEL_AUTH_NO_PRIV 
SNMP_SECURITY_LEVEL_AUTH_PRIV 

Definition at line 216 of file snmp_agent_usm.h.

◆ SnmpSecurityModel

Security models.

Enumerator
SNMP_SECURITY_MODEL_ANY 

Any.

SNMP_SECURITY_MODEL_V1 

SNMPv1.

SNMP_SECURITY_MODEL_V2C 

SNMPv2c.

SNMP_SECURITY_MODEL_USM 

User-based security model.

SNMP_SECURITY_MODEL_TSM 

Transport security model.

Definition at line 202 of file snmp_agent_usm.h.

Function Documentation

◆ snmpAuthIncomingMessage()

error_t snmpAuthIncomingMessage ( const SnmpUserEntry user,
SnmpMessage message 
)

Authenticate incoming SNMP message.

Parameters
[in]userSecurity profile of the user
[in]messagePointer to the incoming SNMP message
Returns
Error code

Definition at line 507 of file snmp_agent_usm.c.

◆ snmpAuthOutgoingMessage()

error_t snmpAuthOutgoingMessage ( const SnmpUserEntry user,
SnmpMessage message 
)

Authenticate outgoing SNMP message.

Parameters
[in]userSecurity profile of the user
[in,out]messagePointer to the outgoing SNMP message
Returns
Error code

Definition at line 467 of file snmp_agent_usm.c.

◆ snmpChangeKey()

void snmpChangeKey ( const HashAlgo hashAlgo,
const uint8_t *  random,
const uint8_t *  delta,
SnmpKey key 
)

Change secret key.

Parameters
[in]hashAlgoHash algorithm to be used
[in]randomPointer to the random component
[in]deltaPointer to the delta component
[in,out]keyPointer to the secret key K

Definition at line 275 of file snmp_agent_usm.c.

◆ snmpCheckEngineTime()

error_t snmpCheckEngineTime ( SnmpAgentContext context,
SnmpMessage message 
)

Replay protection.

Parameters
[in]contextPointer to the SNMP agent context
[in,out]messagePointer to the incoming SNMP message
Returns
Error code

Definition at line 409 of file snmp_agent_usm.c.

◆ snmpCheckSecurityParameters()

error_t snmpCheckSecurityParameters ( const SnmpUserEntry user,
SnmpMessage message,
const uint8_t *  engineId,
size_t  engineIdLen 
)

Check security parameters.

Parameters
[in]userSecurity profile of the user
[in,out]messagePointer to the incoming SNMP message
[in]engineIdPointer to the authoritative engine ID
[in]engineIdLenLength of the authoritative engine ID
Returns
Error code

Definition at line 327 of file snmp_agent_usm.c.

◆ snmpCloneSecurityParameters()

void snmpCloneSecurityParameters ( SnmpUserEntry user,
const SnmpUserEntry cloneFromUser 
)

Clone security parameters.

Parameters
[in,out]userSecurity profile of the user
[in]cloneFromUserSecurity profile of the clone-from user

Definition at line 304 of file snmp_agent_usm.c.

◆ snmpCreateUserEntry()

SnmpUserEntry* snmpCreateUserEntry ( SnmpAgentContext context)

Create a new user entry.

Parameters
[in]contextPointer to the SNMP agent context
Returns
Pointer to the newly created entry

Definition at line 73 of file snmp_agent_usm.c.

◆ snmpDecryptData()

error_t snmpDecryptData ( const SnmpUserEntry user,
SnmpMessage message 
)

Data decryption.

Parameters
[in]userSecurity profile of the user
[in,out]messagePointer to the incoming SNMP message
Returns
Error code

Definition at line 703 of file snmp_agent_usm.c.

◆ snmpEncryptData()

error_t snmpEncryptData ( const SnmpUserEntry user,
SnmpMessage message,
uint64_t *  salt 
)

Data encryption.

Parameters
[in]userSecurity profile of the user
[in,out]messagePointer to the outgoing SNMP message
[in,out]saltPointer to the salt integer
Returns
Error code

Definition at line 561 of file snmp_agent_usm.c.

◆ snmpFindUserEntry()

SnmpUserEntry* snmpFindUserEntry ( SnmpAgentContext context,
const char_t name,
size_t  length 
)

Search the user table for a given user name.

Parameters
[in]contextPointer to the SNMP agent context
[in]namePointer to the user name
[in]lengthLength of the user name
Returns
Pointer to the matching entry

Definition at line 128 of file snmp_agent_usm.c.

◆ snmpGenerateKey()

error_t snmpGenerateKey ( SnmpAuthProtocol  authProtocol,
const char_t password,
SnmpKey key 
)

Password to key algorithm.

Parameters
[in]authProtocolAuthentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
[in]passwordNULL-terminated string that contains the password
[out]keyPointer to the resulting key (Ku)
Returns
Error code

Definition at line 176 of file snmp_agent_usm.c.

◆ snmpGetHashAlgo()

const HashAlgo* snmpGetHashAlgo ( SnmpAuthProtocol  authProtocol)

Get the hash algorithm to be used for a given authentication protocol.

Parameters
[in]authProtocolAuthentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
Returns
Pointer to the corresponding hash algorithm

Definition at line 825 of file snmp_agent_usm.c.

◆ snmpGetMacLength()

size_t snmpGetMacLength ( SnmpAuthProtocol  authProtocol)

Get the length of the truncated MAC for a given authentication protocol.

Parameters
[in]authProtocolAuthentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
Returns
Length of the truncated MAC, in bytes

Definition at line 901 of file snmp_agent_usm.c.

◆ snmpLocalizeKey()

error_t snmpLocalizeKey ( SnmpAuthProtocol  authProtocol,
const uint8_t *  engineId,
size_t  engineIdLen,
SnmpKey key,
SnmpKey localizedKey 
)

Key localization algorithm.

Parameters
[in]authProtocolAuthentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
[in]engineIdPointer to the engine ID
[in]engineIdLenLength of the engine ID
[in]keyPointer to the key to be localized (Ku)
[out]localizedKeyPointer to the resulting key (Kul)
Returns
Error code

Definition at line 236 of file snmp_agent_usm.c.

◆ snmpRefreshEngineTime()

void snmpRefreshEngineTime ( SnmpAgentContext context)

Refresh SNMP engine time.

Parameters
[in]contextPointer to the SNMP agent context

Definition at line 372 of file snmp_agent_usm.c.

Variable Documentation

◆ usmStatsDecryptionErrorsObject

const uint8_t usmStatsDecryptionErrorsObject[10]

Definition at line 64 of file snmp_agent_usm.c.

◆ usmStatsNotInTimeWindowsObject

const uint8_t usmStatsNotInTimeWindowsObject[10]

Definition at line 56 of file snmp_agent_usm.c.

◆ usmStatsUnknownEngineIdsObject

const uint8_t usmStatsUnknownEngineIdsObject[10]

Definition at line 60 of file snmp_agent_usm.c.

◆ usmStatsUnknownUserNamesObject

const uint8_t usmStatsUnknownUserNamesObject[10]

Definition at line 58 of file snmp_agent_usm.c.

◆ usmStatsUnsupportedSecLevelsObject

const uint8_t usmStatsUnsupportedSecLevelsObject[10]

Definition at line 54 of file snmp_agent_usm.c.

◆ usmStatsWrongDigestsObject

const uint8_t usmStatsWrongDigestsObject[10]

Definition at line 62 of file snmp_agent_usm.c.