C# Class SnmpSharpNet.SnmpV3Packet

SNMP version 3 packet implementation class.

Available packet classes are:

SnmpV1Packet
SnmpV1TrapPacket
SnmpV2Packet
SnmpV3Packet

This class is provided to simplify encoding and decoding of packets and to provide consistent interface for users who wish to handle transport part of protocol on their own without using the UdpTarget class. SnmpPacket and derived classes have been developed to implement SNMP version 1, 2 and 3 packet support. For SNMP version 1 and 2 packet, SnmpV1Packet and SnmpV2Packet classes provide sufficient support for encoding and decoding data to/from BER buffers to satisfy requirements of most applications. SNMP version 3 on the other hand requires a lot more information to be passed to the encoder method and returned by the decode method. While using SnmpV3Packet class for full packet handling is possible, transport specific class UdpTarget uses SecureAgentParameters class to store protocol version 3 specific information that carries over from request to request when used on the same SNMP agent and therefore simplifies both initial definition of agents configuration (mostly security) as well as removes the need for repeated initialization of the packet class for subsequent requests. If you decide not to use transport helper class(es) like UdpTarget, BER encoding and decoding and packets is easily done with SnmpPacket derived classes. Example, SNMP version 1 packet encoding:

 SnmpV1Packet packetv1 = new SnmpV1Packet(); packetv1.Community.Set("public"); packetv1.Pdu.Set(mypdu); byte[] berpacket = packetv1.encode();

Example, SNMP version 3 noAuthNoPriv encoding:

 SnmpV3Packet packetv3 = new SnmpV3Packet(); packetv3.noAuthNoPriv("myusername"); packetv3.SetEngineTime(engineTime, engineBoots); // See SNMPv3 discovery process for details packetv3.SetEngineId(engineId); // See SNMPv3 discovery process for details packetv3.IsReportable = true; packetv3.Pdu.Set(mypdu); byte[] berpacket = packetv3.encode();

Example, SNMP version 3 authNoPriv using MD5 authentication packet encoding:

 SnmpV3Packet packetv3 = new SnmpV3Packet(); packetv3.authNoPriv("myusername", "myAuthenticationPassword", AuthenticationDigests.MD5); packetv3.SetEngineTime(engineTime, engineBoots); // See SNMPv3 discovery process for details packetv3.SetEngineId(engineId); // See SNMPv3 discovery process for details packetv3.IsReportable = true; packetv3.Pdu.Set(mypdu); byte[] berpacket = packetv3.encode();

Example, SNMP version 3 authPriv using MD5 authentication and DES encryption packet encoding:

 SnmpV3Packet packetv3 = new SnmpV3Packet(); packetv3.authPriv("myusername", "myAuthenticationPassword", AuthenticationDigests.MD5, "myPrivacyPassword", PrivacyProtocols.DES); packetv3.SetEngineTime(engineTime, engineBoots); // See SNMPv3 discovery process for details packetv3.SetEngineId(engineId); // See SNMPv3 discovery process for details packetv3.IsReportable = true; packetv3.Pdu.Set(mypdu); byte[] berpacket = packetv3.encode();

When decoding SNMP version 3 packets, SnmpV3Packet class needs to be initialized with the same values security values as a request does. This includes, authoritative engine id, engine boots and engine time, if authentication is used, authentication digest and password and for encryption, password and privacy protocol used. Without these parameters packet class will not be able to verify the incoming packet and responses will be discarded even if they are valid.

Inheritance: SnmpPacket

Mostra file Open project: griffina/SnmpSharpNet Class Usage Examples

Protected Properties

Property	Type	Description
_securityModel	Integer32

Public Methods

Method	Description
BuildInformResponse ( ) : SnmpV3Packet	Build SNMP RESPONSE packet for the received INFORM packet.
BuildInformResponse ( SnmpV3Packet informPacket ) : SnmpV3Packet	Build SNMP RESPONSE packet for the INFORM packet class.
DiscoveryRequest ( ) : SnmpV3Packet	Build an SNMP version 3 packet suitable for use in discovery process.
DiscoveryResponse ( Int32 messageId, Int32 requestId, OctetString engineId, Int32 engineBoots, Int32 engineTime, Int32 unknownEngineIdCount ) : SnmpV3Packet	Build SNMP discovery response packet. Manager application has to be able to respond to discovery requests to be able to handle SNMPv3 INFORM notifications. In an INFORM packet, engineId value is set to the manager stations id (unlike all other requests where agent is the authoritative SNMP engine). For the agent to discover appropriate manager engine id, boots and time values (required for authentication and privacy packet handling), manager has to be able to respond to the discovery request.
GenerateAuthenticationKey ( ) : byte[]	Generate authentication key from authentication password and engine id
GeneratePrivacyKey ( ) : byte[]	Generate privacy key from authentication password and engine id
GetUSM ( byte berBuffer, int length ) : UserSecurityModel	"Look-ahead" decode of SNMP packet header including USM information Decode first component of the SNMP version 3 packet allowing the caller to retrieve USM SecureName needed to retrieve client security parameters that will allow authentication and privacy decryption to take place. This method is used to support Agent like behavior or to handle unsolicited packets like TRAP and INFORMs. In all of these cases, sender of packets will forward a packet without a request being sent by you. In turn, you will need to parse enough of the packet to retrieve SecureName which you can use to retrieve security parameters associated with that user and attempt to authorize and privacy decrypt the received packet. Only use this method when your application is acting as an Agent or if you need to process TRAP and INFORM packets.
NoAuthNoPriv ( ) : void	Set class security to no authentication and no privacy. User name is set to "initial" (suitable for SNMP version 3 discovery process). Change username before using if discovery is not being performed.
NoAuthNoPriv ( byte userName ) : void	Set class security to no authentication and no privacy with the specific user name.
SetEngineId ( byte engineId ) : void	Set authoritative engine id
SetEngineTime ( int engineBoots, int engineTime ) : void	Set engine time and boots values
SnmpV3Packet ( ) : System	Standard constructor.
SnmpV3Packet ( ScopedPdu pdu ) : System	Constructor. Sets internal ScopedPdu class to the argument supplied instance of the class. This is a good cheat that will allow you direct access to the internal ScopedPdu class since it is not cloned but assigned to the internal variable.
SnmpV3Packet ( SecureAgentParameters param ) : System	Constructor. Create new SNMPv3 packet class and initialize security parameters
SnmpV3Packet ( SecureAgentParameters param, ScopedPdu pdu ) : System	Constructor Create new SNMPv3 packet class and initialize security parameters and ScopedPdu.
authNoPriv ( byte userName, byte authenticationPassword, AuthenticationDigests authenticationProtocol ) : void	Set class security to enabled authentication and no privacy. To perform authentication, authentication password needs to be supplied and authentication protocol to be used to perform authentication. This method does not initialize the packet user name. Use SNMPV3Packet.SecurityName method to set the security name (also called user name) for this request.
authPriv ( byte userName, byte authenticationPassword, AuthenticationDigests authenticationProtocol, byte privacyPassword, PrivacyProtocols privacyProtocol ) : void	Set packet security to authentication enabled and privacy protection enabled (SNMP v3 mode authPriv)
decode ( byte berBuffer, int length ) : int	Decode SNMP version 3 packet. This method will perform authentication check and decode privacy protected ScopedPdu. This method will not check for the timeliness of the packet, correct engine boot value or engine id because it does not have a reference to the engine time prior to this call.
decode ( byte berBuffer, int length, byte authKey, byte privKey ) : int	Decode SNMP version 3 packet. This method will perform authentication check and decode privacy protected ScopedPdu. This method will not check for the timeliness of the packet, correct engine boot value or engine id because it does not have a reference to the engine time prior to this call.
encode ( ) : byte[]	Encode SNMP version 3 packet Before encoding the packet into a byte array you need to ensure all required information is set. Examples of required information is request type, Vbs (Oid + values pairs), USM settings including SecretName, authentication method and secret (if needed), privacy method and secret (if needed), etc.
encode ( byte authKey, byte privKey ) : byte[]	Encode SNMP version 3 packet Before encoding the packet into a byte array you need to ensure all required information is set. Examples of required information is request type, Vbs (Oid + values pairs), USM settings including SecretName, authentication method and secret (if needed), privacy method and secret (if needed), etc.

