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

#include <mp_v3.h>

Collaboration diagram for v3MP:

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 103 of file mp_v3.h.

Constructor & Destructor Documentation

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

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

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 170 of file mp_v3.h.

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 370 of file mp_v3.h.

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 385 of file mp_v3.h.

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 205 of file mp_v3.h.

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 219 of file mp_v3.h.

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 134 of file mp_v3.h.

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 141 of file mp_v3.h.

unsigned long v3MP::get_stats_invalid_msgs ( ) const

inline

Get the value of the status counter snmpInvalidMsgs.

Returns: - The status counter

Definition at line 257 of file mp_v3.h.

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 265 of file mp_v3.h.

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 249 of file mp_v3.h.

USM* v3MP::get_usm ( )

inline

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

Definition at line 147 of file mp_v3.h.

void v3MP::inc_stats_invalid_msgs ( )

inline

Increment the value of the status counter snmpInvalidMsgs.

Definition at line 277 of file mp_v3.h.

void v3MP::inc_stats_unknown_pdu_handlers ( )

inline

Increment the value of the status counter snmpUnknownPDUHandlers.

Definition at line 282 of file mp_v3.h.

void v3MP::inc_stats_unknown_security_models ( )

inline

Increment the value of the status counter snmpUnknownSecurityModels.

Definition at line 271 of file mp_v3.h.

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

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

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 182 of file mp_v3.h.

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 192 of file mp_v3.h.

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 229 of file mp_v3.h.

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

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

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

friend class CSNMPMessageQueue

friend

Definition at line 106 of file mp_v3.h.

friend class SnmpMessage

friend

Definition at line 105 of file mp_v3.h.

Member Data Documentation

Cache v3MP::cache

private

Definition at line 624 of file mp_v3.h.

unsigned int v3MP::cur_msg_id

private

msgID to use for next message

Definition at line 631 of file mp_v3.h.

SNMP_PP_MUTABLE SnmpSynchronized v3MP::cur_msg_id_lock

private

Definition at line 632 of file mp_v3.h.

EngineIdTable v3MP::engine_id_table

private

Definition at line 623 of file mp_v3.h.

v3MP* v3MP::I

static

Definition at line 282 of file mp_v3.h.

unsigned char* v3MP::own_engine_id

private

Definition at line 627 of file mp_v3.h.

int v3MP::own_engine_id_len

private

Definition at line 628 of file mp_v3.h.

OctetStr v3MP::own_engine_id_oct

private

Definition at line 629 of file mp_v3.h.

unsigned int v3MP::snmpInvalidMsgs

private

Definition at line 638 of file mp_v3.h.

unsigned int v3MP::snmpUnknownPDUHandlers

private

Definition at line 639 of file mp_v3.h.

unsigned int v3MP::snmpUnknownSecurityModels

private

Definition at line 637 of file mp_v3.h.

USM* v3MP::usm

private

the USM object used

Definition at line 634 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

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation