This is the class for the User Based Security Model. More...

#include <usm_v3.h>

Collaboration diagram for USM:

[legend]

Public Member Functions
	USM (unsigned int engine_boots, const OctetStr &engine_id, const v3MP v3_mp, unsigned int msg_id, int &result)
	Create an instance of the USM. More...

	~USM ()
	Destructor. More...

void	set_discovery_mode ()
	Enables the discovery mode of the USM, i.e. More...

void	unset_discovery_mode ()
	Disables the discovery mode of the USM, i.e. More...

bool	is_discovery_enabled () const
	Return TRUE if the USM discovery mode is enabled, FALSE else. More...

int	add_usm_user (const OctetStr &security_name, const long int auth_protocol, const long int priv_protocol, const OctetStr &auth_password, const OctetStr &priv_password)
	Add a new user to the usmUserNameTable. More...

int	add_usm_user (const OctetStr &user_name, const OctetStr &security_name, const long int auth_protocol, const long int priv_protocol, const OctetStr &auth_password, const OctetStr &priv_password)
	Add a new user to the usmUserNameTable. More...

int	add_usm_user (const OctetStr &user_name, const OctetStr &security_name, const long int auth_protocol, const long int priv_protocol, const OctetStr &auth_password, const OctetStr &priv_password, const OctetStr &engine_id)
	Add or replace a localized user in the USM table. More...

int	add_usm_user (const OctetStr &security_name, const long int auth_protocol, const long int priv_protocol, const OctetStr &auth_password, const OctetStr &priv_password, const OctetStr &engine_id)

void	delete_usm_user (const OctetStr &security_name)
	Delete all occurrences of the user with the given security name from the USM. More...

int	save_localized_users (const char *file)
	Save all localized users into a file. More...

int	load_localized_users (const char *file)
	Load localized users from a file. More...

int	save_users (const char *file)
	Save all users with their passwords into a file. More...

int	load_users (const char *file)
	Load users with their passwords from a file. More...

int	add_localized_user (const OctetStr &engine_id, const OctetStr &user_name, const OctetStr &security_name, const long auth_protocol, const OctetStr &auth_key, const long priv_protocol, const OctetStr &priv_key)
	Add or replace a localized user in the USM table. More...

int	build_localized_keys (const OctetStr &engine_id, const int auth_prot, const int priv_prot, const unsigned char auth_password, const unsigned int auth_password_len, const unsigned char priv_password, const unsigned int priv_password_len, unsigned char auth_key, unsigned int auth_key_len, unsigned char priv_key, unsigned int priv_key_len)
	Generate localized keys for the given params. More...

int	delete_localized_user (const OctetStr &user_name)
	Delete all localized entries of this user from the usmUserTable. More...

int	delete_localized_user (const OctetStr &engine_id, const OctetStr &user_name)
	Delete the entry with the given userName and engineID from the usmUserTable. More...

int	remove_engine_id (const OctetStr &engine_id)
	Delete this engine id form all USM tables (users and engine time). More...

int	remove_time_information (const OctetStr &engine_id)
	Delete the time information for the given engine id. More...

int	update_key (const unsigned char user_name, const long user_name_len, const unsigned char engine_id, const long engine_id_len, const unsigned char *new_key, const long new_key_len, const int type_of_key)
	Replace a localized key of the user and engineID in the usmUserTable. More...

struct UsmUser *	get_user (const OctetStr &engine_id, const OctetStr &security_name)
	Search for a user with the given securityName and engineID in the usmUserTable and return the entry. More...

void	free_user (struct UsmUser *&user)
	Free the structure returned from get_user(OctetStr,OctetStr). More...

int	get_security_name (const unsigned char *user_name, const long int user_name_len, OctetStr &security_name)
	Get the security name from a user name. More...

int	get_user_name (unsigned char user_name, long int user_name_len, const unsigned char *security_name, const long int security_name_len)
	Get the user name from a security name. More...

struct UsmKeyUpdate *	key_update_prepare (const OctetStr &securityName, SnmpTarget &target, const OctetStr &newPassword, Pdu &pdu, int type, int &status, const OctetStr &oldpass="", const OctetStr &oldengid="", const OctetStr &newengid="")
	Prepare a key update in the USM. More...

void	key_update_abort (struct UsmKeyUpdate *uku)
	Abort the local key update. More...

int	key_update_commit (struct UsmKeyUpdate *uku, int update_type)
	Commit the local key update. More...

AuthPriv *	get_auth_priv ()
	Get a pointer to the AuthPriv object used by the USM. More...

int	get_time (const OctetStr &engine_id, long int engine_boots, long int engine_time)
	Return engineBoots and engineTime for a given engineID. More...

int	get_local_time (long int engine_boots, long int engine_time) const
	Return engineBoots and engineTime of the local snmp entity. More...

const OctetStr &	get_local_engine_id () const
	Return the local snmp engine id. More...

unsigned long	get_stats_unsupported_sec_levels () const
	Get the number of received messages with an unsupported securityLevel. More...

unsigned long	get_stats_not_in_time_windows () const
	Get the number of received messages outside time window. More...