Method Details

BuildInformResponse() public method

Build SNMP RESPONSE packet for the received INFORM packet.

public BuildInformResponse ( ) : SnmpV3Packet
return	SnmpV3Packet

BuildInformResponse() public static method

Build SNMP RESPONSE packet for the INFORM packet class.

Parameter is not an INFORM SNMP version 3 packet class Parameter is not a SNMP version 3 packet

public static BuildInformResponse ( SnmpV3Packet informPacket ) : SnmpV3Packet
informPacket	SnmpV3Packet	SNMP INFORM packet
return	SnmpV3Packet

DiscoveryRequest() public static method

Build an SNMP version 3 packet suitable for use in discovery process.

public static DiscoveryRequest ( ) : SnmpV3Packet
return	SnmpV3Packet

DiscoveryResponse() public static method

Build SNMP discovery response packet.

Manager application has to be able to respond to discovery requests to be able to handle SNMPv3 INFORM notifications. In an INFORM packet, engineId value is set to the manager stations id (unlike all other requests where agent is the authoritative SNMP engine). For the agent to discover appropriate manager engine id, boots and time values (required for authentication and privacy packet handling), manager has to be able to respond to the discovery request.

public static DiscoveryResponse ( Int32 messageId, Int32 requestId, OctetString engineId, Int32 engineBoots, Int32 engineTime, Int32 unknownEngineIdCount ) : SnmpV3Packet
messageId	System.Int32	Message id from the received discovery packet
requestId	System.Int32	Request id from the received discovery packets Pdu
engineId	OctetString	Local engine id
engineBoots	System.Int32	Number of times local SNMP engine has been restarted
engineTime	System.Int32	Time since the engine was started in seconds
unknownEngineIdCount	System.Int32	Number of discovery packets received by the local SNMP engine
return	SnmpV3Packet

GenerateAuthenticationKey() public method

Generate authentication key from authentication password and engine id

public GenerateAuthenticationKey ( ) : byte[]
return	byte[]

GeneratePrivacyKey() public method

Generate privacy key from authentication password and engine id

public GeneratePrivacyKey ( ) : byte[]
return	byte[]

GetUSM() public method

"Look-ahead" decode of SNMP packet header including USM information

Decode first component of the SNMP version 3 packet allowing the caller to retrieve USM SecureName needed to retrieve client security parameters that will allow authentication and privacy decryption to take place. This method is used to support Agent like behavior or to handle unsolicited packets like TRAP and INFORMs. In all of these cases, sender of packets will forward a packet without a request being sent by you. In turn, you will need to parse enough of the packet to retrieve SecureName which you can use to retrieve security parameters associated with that user and attempt to authorize and privacy decrypt the received packet. Only use this method when your application is acting as an Agent or if you need to process TRAP and INFORM packets.

Thrown when attempting to parse an SNMP packet that is not version 3 Thrown when header specifies packet length that is longer then the amount of data received. Thrown when invalid sequence is enountered while decoding global message data sequence Thrown with SnmpException.UnsupportedNoAuthPriv when packet is using privacy without authentication (not allowed) Thrown with SnmpException.UnsupportedSecurityModel when packet is sent with security model other then USM (only USM is defined in SNMPv3 standard)

public GetUSM ( byte berBuffer, int length ) : UserSecurityModel
berBuffer	byte	Raw SNMP version 3 packet
length	int	SNMP version 3 packet length
return	UserSecurityModel

NoAuthNoPriv() public method

Set class security to no authentication and no privacy. User name is set to "initial" (suitable for SNMP version 3 discovery process). Change username before using if discovery is not being performed.

public NoAuthNoPriv ( ) : void
return	void

NoAuthNoPriv() public method

Set class security to no authentication and no privacy with the specific user name.

public NoAuthNoPriv ( byte userName ) : void
userName	byte	User name
return	void

SetEngineId() public method

Set authoritative engine id

