ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-BER-XS/XS.pm
(Generate patch)

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.14 by root, Sat Apr 20 01:31:07 2019 UTC vs.
Revision 1.15 by root, Sat Apr 20 02:07:29 2019 UTC

… …
73This module implements a I<very> low level BER/DER en-/decoder. 73This module implements a I<very> low level BER/DER en-/decoder.
74 74
75If is tuned for low memory and high speed, while still maintaining some 75If is tuned for low memory and high speed, while still maintaining some
76level of user-friendlyness. 76level of user-friendlyness.
77 77
78Currently, not much is documented, as this is an initial release to
79reserve CPAN namespace, stay tuned for a few days.
80
81=head2 ASN.1/BER/DER/... BASICS 78=head2 ASN.1/BER/DER/... BASICS
82 79
83ASN.1 is a strange language that can be sed to describe protocols and 80ASN.1 is a strange language that can be used to describe protocols and
84data structures. It supports various mappings to JSON, XML, but most 81data structures. It supports various mappings to JSON, XML, but most
85importantly, to a various binary encodings such as BER, that is the topic 82importantly, to a various binary encodings such as BER, that is the topic
86of this module, and is used in SNMP or LDAP for example. 83of this module, and is used in SNMP or LDAP for example.
87 84
88While ASN.1 defines a schema that is useful to interpret encoded data, 85While ASN.1 defines a schema that is useful to interpret encoded data,
… …
90whether something is a string or a number or a sequence or something else, 87whether something is a string or a number or a sequence or something else,
91but you can nevertheless decode the overall structure, even if you end up 88but you can nevertheless decode the overall structure, even if you end up
92with just a binary blob for the actual value. 89with just a binary blob for the actual value.
93 90
94This works because BER values are tagged with a type and a namespace, 91This works because BER values are tagged with a type and a namespace,
95and also have a flag that says whther a value consists of subvalues (is 92and also have a flag that says whether a value consists of subvalues (is
96"constructed") or not (is "primitive"). 93"constructed") or not (is "primitive").
97 94
98Tags are simple integers, and ASN.1 defines a somewhat weird assortment of 95Tags are simple integers, and ASN.1 defines a somewhat weird assortment of
99those - for example, you have 32 bit signed integers and 16(!) different 96those - for example, you have 32 bit signed integers and 16(!) different
100string types, but there is no unsigned32 type for example. Different 97string types, but there is no unsigned32 type for example. Different
… …
347 344
348The default profile supports the standard ASN.1 types, but no 345The default profile supports the standard ASN.1 types, but no
349application-specific ones. This means that class/tag combinations not in 346application-specific ones. This means that class/tag combinations not in
350the base set of ASN.1 are decoded into their raw octet strings. 347the base set of ASN.1 are decoded into their raw octet strings.
351 348
352C<Convert::BER::XS> defines two profile variables you cna use out of the box: 349C<Convert::BER::XS> defines two profile variables you can use out of the box:
353 350
354=over 351=over
355 352
356=item C<$Convert::BER::XS::DEFAULT_PROFILE> 353=item C<$Convert::BER::XS::DEFAULT_PROFILE>
357 354
358This is the default profile, i.e. the profile that is used when no 355This is the default profile, i.e. the profile that is used when no
359profile is specified for de-/encoding. 356profile is specified for de-/encoding.
360 357
361You cna modify it, but remember that this modifies the defaults for all 358You can modify it, but remember that this modifies the defaults for all
362callers that rely on the defauit profile. 359callers that rely on the default profile.
363 360
364=item C<$Convert::BER::XS::SNMP_PROFILE> 361=item C<$Convert::BER::XS::SNMP_PROFILE>
365 362
366A profile with mappings for SNMP-specific application tags added. This is 363A profile with mappings for SNMP-specific application tags added. This is
367useful when de-/encoding SNMP data. 364useful when de-/encoding SNMP data.
368 365
369Example: 366Example:
367
370 $ber = ber_decode $data, $Convert::BER::XS::SNMP_PROFILE; 368 $ber = ber_decode $data, $Convert::BER::XS::SNMP_PROFILE;
371 369
372=back 370=back
373 371
374=head2 The Convert::BER::XS::Profile class 372=head2 The Convert::BER::XS::Profile class
… …
387 385
388Note that currently, the mapping is stored in a flat array, so large 386Note that currently, the mapping is stored in a flat array, so large
389values of C<$tag> will consume large amounts of memory. 387values of C<$tag> will consume large amounts of memory.
390 388
391Example: 389Example:
390
392 $profile = new Convert::BER::XS::Profile; 391 $profile = new Convert::BER::XS::Profile;
393 $profile->set (ASN_APPLICATION, SNMP_COUNTER32, BER_TYPE_INT); 392 $profile->set (ASN_APPLICATION, SNMP_COUNTER32, BER_TYPE_INT);
394 $ber = ber_decode $data, $profile; 393 $ber = ber_decode $data, $profile;
395 394
396=item $type = $profile->get ($class, $tag) 395=item $type = $profile->get ($class, $tag)
… …
438Encodes and decodes an OBJECT IDENTIFIER into dotted form without leading 437Encodes and decodes an OBJECT IDENTIFIER into dotted form without leading
439dot, e.g. C<1.3.6.1.213>. 438dot, e.g. C<1.3.6.1.213>.
440 439
441=item C<BER_TYPE_RELOID> 440=item C<BER_TYPE_RELOID>
442 441
443Same as C<BER_TYPE_OID> but uses relative OID encoding: ASN.1 has this 442Same as C<BER_TYPE_OID> but uses relative object identifier
444hack of encoding the first two OID components into a single integer in a 443encoding: ASN.1 has this hack of encoding the first two OID components
445weird attempt to save an insignificant amount of space in an otherwise 444into a single integer in a weird attempt to save an insignificant amount
446wasteful encoding, and relative OIDs are basically OIDs without this 445of space in an otherwise wasteful encoding, and relative OIDs are
447hack. The practical difference is that the second component of an OID 446basically OIDs without this hack. The practical difference is that the
448can only have the values 1..40, while relative OIDs do not have this 447second component of an OID can only have the values 1..40, while relative
449restriction. 448OIDs do not have this restriction.
450 449
451=item C<BER_TYPE_NULL> 450=item C<BER_TYPE_NULL>
452 451
453Decodes an C<ASN_NULL> value into C<undef>, and always encodes a 452Decodes an C<ASN_NULL> value into C<undef>, and always encodes a
454C<ASN_NULL> type, regardless of the perl value. 453C<ASN_NULL> type, regardless of the perl value.
… …
462 461
463Decodes/encodes a BER real value. NOT IMPLEMENTED. 462Decodes/encodes a BER real value. NOT IMPLEMENTED.
464 463
465=item C<BER_TYPE_IPADDRESS> 464=item C<BER_TYPE_IPADDRESS>
466 465
467Decodes/encodes a four byte string into an IOv4 dotted-quad address string 466Decodes/encodes a four byte string into an IPv4 dotted-quad address string
468in perl. Given ther obsolete nature of this type, this is a low-effort 467in Perl. Given the obsolete nature of this type, this is a low-effort
469implementation that simply uses C<sprintf> and C<sscanf>-style conversion, 468implementation that simply uses C<sprintf> and C<sscanf>-style conversion,
470so it won't handle all string forms supported by C<inet_aton>. 469so it won't handle all string forms supported by C<inet_aton> for example.
471 470
472=item C<BER_TYPE_CROAK> 471=item C<BER_TYPE_CROAK>
473 472
474Always croaks when encountered during encoding or decoding - the 473Always croaks when encountered during encoding or decoding - the
475default behaviour when encountering an unknown type is to treat it as 474default behaviour when encountering an unknown type is to treat it as

Diff Legend

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