The SNMPv3 Message Processing Model (v3MP). More...

#include <mp_v3.h>

Collaboration diagram for v3MP:

[legend]

Classes
class	Cache
	Holds cache entries for currently processed requests. More...

class	EngineIdTable
	The engine id table is used to store known engine ids with corresponding hostadress and port. More...

Public Member Functions
	v3MP (const OctetStr &engine_id, unsigned int engine_boots, int &construct_status)
	Initialize the v3MP. More...

void	get_local_engine_id (OctetStr &id)
	Get the engine id of this SNMP entity. More...

const OctetStr &	get_local_engine_id () const
	Get the engine id of this SNMP entity as a OctetStr reference. More...

USM *	get_usm ()
	Get a pointer to the USM object that is used by the v3MP. More...

	~v3MP ()
	Free all allocated ressources of the v3MP and leave it in an uninitialized state. More...

int	add_to_engine_id_table (const OctetStr &engine_id, const OctetStr &host, int port)
	Add an entry to the engine id table. More...

int	remove_from_engine_id_table (const OctetStr &host, int port)
	Remove an entry from the engine id table. More...

int	remove_from_engine_id_table (const OctetStr &engine_id)
	Remove an entry from the engine id table. More...

int	get_from_engine_id_table (OctetStr &engine_id, const OctetStr &hostport) const
	Get the engine id of the SNMP entity at the given host/port. More...

int	get_from_engine_id_table (OctetStr &engineID, const OctetStr &host, int port) const
	Get the engineID of the SNMP entity at the given host/port. More...

int	reset_engine_id_table ()
	Remove all entries from the engine id table. More...

int	remove_engine_id (const OctetStr &engine_id)
	Remove all occurences of this engine id from v3MP and USM. More...

unsigned long	get_stats_unknown_security_models () const
	Get the value of the status counter snmpUnknownSecurityModels. More...

unsigned long	get_stats_invalid_msgs () const
	Get the value of the status counter snmpInvalidMsgs. More...

unsigned long	get_stats_unknown_pdu_handlers () const
	Get the value of the status counter snmpUnknownPDUHandlers. More...

void	inc_stats_unknown_security_models ()
	Increment the value of the status counter snmpUnknownSecurityModels. More...

void	inc_stats_invalid_msgs ()
	Increment the value of the status counter snmpInvalidMsgs. More...

void	inc_stats_unknown_pdu_handlers ()
	Increment the value of the status counter snmpUnknownPDUHandlers. More...

void	delete_from_cache (unsigned long requestID, unsigned long messageID, const bool local_request)
	Delete the entry with the given request id from the cache. More...

Static Public Attributes
static v3MP *	I

Protected Member Functions
int	snmp_parse (Snmp snmp_session, struct snmp_pdu pdu, unsigned char *inBuf, int inBufLength, OctetStr &securityEngineID, OctetStr &securityName, OctetStr &contextEngineID, OctetStr &contextName, long &securityLevel, long &msgSecurityModel, snmp_version &spp_version, UdpAddress from_address)
	Parse the given buffer as a SNMPv3-Message. More...

int	snmp_build (struct snmp_pdu pdu, unsigned char packet, int *out_length, const OctetStr &securityEngineID, const OctetStr &securityNameIn, int securityModel, int securityLevel, const OctetStr &contextEngineID, const OctetStr &contextName)
	Do the complete process of encoding the given values into the buffer ready to send to the target. More...

void	delete_from_cache (unsigned long requestID, const bool local_request=true)
	Delete the entry with the given request id from the cache. More...

Static Protected Member Functions
static bool	is_v3_msg (unsigned char *buffer, int length)
	Tests if the given buffer contains a SNMPv3-Message. More...

Private Member Functions
int	send_report (unsigned char scopedPDU, int scopedPDULength, struct snmp_pdu pdu, int errorCode, int sLevel, int sModel, OctetStr &sName, UdpAddress &destination, Snmp *snmp_session)
	Send a report message. More...

Private Attributes
EngineIdTable	engine_id_table

Cache	cache

unsigned char *	own_engine_id

int	own_engine_id_len

OctetStr	own_engine_id_oct

unsigned int	cur_msg_id
	msgID to use for next message More...

SNMP_PP_MUTABLE SnmpSynchronized	cur_msg_id_lock

USM *	usm
	the USM object used More...

unsigned int	snmpUnknownSecurityModels

unsigned int	snmpInvalidMsgs

unsigned int	snmpUnknownPDUHandlers

Friends
class	SnmpMessage

class	CSNMPMessageQueue

Detailed Description

The SNMPv3 Message Processing Model (v3MP).