public SetEngineId ( byte engineId ) : void
engineId	byte	Authoritative engine id
return	void

SetEngineTime() public method

Set engine time and boots values

public SetEngineTime ( int engineBoots, int engineTime ) : void
engineBoots	int	Authoritative engine boots value retrived from the agent during discovery procedure.
engineTime	int	Engine time value.
return	void

SnmpV3Packet() public method

Standard constructor.

public SnmpV3Packet ( ) : System
return	System

SnmpV3Packet() public method

Constructor.

Sets internal ScopedPdu class to the argument supplied instance of the class. This is a good cheat that will allow you direct access to the internal ScopedPdu class since it is not cloned but assigned to the internal variable.

public SnmpV3Packet ( ScopedPdu pdu ) : System
pdu	ScopedPdu	class assigned to the class
return	System

SnmpV3Packet() public method

Constructor.

Create new SNMPv3 packet class and initialize security parameters

public SnmpV3Packet ( SecureAgentParameters param ) : System
param	SecureAgentParameters	Initialization SNMPv3 security parameters
return	System

SnmpV3Packet() public method

Constructor

Create new SNMPv3 packet class and initialize security parameters and ScopedPdu.

public SnmpV3Packet ( SecureAgentParameters param, ScopedPdu pdu ) : System
param	SecureAgentParameters	SNMPv3 security parameters
pdu	ScopedPdu	ScopedPdu assigned to the class
return	System

authNoPriv() public method

Set class security to enabled authentication and no privacy. To perform authentication, authentication password needs to be supplied and authentication protocol to be used to perform authentication. This method does not initialize the packet user name. Use SNMPV3Packet.SecurityName method to set the security name (also called user name) for this request.

public authNoPriv ( byte userName, byte authenticationPassword, AuthenticationDigests authenticationProtocol ) : void
userName	byte	User name
authenticationPassword	byte	Authentication password to use in authenticating the message. This /// value has to match the password configured on the agent.
authenticationProtocol	AuthenticationDigests	Authentication protocol to use. Available authentication protocols are: /// for HMAC-MD5 authentication, and /// for HMAC-SHA1 message authentication.
return	void

authPriv() public method

Set packet security to authentication enabled and privacy protection enabled (SNMP v3 mode authPriv)

public authPriv ( byte userName, byte authenticationPassword, AuthenticationDigests authenticationProtocol, byte privacyPassword, PrivacyProtocols privacyProtocol ) : void
userName	byte	User name
authenticationPassword	byte	Authentication password
authenticationProtocol	AuthenticationDigests	Authentication protocol. See definitions in enumeration.
privacyPassword	byte	Privacy protection password.
privacyProtocol	PrivacyProtocols	Privacy protocol. See definitions in enumeration.
return	void

decode() public method

Decode SNMP version 3 packet. This method will perform authentication check and decode privacy protected ScopedPdu. This method will not check for the timeliness of the packet, correct engine boot value or engine id because it does not have a reference to the engine time prior to this call.

public decode ( byte berBuffer, int length ) : int
berBuffer	byte	BER encoded SNMP version 3 packet buffer
length	int	Buffer length
return	int

decode() public method

public decode ( byte berBuffer, int length, byte authKey, byte privKey ) : int
berBuffer	byte	BER encoded SNMP version 3 packet buffer
length	int	Buffer length
authKey	byte	Authentication key (not password)
privKey	byte	Privacy key (not password)
return	int

encode() public method

Encode SNMP version 3 packet

Before encoding the packet into a byte array you need to ensure all required information is set. Examples of required information is request type, Vbs (Oid + values pairs), USM settings including SecretName, authentication method and secret (if needed), privacy method and secret (if needed), etc.

public encode ( ) : byte[]
return	byte[]

encode() public method

Encode SNMP version 3 packet

public encode ( byte authKey, byte privKey ) : byte[]
authKey	byte	Authentication key (not password)
privKey	byte	Privacy key (not password)
return	byte[]

Property Details

_securityModel protected_oe property

Security model code. Only supported security model is UserSecurityModel (integer value 3)

protected Integer32 _securityModel
return	Integer32