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
Datei anzeigen 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

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