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_modes/cbc.h"
#include "cipher/aes.h"
#include "cipher_modes/cfb.h"

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
SnmpUserEntry *	snmpCreateUserEntry (SnmpAgentContext *context)
	Create a new user entry. More...

SnmpUserEntry *	snmpFindUserEntry (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 HashAlgo *	snmpGetHashAlgo (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

SPDX-License-Identifier: GPL-2.0-or-later

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: 2.4.0

Definition in file snmp_agent_usm.h.

Macro Definition Documentation

◆ SNMP_AES_SUPPORT

#define SNMP_AES_SUPPORT ENABLED

Definition at line 98 of file snmp_agent_usm.h.

◆ SNMP_DES_SUPPORT

#define SNMP_DES_SUPPORT ENABLED

Definition at line 91 of file snmp_agent_usm.h.

◆ SNMP_MAX_KEY_SIZE

#define SNMP_MAX_KEY_SIZE 64

Definition at line 147 of file snmp_agent_usm.h.

◆ SNMP_MAX_TRUNCATED_MAC_SIZE

#define SNMP_MAX_TRUNCATED_MAC_SIZE 48

Definition at line 162 of file snmp_agent_usm.h.

◆ SNMP_MD5_SUPPORT

#define SNMP_MD5_SUPPORT ENABLED

Definition at line 49 of file snmp_agent_usm.h.

◆ SNMP_MSG_ENCRYPTION_OVERHEAD

#define SNMP_MSG_ENCRYPTION_OVERHEAD 8

Definition at line 177 of file snmp_agent_usm.h.

◆ SNMP_SHA1_SUPPORT

#define SNMP_SHA1_SUPPORT ENABLED

Definition at line 56 of file snmp_agent_usm.h.

◆ SNMP_SHA224_SUPPORT

#define SNMP_SHA224_SUPPORT DISABLED

Definition at line 63 of file snmp_agent_usm.h.

◆ SNMP_SHA256_SUPPORT

#define SNMP_SHA256_SUPPORT DISABLED

Definition at line 70 of file snmp_agent_usm.h.

◆ SNMP_SHA384_SUPPORT

#define SNMP_SHA384_SUPPORT DISABLED

Definition at line 77 of file snmp_agent_usm.h.

◆ SNMP_SHA512_SUPPORT

#define SNMP_SHA512_SUPPORT DISABLED

Definition at line 84 of file snmp_agent_usm.h.

◆ SNMP_TIME_WINDOW

#define SNMP_TIME_WINDOW 150

Definition at line 42 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 230 of file snmp_agent_usm.h.

◆ SnmpAuthProtocol

enum 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 243 of file snmp_agent_usm.h.

◆ SnmpKeyFormat

enum 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 271 of file snmp_agent_usm.h.

◆ SnmpMessageFlags

enum SnmpMessageFlags

Message flags.

Enumerator
SNMP_MSG_FLAG_AUTH
SNMP_MSG_FLAG_PRIV
SNMP_MSG_FLAG_REPORTABLE

Definition at line 192 of file snmp_agent_usm.h.

◆ SnmpPrivProtocol

enum 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 259 of file snmp_agent_usm.h.

◆ SnmpSecurityLevel

enum 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 218 of file snmp_agent_usm.h.

◆ SnmpSecurityModel

enum 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 204 of file snmp_agent_usm.h.

Function Documentation

◆ snmpAuthIncomingMessage()

error_t snmpAuthIncomingMessage	(	const SnmpUserEntry *	user,
		SnmpMessage *	message
	)

Authenticate incoming SNMP message.

Parameters

[in]	user	Security profile of the user
[in]	message	Pointer to the incoming SNMP message

Returns: Error code

Definition at line 509 of file snmp_agent_usm.c.

◆ snmpAuthOutgoingMessage()

error_t snmpAuthOutgoingMessage	(	const SnmpUserEntry *	user,
		SnmpMessage *	message
	)

Authenticate outgoing SNMP message.

Parameters

[in]	user	Security profile of the user
[in,out]	message	Pointer to the outgoing SNMP message

Returns: Error code

Definition at line 469 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]	hashAlgo	Hash algorithm to be used
[in]	random	Pointer to the random component
[in]	delta	Pointer to the delta component
[in,out]	key	Pointer to the secret key K

Definition at line 277 of file snmp_agent_usm.c.

◆ snmpCheckEngineTime()

error_t snmpCheckEngineTime	(	SnmpAgentContext *	context,
		SnmpMessage *	message
	)

Replay protection.

Parameters

[in]	context	Pointer to the SNMP agent context
[in,out]	message	Pointer to the incoming SNMP message

Returns: Error code

Definition at line 411 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]	user	Security profile of the user
[in,out]	message	Pointer to the incoming SNMP message
[in]	engineId	Pointer to the authoritative engine ID
[in]	engineIdLen	Length of the authoritative engine ID

Returns: Error code

Definition at line 329 of file snmp_agent_usm.c.

◆ snmpCloneSecurityParameters()

void snmpCloneSecurityParameters	(	SnmpUserEntry *	user,
		const SnmpUserEntry *	cloneFromUser
	)

Clone security parameters.

Parameters

[in,out]	user	Security profile of the user
[in]	cloneFromUser	Security profile of the clone-from user

Definition at line 306 of file snmp_agent_usm.c.