If SNMPv3 is used, the application needs to create one object of this class. This object will automatically create an object of the USM class. A pointer to this object is returned from the get_usm() method. See the USM documentation for a description on how to create and delete users.

The only thing that may be configured after creation of the v3MP is the engine id table of the v3MP. Entries for other SNMP entities can be added through add_to_engine_id_table(). It is only required to add entries to this table if you want to disable engine id discovery and/or you don't want the delay caused by the automatic engine id discovery of SNMPv3.

Definition at line 107 of file mp_v3.h.

Constructor & Destructor Documentation

◆ v3MP()

v3MP::v3MP	(	const OctetStr &	engine_id,
		unsigned int	engine_boots,
		int &	construct_status
	)

Initialize the v3MP.

Set the engineID of this SNMP entity and the Snmp object used to send reports. This function creates a new USM object that can be configured after getting a pointer to it through get_usm().

The user is responsible to save and restore and increment the snmpEngineBoots counter (The functions getBootCounter() and saveBootCounter() can be used to do this.).

Parameters

engine_id	- The locale engine id
engine_boots	- The new value for the snmpEngineBoots counter
construct_status	- OUT: SNMPv3_MP_OK or SNMPv3_MP_ERROR

◆ ~v3MP()

v3MP::~v3MP ( )

Free all allocated ressources of the v3MP and leave it in an uninitialized state.

After a call to this function, you can use mpInit() to reinitialize the v3MP.

Member Function Documentation

◆ add_to_engine_id_table()

int v3MP::add_to_engine_id_table	(	const OctetStr &	engine_id,
		const OctetStr &	host,
		int	port
	)

inline

Add an entry to the engine id table.

In this table all known engine ids are stored. If the discovery mode of the USM is enabled, snmp++ will add entries to this table whenever a new engine id is dicovered.

Parameters

engine_id	- The engine id
host	- The numerical IP address
port	- The port

Returns: - SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 174 of file mp_v3.h.

◆ delete_from_cache() [1/2]

void v3MP::delete_from_cache	(	unsigned long	requestID,
		const bool	local_request = `true`
	)

inlineprotected

Delete the entry with the given request id from the cache.

This function is used in eventlist.cpp when a request has timed out.

Parameters

requestID	- The request id.
local_request	- Does the request id belong to a local or to a remote request?

Definition at line 374 of file mp_v3.h.

◆ delete_from_cache() [2/2]

void v3MP::delete_from_cache	(	unsigned long	requestID,
		unsigned long	messageID,
		const bool	local_request
	)

inline

Delete the entry with the given request id from the cache.

This function is used in agent++ RequestList.

Parameters

requestID	- The request id.
messageID	- The message id.
local_request	- Does the request id belong to a local or to a remote request?

Definition at line 389 of file mp_v3.h.

◆ get_from_engine_id_table() [1/2]

int v3MP::get_from_engine_id_table	(	OctetStr &	engine_id,
		const OctetStr &	hostport
	)		const

inline

Get the engine id of the SNMP entity at the given host/port.

Parameters

engine_id	- OUT: The engine id
hostport	- The numerical IP address and port (syntax: a.b.c.d/port)

Returns: - SNMPv3_MP_NOT_INITIALIZED, SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 209 of file mp_v3.h.

◆ get_from_engine_id_table() [2/2]

int v3MP::get_from_engine_id_table	(	OctetStr &	engineID,
		const OctetStr &	host,
		int	port
	)		const

inline

Get the engineID of the SNMP entity at the given host/port.

Parameters

engineID	- OUT: The engineID
host	- The numerical IP address
port	- The port

Returns: - SNMPv3_MP_NOT_INITIALIZED, SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 223 of file mp_v3.h.

◆ get_local_engine_id() [1/2]

void v3MP::get_local_engine_id ( OctetStr & id )

inline

Get the engine id of this SNMP entity.

Parameters

id	- OUT: The engineID of this SNMP entity

Returns: - SNMPv3_MP_OK or SNMPv3_MP_ERROR

Definition at line 138 of file mp_v3.h.

◆ get_local_engine_id() [2/2]

const OctetStr& v3MP::get_local_engine_id ( ) const

inline

Get the engine id of this SNMP entity as a OctetStr reference.

Returns: Local engine id.

Definition at line 145 of file mp_v3.h.

◆ get_stats_invalid_msgs()

unsigned long v3MP::get_stats_invalid_msgs ( ) const

inline

Get the value of the status counter snmpInvalidMsgs.

Returns: - The status counter

Definition at line 261 of file mp_v3.h.

◆ get_stats_unknown_pdu_handlers()

unsigned long v3MP::get_stats_unknown_pdu_handlers ( ) const