unsigned long	get_stats_unknown_user_names () const
	Get the number of received messages with a unknown userName. More...

unsigned long	get_stats_unknown_engine_ids () const
	Get the number of received messages with a unknown engineID. More...

unsigned long	get_stats_wrong_digests () const
	Get the number of received messages with a wrong digest. More...

unsigned long	get_stats_decryption_errors () const
	Get the number of received messages with decryption errors. More...

void	lock_user_name_table ()
	Lock the UsmUserNameTable for access through peek_first_user() and peek_next_user(). More...

const UsmUserNameTableEntry *	peek_first_user ()
	Get a const pointer to the first entry of the UsmUserNameTable. More...

const UsmUserNameTableEntry *	peek_next_user (const UsmUserNameTableEntry *e)
	Get a const pointer to the next entry of the UsmUserNameTable. More...

void	unlock_user_name_table ()
	Unlock the UsmUserNameTable after access through peek_first_user() and peek_next_user(). More...

void	lock_user_table ()
	Lock the UsmUserTable for access through peek_first_luser() and peek_next_luser(). More...

const UsmUserTableEntry *	peek_first_luser ()
	Get a const pointer to the first entry of the UsmUserTable. More...

const UsmUserTableEntry *	peek_next_luser (const UsmUserTableEntry *e)
	Get a const pointer to the next entry of the UsmUserTable. More...

void	unlock_user_table ()
	Unlock the UsmUserTable after access through peek_first_luser() and peek_next_luser(). More...

void	delete_sec_state_reference (struct SecurityStateReference *ssr)
	for v3MP: More...

const struct UsmUserTableEntry *	get_user (int number)
	Protected (for agent++): More...

const struct UsmUserNameTableEntry *	get_user (const OctetStr &security_name)
	Get the properties of the specified user. More...

int	get_user_count () const
	Protected (for agent++): More...

void	add_user_added_callback (const usm_add_user_callback cb)
	Protected (for agent++) More...

int	remove_all_users ()
	Clear all user configuration from this USM instance. More...


void	inc_stats_unsupported_sec_levels ()
	Increase the stats counter. More...

void	inc_stats_not_in_time_windows ()

void	inc_stats_unknown_user_names ()

void	inc_stats_unknown_engine_ids ()

void	inc_stats_wrong_digests ()

void	inc_stats_decryption_errors ()

Protected Member Functions
struct SecurityStateReference *	get_new_sec_state_reference ()
	Get a new security state reference (for v3MP). More...

int	generate_msg (unsigned char globalData, int globalDataLength, int maxMessageSize, const OctetStr &securityEngineID, const OctetStr &securityName, int securityLevel, unsigned char scopedPDU, int scopedPDULength, struct SecurityStateReference securityStateReference, unsigned char wholeMsg, int *wholeMsgLength)
	Generate a complete message that is ready to send to the target. More...

int	process_msg (int maxMessageSize, unsigned char securityParameters, int securityParametersLength, int securityParametersPosition, long int securityLevel, unsigned char wholeMsg, int wholeMsgLength, unsigned char msgData, int msgDataLength, OctetStr &security_engine_id, OctetStr &security_name, unsigned char scopedPDU, int scopedPDULength, long maxSizeResponseScopedPDU, struct SecurityStateReference *securityStateReference, const UdpAddress &fromAddress)
	Parse a received message. More...

Private Member Functions
void	delete_sec_parameters (struct UsmSecurityParameters *usp)
	Delete the pointers in the structure and set all values to 0/NULL. More...

unsigned char *	build_sec_params (unsigned char outBuf, int maxLength, struct UsmSecurityParameters sp, int *position)
	Serialize the given values into the buffer according to the BER. More...

unsigned char *	build_whole_msg (unsigned char outBuf, int maxLength, unsigned char globalData, long int globalDataLength, int positionAuthPar, struct UsmSecurityParameters securityParameters, unsigned char *msgData, long int msgDataLength)
	Serialize the given values according to the BER into the buffer. More...

void	delete_user_ptr (struct UsmUser *user)
	Delete the pointers in the structure. More...

Private Attributes
OctetStr	local_snmp_engine_id
	local snmp engine id More...

const v3MP *	v3mp
	Pointer to the v3MP that created this object. More...

bool	discovery_mode

unsigned int	usmStatsUnsupportedSecLevels

unsigned int	usmStatsNotInTimeWindows

unsigned int	usmStatsUnknownUserNames

unsigned int	usmStatsUnknownEngineIDs

unsigned int	usmStatsWrongDigests

unsigned int	usmStatsDecryptionErrors

AuthPriv *	auth_priv

USMTimeTable *	usm_time_table

USMUserNameTable *	usm_user_name_table

USMUserTable *	usm_user_table

usm_add_user_callback	usm_add_user_cb

Friends
class	v3MP

Detailed Description

This is the class for the User Based Security Model.

To add or delete users, the methods add_usm_user() and delete_usm_user() should be used.

USM distinguishes between userName and securityName. The following is from section 2.1 of RFC3414:

"userName: A string representing the name of the user.

securityName: A human-readable string representing the user in a format that is Security Model independent. There is a one-to-one relationship * between userName and securityName."

