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

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.24 by root, Sat Apr 20 14:59:26 2019 UTC vs.
Revision 1.28 by root, Sat Apr 20 15:37:27 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
 =item C<:const_index>
 The BER tuple array index constants:
-        BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
+        BER_CLASS BER_TAG BER_FLAGS BER_DATA
 =item C<:const_asn>
 ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
 exactly thw two topmost bits from the identifier octet shifted 6 bits to
       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
 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.
 =head2 DECODED BER REPRESENTATION
 This module represents every BER value as a 4-element tuple (actually an
 array-reference):
-   [CLASS, TAG, CONSTRUCTED, DATA]
+   [CLASS, TAG, FLAGS, DATA]
 For example:
-   [ASN_UNIVERSAL, ASN_INTEGER32, 0, 177]       # the integer 177
+   [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>.
+C<BER_TAG>, C<BER_FLAGS> and C<BER_DATA>.
 Also, the first three members are integers with a little caveat: for
 performance reasons, these are readonly and shared, so you must not modify
 them (increment, assign to them etc.) in any way. You may modify the
 I<DATA> member, and you may re-assign the array itself, e.g.:
    $ber = ber_decode $binbuf;
    # the following is NOT legal:
-   $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)
+   $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/FLAGS 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
 (partial) interpretation of the data value. For example, SNMP defines
 extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
 of these, you need to tell this module how to handle those via profiles.
 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 are
 C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
 C<SNMP_COUNTER64>.
-The I<CONSTRUCTED> flag is really just a boolean - if it is false,
+The I<FLAGS> value is really just a boolean at this time (but might
-the value is "primitive" and contains no subvalues, kind of like a
+get extended) - if it is C<0>, the value is "primitive" and contains
-non-reference perl scalar. If it is true, then the value is "constructed"
+no subvalues, kind of like a non-reference perl scalar. If it is C<1>,
-which just means it contains a list of subvalues which this module will
+then the value is "constructed" which just means it contains a list of
-en-/decode as BER tuples themselves.
+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 I<DATA> value is either a reference to an array of further tuples
-the value is I<CONSTRUCTED>), some decoded representation of the value,
+(if the value is I<FLAGS>), some decoded representation of the value, if
-if this module knows how to decode it (e.g. for the integer types above)
+this module knows how to decode it (e.g. for the integer types above) or
-or a binary string with the raw octets if this module doesn't know how to
+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.
 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[, $profile]
 Encodes the BER tuple into a BER/DER data structure. AS with
 Cyber_decode>, an optional profile can be given.
+The encoded data should be both BER and DER ("shortest form") compliant
+unless the input says otherwise (e.g. it uses constructed strings).
 =back
 =head2 HELPER FUNCTIONS
       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>
    XSLoader::load __PACKAGE__, $VERSION;
 }
 our %EXPORT_TAGS = (
    const_index => [qw(
-      BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
+      BER_CLASS BER_TAG BER_FLAGS 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.
+Indefinite length encoding is not supported.
+Constructed strings are decoded just fine, but there should be a way to
+join them for convenience.
 REAL values are not supported and will currently croak.
 This module has undergone little to no testing so far.
 =head2 ITHREADS SUPPORT

Diff Legend

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

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.24 by root, Sat Apr 20 14:59:26 2019 UTC vs. Revision 1.28 by root, Sat Apr 20 15:37:27 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.24 by root, Sat Apr 20 14:59:26 2019 UTC vs.
Revision 1.28 by root, Sat Apr 20 15:37:27 2019 UTC