inline

Get the value of the status counter snmpUnknownPDUHandlers.

Returns: - The status counter

Definition at line 269 of file mp_v3.h.

◆ get_stats_unknown_security_models()

unsigned long v3MP::get_stats_unknown_security_models ( ) const

inline

Get the value of the status counter snmpUnknownSecurityModels.

Returns: - The status counter

Definition at line 253 of file mp_v3.h.

◆ get_usm()

USM* v3MP::get_usm ( )

inline

Get a pointer to the USM object that is used by the v3MP.

Definition at line 151 of file mp_v3.h.

◆ inc_stats_invalid_msgs()

void v3MP::inc_stats_invalid_msgs ( )

inline

Increment the value of the status counter snmpInvalidMsgs.

Definition at line 281 of file mp_v3.h.

◆ inc_stats_unknown_pdu_handlers()

void v3MP::inc_stats_unknown_pdu_handlers ( )

inline

Increment the value of the status counter snmpUnknownPDUHandlers.

Definition at line 286 of file mp_v3.h.

◆ inc_stats_unknown_security_models()

void v3MP::inc_stats_unknown_security_models ( )

inline

Increment the value of the status counter snmpUnknownSecurityModels.

Definition at line 275 of file mp_v3.h.

◆ is_v3_msg()

static bool v3MP::is_v3_msg	(	unsigned char *	buffer,
		int	length
	)

staticprotected

Tests if the given buffer contains a SNMPv3-Message.

The buffer is only parsed to extract the version of the message, no other checks are made.

Parameters

buffer	- The message
length	- The length of the message

Returns: - TRUE if the version could be extracted and it is a SNMPv3 message. On any error: FALSE.

Referenced by SnmpMessage::is_v3_message().

◆ remove_engine_id()

int v3MP::remove_engine_id ( const OctetStr & engine_id )

Remove all occurences of this engine id from v3MP and USM.

Parameters

engine_id - The engine id to remove

Returns: - SNMPv3_MP_NOT_INITIALIZED, SNMPv3_MP_ERROR, SNMPv3_MP_OK

◆ remove_from_engine_id_table() [1/2]

int v3MP::remove_from_engine_id_table	(	const OctetStr &	host,
		int	port
	)

inline

Remove an entry from the engine id table.

Parameters

host	- The numerical IP address
port	- The port

Returns: - SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 186 of file mp_v3.h.

◆ remove_from_engine_id_table() [2/2]

int v3MP::remove_from_engine_id_table ( const OctetStr & engine_id )

inline

Remove an entry from the engine id table.

Parameters

engine_id - The engine id

Returns: - SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 196 of file mp_v3.h.

◆ reset_engine_id_table()

int v3MP::reset_engine_id_table ( )

inline

Remove all entries from the engine id table.

Returns: - SNMPv3_MP_NOT_INITIALIZED, SNMPv3_MP_ERROR, SNMPv3_MP_OK

Definition at line 233 of file mp_v3.h.

◆ send_report()

int v3MP::send_report	(	unsigned char *	scopedPDU,
		int	scopedPDULength,
		struct snmp_pdu *	pdu,
		int	errorCode,
		int	sLevel,
		int	sModel,
		OctetStr &	sName,
		UdpAddress &	destination,
		Snmp *	snmp_session
	)

private

Send a report message.

Parameters

scopedPDU	- The scopedPDU as received. If the pdu is not encrypted, the request id is extracted
scopedPDULength	- The lkength of the scopedPDU
pdu	- The pdu structure.
errorCode	- The code of the error that occured.
sLevel	- Send the report with this security level.
sModel	- Use this security model.
sName	- Use this security name
destination	- Send the report to this address.
snmp_session	- Snmp session to use for sending a report

Returns: - SNMPv3_MP_ERROR, SNMPv3_MP_OK

◆ snmp_build()

int v3MP::snmp_build	(	struct snmp_pdu *	pdu,
		unsigned char *	packet,
		int *	out_length,
		const OctetStr &	securityEngineID,
		const OctetStr &	securityNameIn,
		int	securityModel,
		int	securityLevel,
		const OctetStr &	contextEngineID,
		const OctetStr &	contextName
	)

protected

Do the complete process of encoding the given values into the buffer ready to send to the target.

Parameters

pdu	- The pdu structure
packet	- The buffer to store the serialized message
out_length	- IN: Length of the buffer, OUT: Length of the message
securityEngineID	- The securityEngineID
securityNameIn	- The securityName
securityModel	- Use this security model
securityLevel	- Use this security level
contextEngineID	- The contextEngineID
contextName	- The contextName

