SNMP++  3.3.4
USM Class Reference

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

#include <usm_v3.h>

Collaboration diagram for USM:

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 occurences 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 UsmUserget_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...
 
AuthPrivget_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 OctetStrget_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 UsmUserNameTableEntrypeek_first_user ()
 Get a const pointer to the first entry of the UsmUserNameTable. More...
 
const UsmUserNameTableEntrypeek_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 UsmUserTableEntrypeek_first_luser ()
 Get a const pointer to the first entry of the UsmUserTable. More...
 
const UsmUserTableEntrypeek_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 UsmUserTableEntryget_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 acording 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 v3MPv3mp
 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
 
AuthPrivauth_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 233 of file usm_v3.h.

Constructor & Destructor Documentation

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 ( )

Destructor.

Member Function Documentation

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)
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

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)
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)
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)
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 369 of file usm_v3.h.

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
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
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 acording 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
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)
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)
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
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.
void USM::delete_user_ptr ( struct UsmUser user)
inlineprivate

Delete the pointers in the structure.

Parameters
user- The structure that should be deleted
void USM::delete_usm_user ( const OctetStr security_name)

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

Parameters
security_name- the securityName of the user
void USM::free_user ( struct UsmUser *&  user)

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

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.
AuthPriv* USM::get_auth_priv ( )

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

const OctetStr& USM::get_local_engine_id ( ) const
inline

Return the local snmp engine id.

Definition at line 703 of file usm_v3.h.

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)
struct SecurityStateReference* USM::get_new_sec_state_reference ( )
protected

Get a new security state reference (for v3MP).

Returns
- A newly created security state reference.
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
unsigned long USM::get_stats_decryption_errors ( ) const
inline

Get the number of received messages with decryption errors.

Returns
- usmStatsDecryptionErrors

Definition at line 750 of file usm_v3.h.

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 718 of file usm_v3.h.

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 734 of file usm_v3.h.

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 726 of file usm_v3.h.

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 710 of file usm_v3.h.

unsigned long USM::get_stats_wrong_digests ( ) const
inline

Get the number of received messages with a wrong digest.

Returns
- usmStatsWrongDigests

Definition at line 742 of file usm_v3.h.

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)
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
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
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
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
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
void USM::inc_stats_decryption_errors ( )
void USM::inc_stats_not_in_time_windows ( )
void USM::inc_stats_unknown_engine_ids ( )
void USM::inc_stats_unknown_user_names ( )
void USM::inc_stats_unsupported_sec_levels ( )

Increase the stats counter.

Should only be used by agent++.

void USM::inc_stats_wrong_digests ( )
bool USM::is_discovery_enabled ( ) const
inline

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

Definition at line 271 of file usm_v3.h.

void USM::key_update_abort ( struct UsmKeyUpdate *  uku)

Abort the local key update.

Parameters
uku- The pointer returned by usmPrepareKeyUpdate()
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
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 neccessary 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 ressources.

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 funktion adds the VBs needed to change the keys on the target
type- Indicates how and which key should be chaned: possilbe 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
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
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
void USM::lock_user_name_table ( )

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

void USM::lock_user_table ( )

Lock the UsmUserTable for access through peek_first_luser() and peek_next_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.
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.
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.
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.
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.
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.
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)
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)
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
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
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 260 of file usm_v3.h.

void USM::unlock_user_name_table ( )

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

void USM::unlock_user_table ( )

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

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 266 of file usm_v3.h.

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

friend class v3MP
friend

Definition at line 235 of file usm_v3.h.

Member Data Documentation

AuthPriv* USM::auth_priv
private

Definition at line 1079 of file usm_v3.h.

bool USM::discovery_mode
private

Definition at line 1068 of file usm_v3.h.

OctetStr USM::local_snmp_engine_id
private

local snmp engine id

Definition at line 1064 of file usm_v3.h.

usm_add_user_callback USM::usm_add_user_cb
private

Definition at line 1091 of file usm_v3.h.

USMTimeTable* USM::usm_time_table
private

Definition at line 1082 of file usm_v3.h.

USMUserNameTable* USM::usm_user_name_table
private

Definition at line 1085 of file usm_v3.h.

USMUserTable* USM::usm_user_table
private

Definition at line 1088 of file usm_v3.h.

unsigned int USM::usmStatsDecryptionErrors
private

Definition at line 1076 of file usm_v3.h.

unsigned int USM::usmStatsNotInTimeWindows
private

Definition at line 1072 of file usm_v3.h.

unsigned int USM::usmStatsUnknownEngineIDs
private

Definition at line 1074 of file usm_v3.h.

unsigned int USM::usmStatsUnknownUserNames
private

Definition at line 1073 of file usm_v3.h.

unsigned int USM::usmStatsUnsupportedSecLevels
private

Definition at line 1071 of file usm_v3.h.

unsigned int USM::usmStatsWrongDigests
private

Definition at line 1075 of file usm_v3.h.

const v3MP* USM::v3mp
private

Pointer to the v3MP that created this object.

Definition at line 1065 of file usm_v3.h.


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