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

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.26 by root, Sat Apr 20 15:23:55 2019 UTC vs.
Revision 1.29 by root, Sat Apr 20 15:39:13 2019 UTC

  my $ber = ber_decode $buf, $Convert::BER::XS::SNMP_PROFILE
     or die "unable to decode SNMP message";
  # The above results in a data structure consisting of
- # (class, tag, # constructed, data)
+ # (class, tag, flags, data)
  # tuples. Below is such a message, SNMPv1 trap
  # with a Cisco mac change notification.
  # Did you know that Cisco is in the news almost
  # every week because of some backdoor password
  # or other extremely stupid security bug?
 =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
 =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
 =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_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_INTEGER, 0, 123];
    @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
 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.
 =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
 Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
 a ease-of-use exception, they usually also accept C<undef> instead of a
 tuple reference, in which case they silently fail to match.
 =over
-=item $bool = ber_is $tuple, $class, $tag, $constructed, $data
+=item $bool = ber_is $tuple, $class, $tag, $flags, $data
 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>)).
    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_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
 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.26 by root, Sat Apr 20 15:23:55 2019 UTC vs. Revision 1.29 by root, Sat Apr 20 15:39:13 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.26 by root, Sat Apr 20 15:23:55 2019 UTC vs.
Revision 1.29 by root, Sat Apr 20 15:39:13 2019 UTC