The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Convert-BER-XS-0.1
River stage zero No dependents
++
/ Convert::BER::XS

NAME

Convert::BER::XS - very low level BER en-/decoding

SYNOPSIS

 use Convert::BER::XS ':all';

 my $ber = ber_decode $buf
    or die "unable to decode SNMP v1/v2c Message";

 # the above results in a data structure consisting of (class, tag,
 # constructed, data) tuples. here is such a message, SNMPv1 trap
 # with a cisoc mac change notification

 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
   [
      [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
      [ ASN_UNIVERSAL, 4, 0, "public" ], # community
      [ ASN_CONTEXT, 4, 1, # CHOICE, constructed
         [
            [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
            [ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1
            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
            [ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
            [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
               [
                  [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
                     [
                        [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], # the oid
                        [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
                        ]
                     ]
                  ],
                  ...

 # let's decode it a bit with some helper functions

 my $msg = ber_is_seq $ber
    or die "SNMP message does not start with a sequence";

 ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER32, 0
    or die "SNMP message does not start with snmp version\n";

 # message is SNMP v1 or v2c?
 if ($msg->[0][BER_DATA] == 0 || $msg->[0][BER_DATA] == 1) {

    # message is v1 trap?
    if (ber_is $msg->[2], ASN_CONTEXT, 4, 1) {
       my $trap = $msg->[2][BER_DATA];

       # check whether trap is a cisco mac notification mac changed message
       if (
          (ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects
          and (ber_is_i32 $trap->[2], 6)
          and (ber_is_i32 $trap->[3], 1) # mac changed msg
       ) {
          ... and so on

 # finally, let's encode it again and hope it results in the same bit pattern

 my $buf = ber_encode $ber;

DESCRIPTION

This module implements a very low level BER/DER en-/decoder.

If is tuned for low memory and high speed, while still maintaining some level of user-friendlyness.

Currently, not much is documented, as this is an initial release to reserve CPAN namespace, stay tuned for a few days.

ASN.1/BER/DER/... BASICS

ASN.1 is a strange language that can be sed to describe protocols and data structures. It supports various mappings to JSON, XML, but most importantly, to a various binary encodings such as BER, that is the topic of this module, and is used in SNMP or LDAP for example.

While ASN.1 defines a schema that is useful to interpret encoded data, the BER encoding is actually somehat self-describing: you might not know whether something is a string or a number or a sequence or something else, but you can nevertheless decode the overall structure, even if you end up with just a binary blob for the actual value.

This works because BER values are tagged with a type and a namespace, and also have a flag that says whther a value consists of subvalues (is "constructed") or not (is "primitive").

Tags are simple integers, and ASN.1 defines a somewhat weird assortment of those - for example, you have 32 bit signed integers and 16(!) different string types, but there is no unsigned32 type for example. Different applications work around this in different ways, for example, SNMP defines application-specific Gauge32, Counter32 and Unsigned32, which are mapped to two different tags: you can distinguish between Counter32 and the others, but not between Gause32 and Unsigned32, without the ASN.1 schema.

Ugh.

DECODED BER REPRESENTATION

This module represents every BER value as a 4-element tuple (actually an array-reference):

   [CLASS, TAG, CONSTRUCTED, DATA]

CLASS is something like a namespace for TAGs - there is the ASN_UNIVERSAL namespace which defines tags common to all ASN.1 implementations, the ASN_APPLICATION namespace which defines tags for specific applications (for example, the SNMP Unsigned32 type is in this namespace), a special-purpose context namespace (ASN_CONTEXT, used e.g. for CHOICE) and a private namespace (ASN_PRIVATE).

The meaning of the TAG depends on the namespace, and defines a (partial) interpretation of the data value. For example, right now, SNMP application namespace knowledge ix hardcoded into this module, so it knows that SNMP Unsigned32 values need to be decoded into actual perl integers.

The most common tags in the ASN_UNIVERSAL namespace are ASN_INTEGER32, ASN_BIT_STRING, ASN_NULL, ASN_OCTET_STRING, ASN_OBJECT_IDENTIFIER, ASN_SEQUENCE, ASN_SET and ASN_IA5_STRING.

The most common tags in SNMP's ASN_APPLICATION namespace are SNMP_IPADDRESS, SNMP_COUNTER32, SNMP_UNSIGNED32, SNMP_TIMETICKS, SNMP_OPAQUE and SNMP_COUNTER64.

The CONSTRUCTED flag is really just a boolean - if it is false, the the value is "primitive" and contains no subvalues, kind of like a non-reference perl scalar. IF it is true, then the value is "constructed" which just means it contains a list of subvalues which this module will en-/decode as BER tuples themselves.

The DATA value is either a reference to an array of further tuples (if the value is CONSTRUCTED), some decoded representation of the value, if this module knows how to decode it (e.g. for the integer types above) or a binary string with the raw octets if this module doesn't know how to interpret the namespace/tag.

Thus, you can always decode a BER data structure and at worst you get a string in place of some nice decoded value.

See the SYNOPSIS for an example of such an encoded tuple representation.

RELATIONSHIP TO Convert::BER and Convert::ASN1

This module is not the XS version of Convert::BER, but a different take at doing the same thing. I imagine this module would be a good base for speeding up either of these, or write a similar module, or write your own LDAP or SNMP module for example.

BUGS / SHORTCOMINGs

This module does have a number of SNMPisms hardcoded, such as the SNMP tags for Unsigned32 and so on. More configurability is needed, and, if ever implemented, will come in a form similar to how JSON::XS and CBOR::XS respresent things, namely with an object-oriented interface.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/Convert-BER-XS