Definition at line 241 of file usm_v3.h.

Constructor & Destructor Documentation

◆ USM()

USM::USM	(	unsigned int	engine_boots,
		const OctetStr &	engine_id,
		const v3MP *	v3_mp,
		unsigned int *	msg_id,
		int &	result
	)

Create an instance of the USM.

Parameters

engine_boots	- The new value for the snmpEngineBoots counter
engine_id	- The local snmp engine id
v3_mp	- Pointer to the parent v3MP object.
msg_id	- OUT: The initial value for the msgID
result	- OUT: construct status, should be SNMPv3_USM_OK

◆ ~USM()

USM::~USM ( )

Destructor.

Member Function Documentation

◆ add_localized_user()

int USM::add_localized_user	(	const OctetStr &	engine_id,
		const OctetStr &	user_name,
		const OctetStr &	security_name,
		const long	auth_protocol,
		const OctetStr &	auth_key,
		const long	priv_protocol,
		const OctetStr &	priv_key
	)

Add or replace a localized user in the USM table.

Use this method only, if you know what you are doing.

Parameters

engine_id	- The engineID, the key was localized with
user_name	- The name of the user (in the USM)
security_name	- The securityName of the user, this name is the same for all securityModels
auth_protocol	- Possible values are: SNMP_AUTHPROTOCOL_NONE, SNMP_AUTHPROTOCOL_HMACMD5, SNMP_AUTHPROTOCOL_HMACSHA,...
auth_key	- The key used for authentications
priv_protocol	- Possible values are: SNMP_PRIVPROTOCOL_NONE, SNMP_PRIVPROTOCOL_DES, SNMP_PRIVPROTOCOL_IDEA,...
priv_key	- The key used for privacy

Returns: - SNMPv3_USM_OK SNMP_v3_USM_ERROR (not initialized, no memory)

◆ add_user_added_callback()

void USM::add_user_added_callback ( const usm_add_user_callback cb )

Protected (for agent++)

Register a callback function that is called if a new localized user has been added to the usm user table

◆ add_usm_user() [1/4]

int USM::add_usm_user	(	const OctetStr &	security_name,
		const long int	auth_protocol,
		const long int	priv_protocol,
		const OctetStr &	auth_password,
		const OctetStr &	priv_password
	)

Add a new user to the usmUserNameTable.

If the User is already known to the USM, the old entry is replaced. The USM will compute a userName for the given securityName, which will be the same as securityName (recommended).

If discovery mode is enabled, localized user entries are automatically created for new engine ids.

Parameters

security_name	- Unique securityName
auth_protocol	- Possible values are: SNMP_AUTHPROTOCOL_NONE, SNMP_AUTHPROTOCOL_HMACMD5, SNMP_AUTHPROTOCOL_HMACSHA
priv_protocol	- Possible values are: SNMP_PRIVPROTOCOL_NONE, SNMP_PRIVPROTOCOL_DES, SNMP_PRIVPROTOCOL_IDEA
auth_password	- Secret password for authentication
priv_password	- Secret password for privacy

Returns: - SNMPv3_USM_OK or SNMP_v3_USM_ERROR (memory error, not initialized)

◆ add_usm_user() [2/4]

int USM::add_usm_user	(	const OctetStr &	user_name,
		const OctetStr &	security_name,
		const long int	auth_protocol,
		const long int	priv_protocol,
		const OctetStr &	auth_password,
		const OctetStr &	priv_password
	)

Add a new user to the usmUserNameTable.

If the userName is already known to the USM, the old entry is replaced.

It is not recommended to add users with userName != securityName.

Parameters

user_name	- Unique userName
security_name	- Unique securityName
auth_protocol	- Possible values are: SNMP_AUTHPROTOCOL_NONE, SNMP_AUTHPROTOCOL_HMACMD5, SNMP_AUTHPROTOCOL_HMACSHA
priv_protocol	- Possible values are: SNMP_PRIVPROTOCOL_NONE, SNMP_PRIVPROTOCOL_DES, SNMP_PRIVPROTOCOL_IDEA
auth_password	- Secret password for authentication
priv_password	- Secret password for privacy

Returns: - SNMPv3_USM_OK or SNMP_v3_USM_ERROR (memory error, not initialized)

◆ add_usm_user() [3/4]

int USM::add_usm_user	(	const OctetStr &	user_name,
		const OctetStr &	security_name,
		const long int	auth_protocol,
		const long int	priv_protocol,
		const OctetStr &	auth_password,
		const OctetStr &	priv_password,
		const OctetStr &	engine_id
	)

Add or replace a localized user in the USM table.

This function uses build_localized_keys() to generate localized keys for the given passwords. Then it calls add_localized_user() to add/replace the localized entry for the user.

The passwords are not stored, so no additonal engine id discovery is possible.

Parameters

user_name	- The name of the user (in the USM)
security_name	- The securityName of the user, this name is the same for all securityModels
auth_protocol	- Possible values are: SNMP_AUTHPROTOCOL_NONE, SNMP_AUTHPROTOCOL_HMACMD5, SNMP_AUTHPROTOCOL_HMACSHA,...
priv_protocol	- Possible values are: SNMP_PRIVPROTOCOL_NONE, SNMP_PRIVPROTOCOL_DES, SNMP_PRIVPROTOCOL_IDEA,...
auth_password	- Secret password for authentication
priv_password	- Secret password for privacy
engine_id	- The engineID, the key was localized with

