[ViewVC] Diff of: cvs/Convert-BER-XS/XS.pm

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.22 by root, Sat Apr 20 14:50:08 2019 UTC vs.
Revision 1.27 by root, Sat Apr 20 15:27:28 2019 UTC

  # every week because of some backdoor password
  # or other extremely stupid security bug?
  [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
    [
-      [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
+      [ ASN_UNIVERSAL, ASN_INTEGER, 0, 0 ], # snmp version 1
       [ ASN_UNIVERSAL, 4, 0, "public" ], # community
       [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
          [
             [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
             [ ASN_APPLICATION, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress
-            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
+            [ ASN_UNIVERSAL, ASN_INTEGER, 0, 6 ], # generic trap
-            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
+            [ ASN_UNIVERSAL, ASN_INTEGER, 0, 1 ], # specific trap
             [ ASN_APPLICATION, SNMP_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
             [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
                [
                   [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
                      [
  # 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
+ ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER, 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) {
        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_int $trap->[2], 6)
-          and (ber_is_i32 $trap->[3], 1) # mac changed msg
+          and (ber_is_int $trap->[3], 1) # mac changed msg
        ) {
           ... and so on
  # finally, let's encode it again and hope it results in the same bit pattern
 level of user-friendlyness.
 =head2 EXPORT TAGS AND CONSTANTS
 By default this module doesn't export any symbols, but if you don't want
-to break your keyboard, editor or eyesigh with extreemly long names, I
+to break your keyboard, editor or eyesight with extremely long names, I
 recommend importing the C<:all> tag. Still, you can selectively import
 things.
 =over
 =item C<:all>
-All of the below. Really. Rcommended for at least first steps, or if you
+All of the below. Really. Recommended for at least first steps, or if you
 don't care about a few kilobytes of wasted memory (and namespace).
 =item C<:const>
-All of the stricly ASN.1-related constants defined by this module, the
+All of the strictly ASN.1-related constants defined by this module, the
 same as C<:const_asn :const_index>. Notably, this does not contain
 C<:const_ber_type> and C<:const_snmp>.
 A good set to get everything you need to decode and match BER data would be
 C<:decode :const>.
         BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
 =item C<:const_asn>
-ASN class values (these are C<0>, C<1>, C<2> and C<3>, reespectively -
+ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
-exactly thw two topmost bits from the identifdier octet shifted 6 bits to
+exactly thw two topmost bits from the identifier octet shifted 6 bits to
 the right):
       ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
 ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
 numerical value corresponds exactly to the numbers used in BER/X.690.
-      ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
+      ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
       ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
       ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
       ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
       ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
       ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
 =item C<:decode>
 C<ber_decode> and the match helper functions:
-      ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid
+      ber_decode ber_is ber_is_seq ber_is_int ber_is_oid
 =item C<:encode>
 C<ber_encode> and the construction helper functions:
-      ber_encode ber_i32
+      ber_encode ber_int
 =back
 =head2 ASN.1/BER/DER/... BASICS
 ASN.1 is a strange language that can be used 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.
+of this module, and is used in SNMP, LDAP or X.509 for example.
 While ASN.1 defines a schema that is useful to interpret encoded data,
 the BER encoding is actually somewhat 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
 This works because BER values are tagged with a type and a namespace,
 and also have a flag that says whether a value consists of subvalues (is
 "constructed") or not (is "primitive").
-Tags are simple integers, and ASN.1 defines a somewhat weird assortment of
+Tags are simple integers, and ASN.1 defines a somewhat weird assortment
-those - for example, you have 32 bit signed integers and 16(!) different
+of those - for example, you have one integers and 16(!) different
-string types, but there is no unsigned32 type for example. 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.
 This module represents every BER value as a 4-element tuple (actually an
 array-reference):
    [CLASS, TAG, CONSTRUCTED, DATA]
+For example:
+   [ASN_UNIVERSAL, ASN_INTEGER, 0, 177]       # the integer 177
+   [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"
+   [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"]     # some OID
+   [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence
 To avoid non-descriptive hardcoded array index numbers, this module
 defines symbolic constants to access these members: C<BER_CLASS>,
 C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.
 Also, the first three members are integers with a little caveat: for
    # the following is NOT legal:
    $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)
    # but all of the following are fine:
    $ber->[BER_DATA] = "string";
-   $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123];
+   $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];
    @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
 I<CLASS> is something like a namespace for I<TAG>s - there is the
 C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
 implementations, the C<ASN_APPLICATION> namespace which defines tags for
 specific applications (for example, the SNMP C<Unsigned32> type is in this
 namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
 for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>).
 The meaning of the I<TAG> depends on the namespace, and defines a
-(partial) interpretation of the data value. For example, right now, SNMP
+(partial) interpretation of the data value. For example, SNMP defines
-application namespace knowledge ix hardcoded into this module, so it
+extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
-knows that SNMP C<Unsigned32> values need to be decoded into actual perl
+of these, you need to tell this module how to handle those via profiles.
-integers.
 The most common tags in the C<ASN_UNIVERSAL> namespace are
-C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
+C<ASN_INTEGER>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
 C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
 C<ASN_IA5_STRING>.
-The most common tags in SNMP's C<ASN_APPLICATION> namespace
+The most common tags in SNMP's C<ASN_APPLICATION> namespace are
-are C<SNMP_IPADDRESS>, C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>,
+C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
-C<SNMP_TIMETICKS>, C<SNMP_OPAQUE> and C<SNMP_COUNTER64>.
+C<SNMP_COUNTER64>.
-The I<CONSTRUCTED> flag is really just a boolean - if it is false, the
+The I<CONSTRUCTED> flag is really just a boolean - if it is false,
 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"
+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 I<DATA> value is either a reference to an array of further tuples (if
 the value is I<CONSTRUCTED>), some decoded representation of the value,
 =head2 DECODING AND ENCODING
 =over
-=item $tuple = ber_decoded $bindata
+=item $tuple = ber_decoded $bindata[, $profile]
 Decodes binary BER data in C<$bindata> and returns the resulting BER
 tuple. Croaks on any decoding error, so the returned C<$tuple> is always
 valid.
+How tags are interpreted is defined by the second argument, which must
+be a C<Convert::BER::XS::Profile> object. If it is missing, the default
+profile will be used (C<$Convert::BER::XS::DEFAULT_PROFILE>).
+In addition to rolling your own, this module provides a
+C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP
+types.
+Example: decode a BER blob using the default profile - SNMP values will be
+decided as raw strings.
+   $tuple = ber_decode $data;
+Example: as above, but use the provided SNMP profile.
+   $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
-=item $bindata = ber_encode $tuple
+=item $bindata = ber_encode $tuple[, $profile]
-Encodes the BER tuple into a BER/DER data structure.
+Encodes the BER tuple into a BER/DER data structure. AS with
+Cyber_decode>, an optional profile can be given.
 =back
 =head2 HELPER FUNCTIONS
 Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
 annoying. To reduce this a bit, this module defines a number of helper
-functions, both to match BER tuples and to conmstruct BER tuples:
+functions, both to match BER tuples and to construct BER tuples:
 =head3 MATCH HELPERS
-Thse functions accept a BER tuple as first argument and either paertially
+These functions accept a BER tuple as first argument and either partially
 or fully match it. They often come in two forms, one which exactly matches
 a value, and one which only matches the type and returns the value.
 They do check whether valid tuples are passed in and croak otherwise. As
 a ease-of-use exception, they usually also accept C<undef> instead of a
-tuple reference. in which case they silently fail to match.
+tuple reference, in which case they silently fail to match.
 =over
 =item $bool = ber_is $tuple, $class, $tag, $constructed, $data
-This takes a BER C<$tuple> and matches its elements agains the privded
+This takes a BER C<$tuple> and matches its elements against the provided
 values, all of which are optional - values that are either missing or
 C<undef> will be ignored, the others will be matched exactly (e.g. as if
 you used C<==> or C<eq> (for C<$data>)).
 Some examples:
       orf die "tuple is not an ASN SEQUENCE";
    ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
       or die "tuple is not an ASN NULL value";
-   ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50
+   ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER, 0, 50
       or die "BER integer must be 50";
 =item $seq = ber_is_seq $tuple
 Returns the sequence members (the array of subvalues) if the C<$tuple> is
    my $snmp = ber_is_seq $ber
       or die "SNMP packet invalid: does not start with SEQUENCE";
    # now we know $snmp is a sequence, so decode the SNMP version
-   my $version = ber_is_i32 $snmp->[0]
+   my $version = ber_is_int $snmp->[0]
       or die "SNMP packet invalid: does not start with version number";
-=item $bool = ber_is_i32 $tuple, $i32
+=item $bool = ber_is_int $tuple, $int
-Returns a true value if the C<$tuple> represents an ASN INTEGER32 with
+Returns a true value if the C<$tuple> represents an ASN INTEGER with
-the value C<$i32>.
+the value C<$int>.
-=item $i32 = ber_is_i32 $tuple
+=item $int = ber_is_int $tuple
-Returns true (and extracts the integer value) if the C<$tuple> is an ASN
+Returns true (and extracts the integer value) if the C<$tuple> is an
-INTEGER32. For C<0>, this function returns a special value that is 0 but
+C<ASN_INTEGER>. For C<0>, this function returns a special value that is 0
-true.
+but true.
 =item $bool = ber_is_oid $tuple, $oid_string
 Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
 that exactly matches C<$oid_string>. Example:
 =head3 CONSTRUCTION HELPERS
 =over
-=item $tuple = ber_i32 $value
+=item $tuple = ber_int $value
-Constructs a new C<ASN_INTEGER32> tuple.
+Constructs a new C<ASN_INTEGER> tuple.
 =back
 =head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
 our %EXPORT_TAGS = (
    const_index => [qw(
       BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
    )],
    const_asn => [qw(
-      ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
+      ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
       ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
       ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
       ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
       ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
       ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
    const_snmp => [qw(
       SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
    )],
    decode => [qw(
       ber_decode
-      ber_is ber_is_seq ber_is_i32 ber_is_oid
+      ber_is ber_is_seq ber_is_int ber_is_oid
    )],
    encode => [qw(
       ber_encode
-      ber_i32
+      ber_int
    )],
 );
 our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
 $EXPORT_TAGS{all} = \@EXPORT_OK;
 $EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
-use Data::Dump; ddx \%EXPORT_TAGS;
 =head1 PROFILES
 While any BER data can be correctly encoded and decoded out of the box, it
 can be inconvenient to have to manually decode some values into a "better"
 This module can only en-/decode 64 bit signed and unsigned integers, and
 only when your perl supports those.
 This module does not generally care about ranges, i.e. it will happily
-de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative
+de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
 number into an C<SNMP_COUNTER64>.
 OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
 much larger than e.g. the one imposed by SNMP or other protocols,a nd is
 about 4kB.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.22 by root, Sat Apr 20 14:50:08 2019 UTC vs. Revision 1.27 by root, Sat Apr 20 15:27:28 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.22 by root, Sat Apr 20 14:50:08 2019 UTC vs.
Revision 1.27 by root, Sat Apr 20 15:27:28 2019 UTC