◆ snmpCreateUserEntry()

SnmpUserEntry* snmpCreateUserEntry ( SnmpAgentContext * context )

Create a new user entry.

Parameters

[in] context Pointer to the SNMP agent context

Returns: Pointer to the newly created entry

Definition at line 75 of file snmp_agent_usm.c.

◆ snmpDecryptData()

error_t snmpDecryptData	(	const SnmpUserEntry *	user,
		SnmpMessage *	message
	)

Data decryption.

Parameters

[in]	user	Security profile of the user
[in,out]	message	Pointer to the incoming SNMP message

Returns: Error code

Definition at line 705 of file snmp_agent_usm.c.

◆ snmpEncryptData()

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

Data encryption.

Parameters

[in]	user	Security profile of the user
[in,out]	message	Pointer to the outgoing SNMP message
[in,out]	salt	Pointer to the salt integer

Returns: Error code

Definition at line 563 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]	context	Pointer to the SNMP agent context
[in]	name	Pointer to the user name
[in]	length	Length of the user name

Returns: Pointer to the matching entry

Definition at line 130 of file snmp_agent_usm.c.

◆ snmpGenerateKey()

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

Password to key algorithm.

Parameters

[in]	authProtocol	Authentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
[in]	password	NULL-terminated string that contains the password
[out]	key	Pointer to the resulting key (Ku)

Returns: Error code

Definition at line 178 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] authProtocol Authentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)

Returns: Pointer to the corresponding hash algorithm

Definition at line 827 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] authProtocol Authentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)

Returns: Length of the truncated MAC, in bytes

Definition at line 903 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]	authProtocol	Authentication protocol (MD5, SHA-1, SHA-224, SHA-256, SHA384 or SHA512)
[in]	engineId	Pointer to the engine ID
[in]	engineIdLen	Length of the engine ID
[in]	key	Pointer to the key to be localized (Ku)
[out]	localizedKey	Pointer to the resulting key (Kul)

Returns: Error code

Definition at line 238 of file snmp_agent_usm.c.

◆ snmpRefreshEngineTime()

void snmpRefreshEngineTime ( SnmpAgentContext * context )

Refresh SNMP engine time.

Parameters

[in] context Pointer to the SNMP agent context

Definition at line 374 of file snmp_agent_usm.c.

Variable Documentation

◆ usmStatsDecryptionErrorsObject

const uint8_t usmStatsDecryptionErrorsObject[10]

extern

Definition at line 66 of file snmp_agent_usm.c.

◆ usmStatsNotInTimeWindowsObject

const uint8_t usmStatsNotInTimeWindowsObject[10]

extern

Definition at line 58 of file snmp_agent_usm.c.

◆ usmStatsUnknownEngineIdsObject

const uint8_t usmStatsUnknownEngineIdsObject[10]

extern

Definition at line 62 of file snmp_agent_usm.c.

◆ usmStatsUnknownUserNamesObject

const uint8_t usmStatsUnknownUserNamesObject[10]

extern

Definition at line 60 of file snmp_agent_usm.c.

◆ usmStatsUnsupportedSecLevelsObject

const uint8_t usmStatsUnsupportedSecLevelsObject[10]

extern

Definition at line 56 of file snmp_agent_usm.c.

◆ usmStatsWrongDigestsObject

const uint8_t usmStatsWrongDigestsObject[10]

extern

Definition at line 64 of file snmp_agent_usm.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

License

Macro Definition Documentation

◆ SNMP_AES_SUPPORT

◆ SNMP_DES_SUPPORT

◆ SNMP_MAX_KEY_SIZE

◆ SNMP_MAX_TRUNCATED_MAC_SIZE

◆ SNMP_MD5_SUPPORT

◆ SNMP_MSG_ENCRYPTION_OVERHEAD

◆ SNMP_SHA1_SUPPORT

◆ SNMP_SHA224_SUPPORT

◆ SNMP_SHA256_SUPPORT

◆ SNMP_SHA384_SUPPORT

◆ SNMP_SHA512_SUPPORT

◆ SNMP_TIME_WINDOW

Enumeration Type Documentation

◆ SnmpAccess

◆ SnmpAuthProtocol

◆ SnmpKeyFormat

◆ SnmpMessageFlags

◆ SnmpPrivProtocol

◆ SnmpSecurityLevel

◆ SnmpSecurityModel

Function Documentation

◆ snmpAuthIncomingMessage()

◆ snmpAuthOutgoingMessage()

◆ snmpChangeKey()

◆ snmpCheckEngineTime()

◆ snmpCheckSecurityParameters()

◆ snmpCloneSecurityParameters()

◆ snmpCreateUserEntry()

◆ snmpDecryptData()

◆ snmpEncryptData()

◆ snmpFindUserEntry()

◆ snmpGenerateKey()

◆ snmpGetHashAlgo()

◆ snmpGetMacLength()

◆ snmpLocalizeKey()

◆ snmpRefreshEngineTime()

Variable Documentation

◆ usmStatsDecryptionErrorsObject

◆ usmStatsNotInTimeWindowsObject

◆ usmStatsUnknownEngineIdsObject

◆ usmStatsUnknownUserNamesObject

◆ usmStatsUnsupportedSecLevelsObject

◆ usmStatsWrongDigestsObject