Returns: - SNMPv3_USM_OK SNMP_v3_USM_ERROR (not initialized, no memory)

◆ add_usm_user() [4/4]

int USM::add_usm_user	(	const OctetStr &	security_name,
		const long int	auth_protocol,
		const long int	priv_protocol,
		const OctetStr &	auth_password,
		const OctetStr &	priv_password,
		const OctetStr &	engine_id
	)

inline

Definition at line 377 of file usm_v3.h.

◆ build_localized_keys()

int USM::build_localized_keys	(	const OctetStr &	engine_id,
		const int	auth_prot,
		const int	priv_prot,
		const unsigned char *	auth_password,
		const unsigned int	auth_password_len,
		const unsigned char *	priv_password,
		const unsigned int	priv_password_len,
		unsigned char *	auth_key,
		unsigned int *	auth_key_len,
		unsigned char *	priv_key,
		unsigned int *	priv_key_len
	)

Generate localized keys for the given params.

The buffers for the keys should be of size SNMPv3_USM_MAX_KEY_LEN.

Parameters

engine_id	-
auth_prot	-
priv_prot	-
auth_password	-
auth_password_len	-
priv_password	-
priv_password_len	-
auth_key	- allocated space for the authentication key
auth_key_len	- IN: length of the buffer, OUT: key length
priv_key	- allocated space for the privacy key
priv_key_len	- IN: length of the buffer, OUT: key length

Returns: SNMPv3_USM_OK, or USM error codes

◆ build_sec_params()

unsigned char* USM::build_sec_params	(	unsigned char *	outBuf,
		int *	maxLength,
		struct UsmSecurityParameters	sp,
		int *	position
	)

private

Serialize the given values into the buffer according to the BER.

UsmSecurityParameters ::= SEQUENCE { – global User-based security parameters msgAuthoritativeEngineID OCTET STRING (5..32) msgAuthoritativeEngineBoots INTEGER (0..2147483647), msgAuthoritativeEngineTime INTEGER (0..2147483647), msgUserName OCTET STRING (SIZE(0..32)), – authentication protocol specific parameters msgAuthenticationParameters OCTET STRING, – privacy protocol specific parameters msgPrivacyParameters OCTET STRING }

Parameters

outBuf	- buffer for the serialized values
maxLength	- before call: length of the buffer after call: bytes left in the buffer
sp	- the values to serialize
position	- after call: points to the first byte of the field for the authentication parameter

Returns: - a pointer to the first free byte in the buffer, NULL on error

◆ build_whole_msg()

unsigned char* USM::build_whole_msg	(	unsigned char *	outBuf,
		int *	maxLength,
		unsigned char *	globalData,
		long int	globalDataLength,
		int *	positionAuthPar,
		struct UsmSecurityParameters	securityParameters,
		unsigned char *	msgData,
		long int	msgDataLength
	)

private

Serialize the given values according to the BER into the buffer.

On success, the buffer contains a valid SNMPv3 message.

Parameters

outBuf	- buffer for the serialized values
maxLength	- before call: length of the buffer after call: bytes left in the buffer
globalData	- Buffer that contains the serialized globalData
globalDataLength	- The length of this buffer
positionAuthPar	- after call: points to the first byte of the field for the authentication parameter
securityParameters	- The security parameters
msgData	- Buffer that contains the serialized msgData
msgDataLength	- The length of this buffer

Returns: - a pointer to the first free byte in the buffer, NULL on error

◆ delete_localized_user() [1/2]

int USM::delete_localized_user ( const OctetStr & user_name )

Delete all localized entries of this user from the usmUserTable.

Parameters

user_name - The userName that should be deleted

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (user deleted or not in table)

◆ delete_localized_user() [2/2]

int USM::delete_localized_user	(	const OctetStr &	engine_id,
		const OctetStr &	user_name
	)

Delete the entry with the given userName and engineID from the usmUserTable.

Parameters

engine_id	- The engineID
user_name	- The userName that should be deleted

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (user deleted or not in table)

◆ delete_sec_parameters()

void USM::delete_sec_parameters ( struct UsmSecurityParameters * usp )

private

Delete the pointers in the structure and set all values to 0/NULL.

Parameters

usp	- The structure that should be deleted

◆ delete_sec_state_reference()

void USM::delete_sec_state_reference ( struct SecurityStateReference * ssr )

for v3MP:

Delete the pointers within the structure and the structure itself.

Parameters

ssr	- The structure that should be deleted.

◆ delete_user_ptr()

void USM::delete_user_ptr ( struct UsmUser * user )

inlineprivate

Delete the pointers in the structure.

Parameters

user	- The structure that should be deleted

◆ delete_usm_user()

void USM::delete_usm_user ( const OctetStr & security_name )

Delete all occurrences of the user with the given security name from the USM.

Parameters

security_name - the securityName of the user

◆ free_user()

void USM::free_user ( struct UsmUser *& user )

