snmp_agent_usm.c File Reference

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"

Go to the source code of this file.

Macros

#define TRACE_LEVEL   SNMP_TRACE_LEVEL
 

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] = {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

Copyright (C) 2010-2024 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.

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.4.0

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]userSecurity profile of the user
[in]messagePointer 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]userSecurity profile of the user
[in,out]messagePointer 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]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 277 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 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]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 329 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 306 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 75 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 705 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 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]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 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]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 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]authProtocolAuthentication 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]authProtocolAuthentication 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]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 238 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 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.