SNMP - lemontree55/packetgen GitHub Wiki
SNMP is quite different from others protocols: it uses ASN.1 data structures. So, to understand SNMP serialization/deserialization, you need to understand ASN.1.
ASN.1
ASN.1 is an interface description language for defining data structures that can be serialized and deserialized in a standard and cross-platform way. It is broadly used in telecommunications and computer networking, and also in cryptography (X.509 certificates are defined with ASN.1, for example).
ASN.1 is a notation independent of the way data are encoded. Encoding are specified in Encoding Rules.
The most used encoding rules are BER (Basic Encoding Rules) and DER (Distinguished Encoding Rules). Both are quite equivalent, but the latter is specified to guaranty uniqueness of encoding. But, in fact, there are just little differences between them.
ASN.1 provides basic objects, such as: integers, many kinds of strings, floats, booleans. It also provides some container objects (sequences and sets). They all are defined in Universal class. A protocol may defined others objects, which will be grouped in the Context class. For example, SNMP defines GetRequest-PDU object in this class. There is also Private and Application classes.
Each basic object has a tag, used by the encoding rules. For example, Boolean has tag value 1, Integer has tag value 2. In context class, tags begin at 0xA0. For example, in SNMP context, 0xA0 tag is a GetRequest-PDU.
Others objects may be constructed from those basic ones using Sequences and Sets. Sequences are like ruby arrays. Sets are arrays limited to a unique object type.
Finally, a ASN.1 object is a tree, whose leafs are basic types, and non-leaf nodes are Sets or Sequences.
ASN.1 in PacketGen
In PacketGen, ASN.1 objetcs are handled using rasn1 gem. This gem defines
basic ASN.1 objets and provides ways to decode and encode data in DER and BER
encodings.
rasn1 gem
rasn1 gem provides a RASN1::Model class to define complex ASN.1 objects. See
Rasn1 wiki for a simple example.
SNMP
In PacketGen, SNMP header inherits from PacketGen::Header::ASN1Base, which
inherits from RASN1::Model.
Header::ASN1Base provides Header minimal API.
Some ASN1. objets are also defined in PacketGen::Header::SNMP namespace:
PDUs, which is a CHOICE between all SNMP PDUs,GetRequest, which is the model of a SNMP Get request,GetNextRequest,GetResponse,SetRequest,Trapv1, which is Trap PDU for SNMPv1,Bulk,InformRequest,Trapv2, which is Trap PDU for SNMPv2,Report,VariableBindings, which is a SEQUENCE OF (an array of)VarBind. This class is used in PDU classes,VarBind, which is an association between a name (as an OBJECT ID) and a value (its type depends on its name).
SNMP base class
SNMP class
is a simple ASN.1 object defined like this:
class SNMP < ASN1Base
sequence :message,
content: [integer(:version, value: 'v2c',
enum: { 'v1' => 0, 'v2c' => 1, 'v2' => 2, 'v3' => 3 }),
octet_string(:community, value: 'public'),
model(:data, PDUs)]
end
which is equivalent to this ASN.1 definition:
Message ::= SEQUENCE {
version INTEGER { version-1(0), version-2c(1), version-2(2), version-3(3) },
community OCTET STRING,
data ANY -- Here is PDU
}
All objects may be accessed through #[] accessor:
snmp = PacketGen::Header::SNMP.new
snmp[:version] # => RASN1::Types::Enumerated
snmp[:version].to_i # => 1
snmp[:version].value # => "v2c"
snmp[:community] # => RASN1::Types::OctetString
snmp[:community].value # => "public"
snmp[:data] # => PacketGen::Header::SNMP::PDUs
For convenience, these upper fields are accessible through accessors, as for others headers:
snmp.version = 0
snmp.version # => "v1"
snmp.version = "v3"
snmp.community # => "public"
snmp.commutiyy = 'private'
snmp.data # => PacketGen::Header::SNMP::PDUs
SNMP::PDUs class
In RFC, PDUs is defined as:
PDUs ::= CHOICE {
get-request [0] IMPLICIT PDU,
get-next-request [1] IMPLICIT PDU,
get-response [2] IMPLICIT PDU,
set-request [3] IMPLICIT PDU,
snmpV1-trap [4] IMPLICIT PDU,
get-bulk-request [5] IMPLICIT PDU,
inform-request [6] IMPLICIT PDU,
snmpV2-trap [7] IMPLICIT PDU,
report [8] IMPLICIT PDU
}
SNMP::PDUs class is defined as a subclass of RASN1::Model, and as a CHOICE.
Setting header type (or PDU type) may be done this way:
smp.data.root # access to root ASN.1 object in PDU class
# => RASN1::Types::CHOICE
snmp.data.root.chosen = 0 # Choose first CHOICE from PDUs: SNMP::GetRequest
snmp.data.root.chosen_value # => PacketGen::Header::SNMP::GetRequest
As RASN1::Model may delegate some methods to its root object, we can simplify previous code:
smp.data.root # access to root ASN.1 object in PDU class
# => RASN1::Types::CHOICE
snmp.data.chosen = 0 # Choose first CHOICE from PDUs: SNMP::GetRequest
snmp.data.chosen_value # => PacketGen::Header::SNMP::GetRequest
# or even simpler
snmp.pdu # => PacketGen::Header::SNMP::GetRequest
SNMP::GetRequest class
GetRequest PDU is defined as:
GetRequest-PDU ::= [0] IMPLICIT PDU
PDU ::= SEQUENCE {
request-id INTEGER (-214783648..214783647),
error-status -- sometimes ignored
INTEGER {
noError(0),
tooBig(1),
noSuchName(2), -- for proxy compatibility
badValue(3), -- for proxy compatibility
readOnly(4), -- for proxy compatibility
genErr(5),
noAccess(6),
wrongType(7),
wrongLength(8),
wrongEncoding(9),
wrongValue(10),
noCreation(11),
inconsistentValue(12),
resourceUnavailable(13),
commitFailed(14),
undoFailed(15),
authorizationError(16),
notWritable(17),
inconsistentName(18)
},
error-index -- sometimes ignored
INTEGER (0..max-bindings),
variable-bindings -- values are sometimes ignored
VarBindList
}
So a GetRequest object has these accessors:
snmp = PacketGen::Header::SNMP.new
snmp.data.chosen = 0 # GetRequest PDU
# accessors
snmp.pdu[:id] # request-id (RASN1::Types::Integer)
snmp.pdu[:error] # error, with possible values from SNMP::ERRORS (RASN1::Types::Enumerated)
snmp.pdu[:error_index] # error-index (RASN1::Types::Integer)
snmp.pdu[:varbindlist] # variable-bindings (SNMP::VariableBindings)
You may add some VarBind:
# name is an OBJECT ID, and there is no value in a GetRequest (value set to NULL)
snmp.pdu[:varbindlist] << { name: '1.3.6.1.2.1.1.5.0' }
snmp.pdu[:varbindlist].value[0] # => PacketGen::Header::SNMP::VarBind
snmp.pdu[:varbindlist].value[0][:name] # => RASN1::Types::ObjectId
snmp.pdu[:varbindlist].value[0][:name].value # => '1.3.6.1.2.1.1.5.0'
SNMP::GetNextRequest class
GetNextRequest is a subclass of GetRequest, with only a different PDU identifier.
Creating a GetNextRequest may be done this way:
snmp = PacketGen::Header::SNMP.new
snmp.data.chosen = 1 # GetNextRequest PDU
snmp.pdu # => PacketGen::Header::SNMP::GetNextRequest
SNMP::GetResponse class
GetResponse is a subclass of GetRequest, with only a different PDU identifier.
Creating a GetResponse may be done this way:
snmp = PacketGen::Header::SNMP.new
snmp.data.chosen = 2 # GetResponse PDU
snmp.pdu # => PacketGen::Header::SNMP::GetResponse
SNMP::SetRequest class
GetResponse is a subclass of GetRequest, with only a different PDU identifier.
Creating a GetResponse may be done this way:
snmp = PacketGen::Header::SNMP.new
snmp.data.chosen = 3 # SetRequest PDU
snmp.pdu # => PacketGen::Header::SNMP::SetRequest
SNMP::Trapv1 class
Trapv1 PDU is defined as:
Trap-PDU ::= [4] IMPLICIT SEQUENCE {
enterprise OBJECT IDENTIFIER,
agent-addr NetworkAddress,
generic-trap -- generic trap type
INTEGER {
coldStart(0),
warmStart(1),
linkDown(2),
linkUp(3),
authenticationFailure(4),
egpNeighborLoss(5),
enterpriseSpecific(6)
},
specific-trap INTEGER,
time-stamp TimeTicks,
variable-bindings VarBindList
}
So a GetRequest object has these accessors:
snmp = PacketGen::Header::SNMP.new
snmp.data.chosen = 4 # Trapv1 PDU
# accessors
snmp.pdu[:enterprise] # => RASN1::Types::ObjectId
snmp.pdu[:agent_addr] # => RASN1::Types::OctetString
snmp.pdu[:generic_trap] # => RASN1::Types::Enumerated
snmp.pdu[:specific_trap] # => RASN1::Types::Integer
snmp.pdu[:timestamp] # => RASN1::Types::Integer
snmp.pdu[:varbindlist] # => PacketGen::Header::SNMP::VariableBindings
:generic_trap may take these values:
cold_startor0,warm_startor1,link_downor2,link_upor3,auth_failureor4,egp_neighbor_lossor5,specificor6.
SNMP::Bulk class
Create a Bulk PDU:
bulk = PacketGen::Header::SNMP.new
bulk.data.chosen = 5
Bulk accessors:
bulk.pdu[:id] # => RASN1::Types::Integer
bulk.pdu[:non_repeaters] # => RASN1::Types::Integer
bulk.pdu[:max_repetitions] # => RASN1::Types::Integer
bulk.pdu[:varbindlist] # => PacketGen::Header::SNMP::VariableBindings
SNMP::InformRequest class
Create a InformRequest PDU:
ir = PacketGen::Header::SNMP.new
ir.data.chosen = 6
InformRequest is a subclass of GetRequest, so it has the same accessors.
SNMP::Trapv2 class
Create a Trapv2 PDU:
ir = PacketGen::Header::SNMP.new
ir.data.chosen = 7
Trapv2 is a subclass of GetRequest, so it has the same accessors.
SNMP::Report class
Create a Report PDU:
ir = PacketGen::Header::SNMP.new
ir.data.chosen = 8
Report is a subclass of GetRequest, so it has the same accessors.