Free the structure returned from get_user(OctetStr,OctetStr).

◆ generate_msg()

int USM::generate_msg	(	unsigned char *	globalData,
		int	globalDataLength,
		int	maxMessageSize,
		const OctetStr &	securityEngineID,
		const OctetStr &	securityName,
		int	securityLevel,
		unsigned char *	scopedPDU,
		int	scopedPDULength,
		struct SecurityStateReference *	securityStateReference,
		unsigned char *	wholeMsg,
		int *	wholeMsgLength
	)

protected

Generate a complete message that is ready to send to the target.

Parameters

globalData	- Buffer containing the serialized globalData, ready to be copied into the wholeMsg
globalDataLength	- The length of this buffer
maxMessageSize	- The maximum message size
securityEngineID	- The engineID of the authoritative SNMP entity
securityName	- The name of the user
securityLevel	- The security Level for this Message
scopedPDU	- Buffer containing the serialized scopedPDU, ready to be copied into the wholeMsg
scopedPDULength	- The length of this Buffer
securityStateReference	- The reference that was generated when the request was parsed. For request, this param has to be NULL. The reference is deleted by this function.
wholeMsg	- OUT: the buffer for the whole message
wholeMsgLength	- IN: lenght of the buffer. OUT: length of the generated message

Returns: - SNMPv3_USM_OK on success. See snmperrs.h for the error codes of the USM.

◆ get_auth_priv()

AuthPriv* USM::get_auth_priv ( )

Get a pointer to the AuthPriv object used by the USM.

◆ get_local_engine_id()

const OctetStr& USM::get_local_engine_id ( ) const

inline

Return the local snmp engine id.

Definition at line 711 of file usm_v3.h.

◆ get_local_time()

int USM::get_local_time	(	long int *	engine_boots,
		long int *	engine_time
	)		const

Return engineBoots and engineTime of the local snmp entity.

Parameters

engine_boots	- OUT: boot counter (0 if not found)
engine_time	- OUT: engine time (0 if not found)

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (entry found, values are filled)

◆ get_new_sec_state_reference()

struct SecurityStateReference* USM::get_new_sec_state_reference ( )

protected

Get a new security state reference (for v3MP).

Returns: - A newly created security state reference.

◆ get_security_name()

int USM::get_security_name	(	const unsigned char *	user_name,
		const long int	user_name_len,
		OctetStr &	security_name
	)

Get the security name from a user name.

Parameters

user_name	-
user_name_len	-
security_name	- Buffer for the securityName

Returns: - SNMPv3_USM_ERROR (not initialized, not found, buffer too small), SNMPv3_USM_OK

◆ get_stats_decryption_errors()

unsigned long USM::get_stats_decryption_errors ( ) const

inline

Get the number of received messages with decryption errors.

Returns: - usmStatsDecryptionErrors

Definition at line 758 of file usm_v3.h.

◆ get_stats_not_in_time_windows()

unsigned long USM::get_stats_not_in_time_windows ( ) const

inline

Get the number of received messages outside time window.

Returns: - usmStatsNotInTimeWindows

Definition at line 726 of file usm_v3.h.

◆ get_stats_unknown_engine_ids()

unsigned long USM::get_stats_unknown_engine_ids ( ) const

inline

Get the number of received messages with a unknown engineID.

Returns: - usmStatsUnknownEngineIDs

Definition at line 742 of file usm_v3.h.

◆ get_stats_unknown_user_names()

unsigned long USM::get_stats_unknown_user_names ( ) const

inline

Get the number of received messages with a unknown userName.

Returns: - usmStatsUnknownUserNames

Definition at line 734 of file usm_v3.h.

◆ get_stats_unsupported_sec_levels()

unsigned long USM::get_stats_unsupported_sec_levels ( ) const

inline

Get the number of received messages with an unsupported securityLevel.

Returns: - usmStatsUnsupportedSecLevels

Definition at line 718 of file usm_v3.h.

◆ get_stats_wrong_digests()

unsigned long USM::get_stats_wrong_digests ( ) const

inline

Get the number of received messages with a wrong digest.

Returns: - usmStatsWrongDigests

Definition at line 750 of file usm_v3.h.

◆ get_time()

int USM::get_time	(	const OctetStr &	engine_id,
		long int *	engine_boots,
		long int *	engine_time
	)

Return engineBoots and engineTime for a given engineID.

Parameters

engine_id	- The engineID of the SNMP entity
engine_boots	- OUT: boot counter (0 if not found)
engine_time	- OUT: engine time (0 if not found)

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (entry found, values are filled) SNMPv3_USM_UNKNOWN_ENGINEID ( not found)

◆ get_user() [1/3]

struct UsmUser* USM::get_user	(	const OctetStr &	engine_id,
		const OctetStr &	security_name
	)

Search for a user with the given securityName and engineID in the usmUserTable and return the entry.

If no entry could be found, the usmUserNameTable is searched for the given securityName. If this table has an entry of this user, a localized entry is generated, added to the usmUserTable and returned to the caller.

The caller has to call free_user() with the returned struct.

Parameters

engine_id	-
security_name	-

