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

#include "core/net.h"
#include "snmp/snmp_agent.h"
#include "snmp/snmp_agent_usm.h"
#include "core/crypto.h"
#include "encoding/asn1.h"
#include "mac/hmac.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL SNMP_TRACE_LEVEL

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] = {43, 6, 1, 6, 3, 15, 1, 1, 1, 0}

const uint8_t	usmStatsNotInTimeWindowsObject [10] = {43, 6, 1, 6, 3, 15, 1, 1, 2, 0}

const uint8_t	usmStatsUnknownUserNamesObject [10] = {43, 6, 1, 6, 3, 15, 1, 1, 3, 0}

const uint8_t	usmStatsUnknownEngineIdsObject [10] = {43, 6, 1, 6, 3, 15, 1, 1, 4, 0}

const uint8_t	usmStatsWrongDigestsObject [10] = {43, 6, 1, 6, 3, 15, 1, 1, 5, 0}

const uint8_t	usmStatsDecryptionErrorsObject [10] = {43, 6, 1, 6, 3, 15, 1, 1, 6, 0}

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.

Description

This module implements the User-based Security Model (USM) for Simple Network Management Protocol (SNMP) version 3. Refer to the following RFCs for complete details:

RFC 3414: User-based Security Model (USM) for SNMPv3
RFC 3826: AES Cipher Algorithm in the SNMP User-based Security Model
RFC 7860: HMAC-SHA-2 Authentication Protocols in the User-based Security Model

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

Version: 2.5.4

Definition in file snmp_agent_usm.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL SNMP_TRACE_LEVEL

Definition at line 41 of file snmp_agent_usm.c.

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] = {43, 6, 1, 6, 3, 15, 1, 1, 6, 0}

Definition at line 66 of file snmp_agent_usm.c.

◆ usmStatsNotInTimeWindowsObject

const uint8_t usmStatsNotInTimeWindowsObject[10] = {43, 6, 1, 6, 3, 15, 1, 1, 2, 0}

Definition at line 58 of file snmp_agent_usm.c.

◆ usmStatsUnknownEngineIdsObject

const uint8_t usmStatsUnknownEngineIdsObject[10] = {43, 6, 1, 6, 3, 15, 1, 1, 4, 0}

Definition at line 62 of file snmp_agent_usm.c.

◆ usmStatsUnknownUserNamesObject

const uint8_t usmStatsUnknownUserNamesObject[10] = {43, 6, 1, 6, 3, 15, 1, 1, 3, 0}

Definition at line 60 of file snmp_agent_usm.c.

◆ usmStatsUnsupportedSecLevelsObject

const uint8_t usmStatsUnsupportedSecLevelsObject[10] = {43, 6, 1, 6, 3, 15, 1, 1, 1, 0}

Definition at line 56 of file snmp_agent_usm.c.

◆ usmStatsWrongDigestsObject

const uint8_t usmStatsWrongDigestsObject[10] = {43, 6, 1, 6, 3, 15, 1, 1, 5, 0}

Definition at line 64 of file snmp_agent_usm.c.

Macros

Functions

Variables

Detailed Description

License

Description

Macro Definition Documentation

◆ TRACE_LEVEL

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