Returns: - SNMPv3_MP_OK or any error listed in snmperr.h

◆ snmp_parse()

int v3MP::snmp_parse	(	Snmp *	snmp_session,
		struct snmp_pdu *	pdu,
		unsigned char *	inBuf,
		int	inBufLength,
		OctetStr &	securityEngineID,
		OctetStr &	securityName,
		OctetStr &	contextEngineID,
		OctetStr &	contextName,
		long &	securityLevel,
		long &	msgSecurityModel,
		snmp_version &	spp_version,
		UdpAddress	from_address
	)

protected

Parse the given buffer as a SNMPv3-Message.

Parameters

snmp_session	- IN: The session used to receive the msg
pdu	- OUT: Parsed values are put into this struct
inBuf	- The buffer to parse
inBufLength	- The length of the buffer
securityEngineID	- OUT: The parsed securityEngineID
securityName	- OUT: The parsed securityName
contextEngineID	- OUT: The parsed contextEngineID
contextName	- OUT: The parsed contextName
securityLevel	- OUT: The parsed security level
msgSecurityModel	- OUT: The security model used
spp_version	- OUT: SNMP version (SNMPv3)
from_address	- Where the message came from (used to send a report if neccessary)

Returns: - SNMPv3_MP_OK or any error listed in snmperr.h

Friends And Related Function Documentation

◆ CSNMPMessageQueue

friend class CSNMPMessageQueue

friend

Definition at line 110 of file mp_v3.h.

◆ SnmpMessage

friend class SnmpMessage

friend

Definition at line 109 of file mp_v3.h.

Member Data Documentation

◆ cache

Cache v3MP::cache

private

Definition at line 644 of file mp_v3.h.

◆ cur_msg_id

unsigned int v3MP::cur_msg_id

private

msgID to use for next message

Definition at line 651 of file mp_v3.h.

◆ cur_msg_id_lock

SNMP_PP_MUTABLE SnmpSynchronized v3MP::cur_msg_id_lock

private

Definition at line 652 of file mp_v3.h.

◆ engine_id_table

EngineIdTable v3MP::engine_id_table

private

Definition at line 643 of file mp_v3.h.

◆ I

v3MP* v3MP::I

static

Definition at line 286 of file mp_v3.h.

◆ own_engine_id

unsigned char* v3MP::own_engine_id

private

Definition at line 647 of file mp_v3.h.

◆ own_engine_id_len

int v3MP::own_engine_id_len

private

Definition at line 648 of file mp_v3.h.

◆ own_engine_id_oct

OctetStr v3MP::own_engine_id_oct

private

Definition at line 649 of file mp_v3.h.

◆ snmpInvalidMsgs

unsigned int v3MP::snmpInvalidMsgs

private

Definition at line 658 of file mp_v3.h.

◆ snmpUnknownPDUHandlers

unsigned int v3MP::snmpUnknownPDUHandlers

private

Definition at line 659 of file mp_v3.h.

◆ snmpUnknownSecurityModels

unsigned int v3MP::snmpUnknownSecurityModels

private

Definition at line 657 of file mp_v3.h.

◆ usm

USM* v3MP::usm

private

the USM object used

Definition at line 654 of file mp_v3.h.

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

mp_v3.h

Classes

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ v3MP()

◆ ~v3MP()

Member Function Documentation

◆ add_to_engine_id_table()

◆ delete_from_cache() [1/2]

◆ delete_from_cache() [2/2]

◆ get_from_engine_id_table() [1/2]

◆ get_from_engine_id_table() [2/2]

◆ get_local_engine_id() [1/2]

◆ get_local_engine_id() [2/2]

◆ get_stats_invalid_msgs()

◆ get_stats_unknown_pdu_handlers()

◆ get_stats_unknown_security_models()

◆ get_usm()

◆ inc_stats_invalid_msgs()

◆ inc_stats_unknown_pdu_handlers()

◆ inc_stats_unknown_security_models()

◆ is_v3_msg()

◆ remove_engine_id()

◆ remove_from_engine_id_table() [1/2]

◆ remove_from_engine_id_table() [2/2]

◆ reset_engine_id_table()

◆ send_report()

◆ snmp_build()

◆ snmp_parse()

Friends And Related Function Documentation

◆ CSNMPMessageQueue

◆ SnmpMessage

Member Data Documentation

◆ cache

◆ cur_msg_id

◆ cur_msg_id_lock

◆ engine_id_table

◆ I

◆ own_engine_id

◆ own_engine_id_len

◆ own_engine_id_oct

◆ snmpInvalidMsgs

◆ snmpUnknownPDUHandlers

◆ snmpUnknownSecurityModels

◆ usm