Returns: - a pointer to the structure if an entry could be found or was generated, NULL for all errors

◆ get_user() [2/3]

const struct UsmUserTableEntry* USM::get_user ( int number )

Protected (for agent++):

Get the user at the specified position of the usmUserTable.

The returned pointer must NOT be deleted!

Note: lock_user_table() and unlock_user_table() must be used for thread synchronization.

Parameters

number - get the entry at position number (1...)

Returns: - a pointer to the structure or NULL if number is out of range

◆ get_user() [3/3]

const struct UsmUserNameTableEntry* USM::get_user ( const OctetStr & security_name )

Get the properties of the specified user.

The returned pointer must NOT be deleted!

Note: lock_user_table() and unlock_user_table() must be used for thread synchronization.

Parameters

security_name - The security name of the user

Returns: - a pointer to the structure or NULL if number is out of range

◆ get_user_count()

int USM::get_user_count ( ) const

Protected (for agent++):

Get the number of elements in the usmUserTable

Note: lock_user_table() and unlock_user_table() must be used for thread synchronization.

Returns: - number of elements

◆ get_user_name()

int USM::get_user_name	(	unsigned char *	user_name,
		long int *	user_name_len,
		const unsigned char *	security_name,
		const long int	security_name_len
	)

Get the user name from a security name.

Parameters

user_name	- Buffer for the userName
user_name_len	- Has to be set to the max length of the buffer. Is set to the length of the found securityName or to 0 if not found.
security_name	-
security_name_len	-

Returns: - SNMPv3_USM_ERROR (not initialized, not found, buffer too small), SNMPv3_USM_OK

◆ inc_stats_decryption_errors()

void USM::inc_stats_decryption_errors ( )

◆ inc_stats_not_in_time_windows()

void USM::inc_stats_not_in_time_windows ( )

◆ inc_stats_unknown_engine_ids()

void USM::inc_stats_unknown_engine_ids ( )

◆ inc_stats_unknown_user_names()

void USM::inc_stats_unknown_user_names ( )

◆ inc_stats_unsupported_sec_levels()

void USM::inc_stats_unsupported_sec_levels ( )

Increase the stats counter.

Should only be used by agent++.

◆ inc_stats_wrong_digests()

void USM::inc_stats_wrong_digests ( )

◆ is_discovery_enabled()

bool USM::is_discovery_enabled ( ) const

inline

Return TRUE if the USM discovery mode is enabled, FALSE else.

Definition at line 279 of file usm_v3.h.

◆ key_update_abort()

void USM::key_update_abort ( struct UsmKeyUpdate * uku )

Abort the local key update.

Parameters

uku	- The pointer returned by usmPrepareKeyUpdate()

◆ key_update_commit()

int USM::key_update_commit	(	struct UsmKeyUpdate *	uku,
		int	update_type
	)

Commit the local key update.

Parameters

uku	- The pointer returned by usmPrepareKeyUpdate()
update_type	- One of USM_KeyUpdate, USM_PasswordKeyUpdate, USM_PasswordAllKeyUpdate

Returns: - SNMPv3_USM_ERROR, SNMPv3_USM_OK

◆ key_update_prepare()

struct UsmKeyUpdate* USM::key_update_prepare	(	const OctetStr &	securityName,
		SnmpTarget &	target,
		const OctetStr &	newPassword,
		Pdu &	pdu,
		int	type,
		int &	status,
		const OctetStr &	oldpass = `""`,
		const OctetStr &	oldengid = `""`,
		const OctetStr &	newengid = `""`
	)

Prepare a key update in the USM.

The following procedure is used: To prepare the key update, this function adds the necessary variable bindings to the Pdu to do the key update on the target SNMP entity. The Pdu has to be sent to the target. If the key update on the target is successful, usmCommitKeyUpdate() has to be called to do the local key update. On failure usmAbortKeyUpdate() has to be called to free temporary resources.

Parameters

securityName	- The name of the user
target	- A target to identify the SNMP entity on which the key will be updated
newPassword	- The new password for the user
pdu	- A PDU into which this function adds the VBs needed to change the keys on the target
type	- Indicates how and which key should be changed: possible values are: AUTHKEY, PRIVKEY and OWNAUTHKEY, OWNPRIVKEY.
status	- The return status: SNMPv3_USM_OK or one of the error codes

Returns: - A structure, that is needed to commit/abort the key update. If an error occurs, the return value is NULL

◆ load_localized_users()

int USM::load_localized_users ( const char * file )

Load localized users from a file.

Parameters

file	- filename including path

Returns: SNMPv3_USM_ERROR, SNMPv3_USM_FILEOPEN_ERROR, SNMPv3_USM_FILEREAD_ERROR or SNMPv3_USM_OK

◆ load_users()

int USM::load_users ( const char * file )

Load users with their passwords from a file.

Parameters

file	- filename including path

Returns: SNMPv3_USM_ERROR, SNMPv3_USM_FILEOPEN_ERROR, SNMPv3_USM_FILEREAD_ERROR or SNMPv3_USM_OK

◆ lock_user_name_table()

void USM::lock_user_name_table ( )

Lock the UsmUserNameTable for access through peek_first_user() and peek_next_user().

◆ lock_user_table()

void USM::lock_user_table ( )

Lock the UsmUserTable for access through peek_first_luser() and peek_next_luser().

◆ peek_first_luser()

const UsmUserTableEntry* USM::peek_first_luser ( )

Get a const pointer to the first entry of the UsmUserTable.

Note: Use lock_user_table() and unlock_user_table() for thread safety.

◆ peek_first_user()

const UsmUserNameTableEntry* USM::peek_first_user ( )

Get a const pointer to the first entry of the UsmUserNameTable.

Note: Use lock_user_name_table() and unlock_user_name_table() for thread safety.

◆ peek_next_luser()

const UsmUserTableEntry* USM::peek_next_luser ( const UsmUserTableEntry * e )

Get a const pointer to the next entry of the UsmUserTable.

Note: Use lock_user_table() and unlock_user_table() for thread safety.

◆ peek_next_user()

const UsmUserNameTableEntry* USM::peek_next_user ( const UsmUserNameTableEntry * e )

Get a const pointer to the next entry of the UsmUserNameTable.

Note: Use lock_user_name_table() and unlock_user_name_table() for thread safety.

◆ process_msg()

int USM::process_msg	(	int	maxMessageSize,
		unsigned char *	securityParameters,
		int	securityParametersLength,
		int	securityParametersPosition,
		long int	securityLevel,
		unsigned char *	wholeMsg,
		int	wholeMsgLength,
		unsigned char *	msgData,
		int	msgDataLength,
		OctetStr &	security_engine_id,
		OctetStr &	security_name,
		unsigned char *	scopedPDU,
		int *	scopedPDULength,
		long *	maxSizeResponseScopedPDU,
		struct SecurityStateReference *	securityStateReference,
		const UdpAddress &	fromAddress
	)

protected

Parse a received message.

Parameters

maxMessageSize	- The maximum message size of the snding SNMP entity.
securityParameters	- The security parameters as received
securityParametersLength	- The length of the security parameters
securityParametersPosition	- The position of the security parameters in the message
securityLevel	- The securityLevel of the message
wholeMsg	- The buffer with the whole message
wholeMsgLength	- The length of the whole message
msgData	- The buffer with the messageData
msgDataLength	- The length of the messageData buffer
security_engine_id	- OUT: the authoritative engineID
security_name	- OUT: the name of the user
scopedPDU	- OUT: buffer containing the scopedPDU
scopedPDULength	- IN: length of the buffer OUT: length of the scopedPDU
maxSizeResponseScopedPDU	- OUT: maximum size for a scopedPDU in a response message
securityStateReference	- OUT: the securityStateReference
fromAddress	- IN: Address of the sender

Returns: - SNMPv3_USM_OK on success. See snmperrs.h for the error codes of the USM.

◆ remove_all_users()

int USM::remove_all_users ( )

Clear all user configuration from this USM instance.

This method is not synchronized. Do not use it while the USM is being used by other threads.

Returns: SNMPv3_USM_OK on success.

◆ remove_engine_id()

int USM::remove_engine_id ( const OctetStr & engine_id )

Delete this engine id form all USM tables (users and engine time).

Parameters

engine_id - the engine id

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (entries deleted or not in table)

◆ remove_time_information()

int USM::remove_time_information ( const OctetStr & engine_id )

Delete the time information for the given engine id.

Parameters

engine_id - the engine id

Returns: - SNMPv3_USM_ERROR (not initialized), SNMPv3_USM_OK (entry deleted or not in table)

◆ save_localized_users()

int USM::save_localized_users ( const char * file )

Save all localized users into a file.

Parameters

file	- filename including path

Returns: SNMPv3_USM_ERROR, SNMPv3_USM_FILECREATE_ERROR, SNMPv3_USM_FILERENAME_ERROR or SNMPv3_USM_OK

◆ save_users()

int USM::save_users ( const char * file )

Save all users with their passwords into a file.

Parameters

file	- filename including path

Returns: SNMPv3_USM_ERROR, SNMPv3_USM_FILECREATE_ERROR, SNMPv3_USM_FILERENAME_ERROR or SNMPv3_USM_OK

◆ set_discovery_mode()

void USM::set_discovery_mode ( )

inline

Enables the discovery mode of the USM, i.e.

the USM accepts all messages with unknown engine ids and adds these engine ids to its tables.

Definition at line 268 of file usm_v3.h.

◆ unlock_user_name_table()

void USM::unlock_user_name_table ( )

Unlock the UsmUserNameTable after access through peek_first_user() and peek_next_user().

◆ unlock_user_table()

void USM::unlock_user_table ( )

Unlock the UsmUserTable after access through peek_first_luser() and peek_next_luser().

◆ unset_discovery_mode()

void USM::unset_discovery_mode ( )

inline

Disables the discovery mode of the USM, i.e.

the USM will not accept any message with an unknown engine id.

Definition at line 274 of file usm_v3.h.

◆ update_key()

int USM::update_key	(	const unsigned char *	user_name,
		const long	user_name_len,
		const unsigned char *	engine_id,
		const long	engine_id_len,
		const unsigned char *	new_key,
		const long	new_key_len,
		const int	type_of_key
	)

