The User-based Security Model (USM) associates a user (by "user name") with security information. More...

#include <usm.hpp>

Inheritance diagram for USM:

Public Member Functions
	USM ()
	Default constructor; this is essentially "noAuthNoPriv". More...

	USM (const std::string &username, Authentication::Type authentication, const std::string &authenticationPassword, Encryption::Type encryption, const std::string &encryptionPassword) throw ( Exception )
	This constructs a USM instance with the specified parameters. More...

	USM (const USM &usm)
	Copy constructor. More...

std::string	authoritativeEngineID () const
	This returns the authoritative engine ID. More...

void	authoritativeEngineID (const std::string &authoritativeEngineID)
	This sets the authoritative engine ID. More...

uint32_t	authoritativeEngineBoots () const
	This returns the number of times that the engine has booted. More...

void	authoritativeEngineBoots (uint32_t authoritativeEngineBoots)
	This updates the number of times that the engine has booted. More...

std::chrono::seconds	authoritativeEngineTime () const
	This returns the amount of time since the last boot of the engine, measured in seconds. More...

void	authoritativeEngineTime (std::chrono::seconds authoritativeEngineTime)
	This updates the number of time since the last boot of the engine. More...

bool	isAuthenticated () const
	TODO: THIS.

void	updateTimeFromClock ()
	This will update the value of "authoritativeEngineTime" based on the amount of wall time elapsed since the last update. More...

std::string	username () const
	This returns the user name. More...

Authentication::Type	authentication () const
	This returns the type of authentication used. More...

std::string	authenticationPassword () const
	This returns the authentication password. More...

std::string	authenticationKey () const
	This returns the authentication key. More...

Encryption::Type	encryption () const
	This returns the type of encryption used. More...

std::string	encryptionPassword () const
	This returns the encryption password. More...

std::string	encryptionKey () const
	This returns the encryption key. More...

Public Member Functions inherited from SecurityModel
Type	type () const
	This returns the identifier of the security model that this instance represents. More...

Protected Attributes
std::string	_username
	The user name. More...

Authentication::Type	_authentication
	The type of authentication used.

std::string	_authenticationPassword
	If authentication is to be used, then the user will have a secret authentication password. More...

std::string	_authenticationKey
	This is the actual authentication "key" to be used. More...

Encryption::Type	_encryption
	The type of encryption used. More...

std::string	_encryptionPassword
	If encryption is to be used, then the user will have a secret encryption password. More...

std::string	_encryptionKey
	This is the actual encryption "key" to be used. More...

std::string	_authoritativeEngineID
	The authoritative engine ID OCTET STRING.

uint32_t	_authoritativeEngineBoots
	The number of times that the engine has booted. More...

std::chrono::seconds	_authoritativeEngineTime
	The amount of time since the last boot of the engine, measured in seconds. More...

std::chrono::system_clock::time_point	lastUpdateTime
	This is the last time that authoritative engine information was updated. More...

Protected Attributes inherited from SecurityModel
Type	_type
	This is the type of security model that this particular intance represents. More...

Additional Inherited Members
Public Types inherited from SecurityModel
enum	Type { ANY = 0, SNMPv1 = 1, SNMPv2c = 2, USM = 3 }
	This identifies the security model.

Detailed Description

The User-based Security Model (USM) associates a user (by "user name") with security information.

This includes the concepts of "authentication" (making sure that the message was not tampered with) and "privacy" (making sure that the message could not be read by a third party; that is, encryption).

For USM, a user name is required. Authentication is optional, as is encryption (but note that encryption requires authentication).

From RFC-2574, section 1.5: Each SNMP engine maintains two values, snmpEngineBoots and snmpEngineTime, which taken together provide an indication of time at that SNMP engine. Both of these values are included in an authenticated message sent to/received from that SNMP engine. On receipt, the values are checked to ensure that the indicated timeliness value is within a Time Window of the current time. The Time Window represents an administrative upper bound on acceptable delivery delay for protocol messages.

For an SNMP engine to generate a message which an authoritative SNMP engine will accept as authentic, and to verify that a message received from that authoritative SNMP engine is authentic, such an SNMP engine must first achieve timeliness synchronization with the authoritative SNMP engine.

Constructor & Destructor Documentation

USM ( )

Default constructor; this is essentially "noAuthNoPriv".

There is no authentication whatsoever, nor is there any privacy.

USM	(	const std::string &	username,
		Authentication::Type	authentication,
		const std::string &	authenticationPassword,
		Encryption::Type	encryption,
		const std::string &	encryptionPassword
	)
throw	(	Exception
	)

This constructs a USM instance with the specified parameters.