Replace a localized key of the user and engineID in the usmUserTable.

Parameters

user_name	- The name of the user in the USM
user_name_len	- The length of the user name
engine_id	- Change the localized key for the SNMP entity with this engine id
engine_id_len	- The length of the engine id
new_key	- The new key
new_key_len	- The length of the new key
type_of_key	- AUTHKEY, OWNAUTHKEY, PRIVKEY or OWNPRIVKEY

Returns: - SNMPv3_USM_ERROR (no such entry or not initialized), SNMPv3_USM_OK

Friends And Related Function Documentation

◆ v3MP

friend class v3MP

friend

Definition at line 243 of file usm_v3.h.

Member Data Documentation

◆ auth_priv

AuthPriv* USM::auth_priv

private

Definition at line 1087 of file usm_v3.h.

◆ discovery_mode

bool USM::discovery_mode

private

Definition at line 1076 of file usm_v3.h.

◆ local_snmp_engine_id

OctetStr USM::local_snmp_engine_id

private

local snmp engine id

Definition at line 1072 of file usm_v3.h.

◆ usm_add_user_cb

usm_add_user_callback USM::usm_add_user_cb

private

Definition at line 1099 of file usm_v3.h.

◆ usm_time_table

USMTimeTable* USM::usm_time_table

private

Definition at line 1090 of file usm_v3.h.

◆ usm_user_name_table

USMUserNameTable* USM::usm_user_name_table

private

Definition at line 1093 of file usm_v3.h.

◆ usm_user_table

USMUserTable* USM::usm_user_table

private

Definition at line 1096 of file usm_v3.h.

◆ usmStatsDecryptionErrors

unsigned int USM::usmStatsDecryptionErrors

private

Definition at line 1084 of file usm_v3.h.

◆ usmStatsNotInTimeWindows

unsigned int USM::usmStatsNotInTimeWindows

private

Definition at line 1080 of file usm_v3.h.

◆ usmStatsUnknownEngineIDs

unsigned int USM::usmStatsUnknownEngineIDs

private

Definition at line 1082 of file usm_v3.h.

◆ usmStatsUnknownUserNames

unsigned int USM::usmStatsUnknownUserNames

private

Definition at line 1081 of file usm_v3.h.

◆ usmStatsUnsupportedSecLevels

unsigned int USM::usmStatsUnsupportedSecLevels

private

Definition at line 1079 of file usm_v3.h.

◆ usmStatsWrongDigests

unsigned int USM::usmStatsWrongDigests

private

Definition at line 1083 of file usm_v3.h.

◆ v3mp

const v3MP* USM::v3mp

private

Pointer to the v3MP that created this object.

Definition at line 1073 of file usm_v3.h.

The documentation for this class was generated from the following file:

usm_v3.h

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ USM()

◆ ~USM()

Member Function Documentation

◆ add_localized_user()

◆ add_user_added_callback()

◆ add_usm_user() [1/4]

◆ add_usm_user() [2/4]

◆ add_usm_user() [3/4]

◆ add_usm_user() [4/4]

◆ build_localized_keys()

◆ build_sec_params()

◆ build_whole_msg()

◆ delete_localized_user() [1/2]

◆ delete_localized_user() [2/2]

◆ delete_sec_parameters()

◆ delete_sec_state_reference()

◆ delete_user_ptr()

◆ delete_usm_user()

◆ free_user()

◆ generate_msg()

◆ get_auth_priv()

◆ get_local_engine_id()

◆ get_local_time()

◆ get_new_sec_state_reference()

◆ get_security_name()

◆ get_stats_decryption_errors()

◆ get_stats_not_in_time_windows()

◆ get_stats_unknown_engine_ids()

◆ get_stats_unknown_user_names()

◆ get_stats_unsupported_sec_levels()

◆ get_stats_wrong_digests()

◆ get_time()

◆ get_user() [1/3]

◆ get_user() [2/3]

◆ get_user() [3/3]

◆ get_user_count()

◆ get_user_name()

◆ inc_stats_decryption_errors()

◆ inc_stats_not_in_time_windows()

◆ inc_stats_unknown_engine_ids()

◆ inc_stats_unknown_user_names()

◆ inc_stats_unsupported_sec_levels()

◆ inc_stats_wrong_digests()

◆ is_discovery_enabled()

◆ key_update_abort()

◆ key_update_commit()

◆ key_update_prepare()

◆ load_localized_users()

◆ load_users()

◆ lock_user_name_table()

◆ lock_user_table()

◆ peek_first_luser()

◆ peek_first_user()

◆ peek_next_luser()

◆ peek_next_user()

◆ process_msg()

◆ remove_all_users()

◆ remove_engine_id()

◆ remove_time_information()

◆ save_localized_users()

◆ save_users()

◆ set_discovery_mode()

◆ unlock_user_name_table()

◆ unlock_user_table()

◆ unset_discovery_mode()

◆ update_key()

Friends And Related Function Documentation

◆ v3MP

Member Data Documentation

◆ auth_priv

◆ discovery_mode

◆ local_snmp_engine_id

◆ usm_add_user_cb