Note that if you specify an encryption type but no authentication type, then this will throw an Exception.

Parameters

username	The username.
authentication	The kind of authentication to use.
authenticationPassword	The authentication secret that will be used, along with the agent engine ID, to generate an authentication key.
encryption	The kind of encryption to use.
encryptionPassword	The encryption secret that will be used, along with the agent engine ID, to generate an encryption key.

Exceptions

Exception

USM ( const USM & usm )

Copy constructor.

Parameters

usm	The USM instance to copy.

Member Function Documentation

Authentication::Type authentication ( ) const

inline

This returns the type of authentication used.

Returns: The type of authentication.

std::string authenticationKey ( ) const

inline

This returns the authentication key.

Returns: The authentication key.

std::string authenticationPassword ( ) const

inline

This returns the authentication password.

This is strictly used to generate the authentication "key".

Returns: The authentication password.

uint32_t authoritativeEngineBoots ( ) const

inline

This returns the number of times that the engine has booted.

Returns: The number of times that the engine has booted.

void authoritativeEngineBoots ( uint32_t authoritativeEngineBoots )

inline

This updates the number of times that the engine has booted.

Parameters

authoritativeEngineBoots The new value for the number of times that the engine has booted.

std::string authoritativeEngineID ( ) const

inline

This returns the authoritative engine ID.

Returns: The authoritative engine ID.

void authoritativeEngineID ( const std::string & authoritativeEngineID )

This sets the authoritative engine ID.

In addition, if authentication is configured, this will update the authentication and encryption keys.

Parameters

authoritativeEngineID The desired authoritative engine ID.

std::chrono::seconds authoritativeEngineTime ( ) const

inline

This returns the amount of time since the last boot of the engine, measured in seconds.

Returns: The amount of time since the last boot of the engine, in seconds.

void authoritativeEngineTime ( std::chrono::seconds authoritativeEngineTime )

inline

This updates the number of time since the last boot of the engine.

Under normal operations, this is updated via updateTimeFromClock(), which uses the system clock to appropriately increment the value. However, this method may be used to set the value exactly.

Parameters

authoritativeEngineTime The new value for the amount of time since the last boot of the engine.

Encryption::Type encryption ( ) const

inline

This returns the type of encryption used.

Returns: The type of encryption.

std::string encryptionKey ( ) const

inline

This returns the encryption key.

Returns: The encryption key.

std::string encryptionPassword ( ) const

inline

This returns the encryption password.

This is strictly used to generate the encryption "key".

Returns: The encryption password.

void updateTimeFromClock ( )

inline

This will update the value of "authoritativeEngineTime" based on the amount of wall time elapsed since the last update.

This is useful because USM requires that a client have a belief about the agent's engine time value.

This is the number of seconds that have elapsed since the last time that we updated the engine time value.

std::string username ( ) const

inline

This returns the user name.

Returns: The user name.

Member Data Documentation

std::string _authenticationKey

protected

This is the actual authentication "key" to be used.

While the "password" might seem like the real thing, it is only truly used to generate a "key" of a known byte length (depending on the type of authentication used). HMAC-MD5-96: 16 bytes. HMAC-SHA-96: 20 bytes.

std::string _authenticationPassword

protected

If authentication is to be used, then the user will have a secret authentication password.

This must be known to both the user and the agent in advance. This password will be used in some capacity (for example, in conjunction with creating an MD5 or SHA checksum) such that the agent can know if the message was tampered with along the way.

uint32_t _authoritativeEngineBoots

protected

The number of times that the engine has booted.

Syntax: INTEGER (0..2147483647)

std::chrono::seconds _authoritativeEngineTime

protected

The amount of time since the last boot of the engine, measured in seconds.

Syntax: INTEGER (0..2147483647)

Encryption::Type _encryption

protected

The type of encryption used.

Note that if encryption is used, then authentication must be used as well.

std::string _encryptionKey

protected

This is the actual encryption "key" to be used.

While the "password" might seem like the real thing, it is only truly used to generate a "key" of a known byte length (depending on the type of encryption used). CBC-DES: 16 bytes. CFB128-AES-128: 16 bytes.

std::string _encryptionPassword

protected

If encryption is to be used, then the user will have a secret encryption password.

This must be known to both the user and the agent in advance. This password will be used, along with some semi-random "salt", to encrypt the data. The salt will be included with the message.

std::string _username

protected

The user name.

OCTET STRING (SIZE(0..32))

std::chrono::system_clock::time_point lastUpdateTime

protected

This is the last time that authoritative engine information was updated.

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

include/public/dangerous/snmp/securitymodel/usm.hpp

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation