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.20 by root, Sat Apr 20 14:47:23 2019 UTC

4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Convert::BER::XS ':all'; 7 use Convert::BER::XS ':all';
8 8
9 my $ber = ber_decode $buf 9 my $ber = ber_decode $buf, $Convert::BER::XS::SNMP_PROFILE
10 or die "unable to decode SNMP message"; 10 or die "unable to decode SNMP message";
11 11
12 # The above results in a data structure consisting of 12 # The above results in a data structure consisting of
13 # (class, tag, # constructed, data) 13 # (class, tag, # constructed, data)
14 # tuples. Below is such a message, SNMPv1 trap 14 # tuples. Below is such a message, SNMPv1 trap
15 # with a Cisco mac change notification. 15 # with a Cisco mac change notification.
16 # Did you know that Cisco is in the news almost 16 # Did you know that Cisco is in the news almost
17 # every week because # of some backdoor password 17 # every week because of some backdoor password
18 # or other extremely stupid security bug? 18 # or other extremely stupid security bug?
19 19
20 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, 20 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
21 [ 21 [
22 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1 22 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
23 [ ASN_UNIVERSAL, 4, 0, "public" ], # community 23 [ ASN_UNIVERSAL, 4, 0, "public" ], # community
24 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU 24 [ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
25 [ 25 [
26 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid 26 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
27 [ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1 27 [ ASN_APPLICATION, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress
28 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap 28 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
29 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap 29 [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
30 [ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks 30 [ ASN_APPLICATION, SNMP_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist 31 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
32 [ 32 [
33 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair 33 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
34 [ 34 [
35 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], 35 [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],
62 ) { 62 ) {
63 ... and so on 63 ... and so on
64 64
65 # finally, let's encode it again and hope it results in the same bit pattern 65 # finally, let's encode it again and hope it results in the same bit pattern
66 66
67 my $buf = ber_encode $ber; 67 my $buf = ber_encode $ber, $Convert::BER::XS::SNMP_PROFILE;
68 68
69=head1 DESCRIPTION 69=head1 DESCRIPTION
70 70
71WARNING: Before release 1.0, the API is not considered stable in any way. 71WARNING: Before release 1.0, the API is not considered stable in any way.
72 72
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 75It 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 78=head2 EXPORT TAGS AND CONSTANTS
79reserve CPAN namespace, stay tuned for a few days. 79
80By default this module doesn't export any symbols, but if you don't want
81to break your keyboard, editor or eyesigh with extreemly long names, I
82recommend importing the C<:all> tag. Still, you can selectively import
83things:
84
85=over
86
87=item :all
88
89All of the below. Really. Rcommended for at least first steps, or if you
90don't care about a few kilobytes of wasted memory (and namespace).
91
92=item :const
93
94All of the stricly ASN.1-related constants defined by this module, the
95same as C<:const_asn :const_index>. Notably, this does not contain
96C<:const_ber_type> and C<:const_snmp>.
97
98A good set to get everything you need to decode and match BER data would be
99C<:decode :const>.
100
101=item C<:const_index>>
102
103The BER tuple array index constants:
104
105 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
106
107=item C<:const_asn>
108
109ASN class values (these are C<0>, C<1>, C<2> and C<3>, reespectively -
110exactly thw two topmost bits from the identifdier octet shifted 6 bits to
111the right):
112
113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
114
115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
116numerical value corresponds exactly to the numbers used in BER/X.690.
117
118 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
119 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
120 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
121 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
122 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
123 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
124
125=item C<:const_ber_type>
126
127The BER type constants, explained in the PROFILES section.
128
129 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
130 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
131 BER_TYPE_IPADDRESS BER_TYPE_CROAK
132
133=item C<:const_snmp>
134
135Constants only relevant to SNMP. These are the tag values used by SNMP in
136the C<ASN_APPLICATION> namespace and have the exact numerical value as in
137BER/RFC 2578.
138
139 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
140
141=item C<:decode>
142
143C<ber_decode> and the match helper functions:
144
145 ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid
146
147=item C<:encode>
148
149C<ber_encode> and the construction helper functions:
150
151 ber_encode ber_i32
152
153=back
80 154
81=head2 ASN.1/BER/DER/... BASICS 155=head2 ASN.1/BER/DER/... BASICS
82 156
83ASN.1 is a strange language that can be sed to describe protocols and 157ASN.1 is a strange language that can be used to describe protocols and
84data structures. It supports various mappings to JSON, XML, but most 158data structures. It supports various mappings to JSON, XML, but most
85importantly, to a various binary encodings such as BER, that is the topic 159importantly, to a various binary encodings such as BER, that is the topic
86of this module, and is used in SNMP or LDAP for example. 160of this module, and is used in SNMP or LDAP for example.
87 161
88While ASN.1 defines a schema that is useful to interpret encoded data, 162While 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, 164whether 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 165but you can nevertheless decode the overall structure, even if you end up
92with just a binary blob for the actual value. 166with just a binary blob for the actual value.
93 167
94This works because BER values are tagged with a type and a namespace, 168This 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 169and also have a flag that says whether a value consists of subvalues (is
96"constructed") or not (is "primitive"). 170"constructed") or not (is "primitive").
97 171
98Tags are simple integers, and ASN.1 defines a somewhat weird assortment of 172Tags are simple integers, and ASN.1 defines a somewhat weird assortment of
99those - for example, you have 32 bit signed integers and 16(!) different 173those - for example, you have 32 bit signed integers and 16(!) different
100string types, but there is no unsigned32 type for example. Different 174string types, but there is no unsigned32 type for example. Different
292use Exporter qw(import); 366use Exporter qw(import);
293 367
294our $VERSION; 368our $VERSION;
295 369
296BEGIN { 370BEGIN {
297 $VERSION = 0.7; 371 $VERSION = 0.8;
298 XSLoader::load __PACKAGE__, $VERSION; 372 XSLoader::load __PACKAGE__, $VERSION;
299} 373}
300 374
301our %EXPORT_TAGS = ( 375our %EXPORT_TAGS = (
302 const => [qw( 376 const_index => [qw(
303 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 377 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
304 378 )],
379 const_asn => [qw(
305 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 380 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
306 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 381 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
307 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 382 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
308 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 383 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
309 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 384 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
310 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 385 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
311 386
312 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE 387 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
313 388 )],
389 const_ber_type => [qw(
314 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT 390 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
315 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL 391 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
316 BER_TYPE_IPADDRESS BER_TYPE_CROAK 392 BER_TYPE_IPADDRESS BER_TYPE_CROAK
317 )], 393 )],
318 const_snmp => [qw( 394 const_snmp => [qw(
319 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 395 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
320 )], 396 )],
321 encode => [qw( 397 decode => [qw(
322 ber_decode 398 ber_decode
323 ber_is ber_is_seq ber_is_i32 ber_is_oid 399 ber_is ber_is_seq ber_is_i32 ber_is_oid
324 )], 400 )],
325 decode => [qw( 401 encode => [qw(
326 ber_encode 402 ber_encode
327 ber_i32 403 ber_i32
328 )], 404 )],
329); 405);
330 406
331our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 407our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
332 408
333$EXPORT_TAGS{all} = \@EXPORT_OK; 409$EXPORT_TAGS{all} = \@EXPORT_OK;
410$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
411use Data::Dump; ddx \%EXPORT_TAGS;
334 412
335=head1 PROFILES 413=head1 PROFILES
336 414
337While any BER data can be correctly encoded and decoded out of the box, it 415While any BER data can be correctly encoded and decoded out of the box, it
338can be inconvenient to have to manually decode some values into a "better" 416can be inconvenient to have to manually decode some values into a "better"
347 425
348The default profile supports the standard ASN.1 types, but no 426The default profile supports the standard ASN.1 types, but no
349application-specific ones. This means that class/tag combinations not in 427application-specific ones. This means that class/tag combinations not in
350the base set of ASN.1 are decoded into their raw octet strings. 428the base set of ASN.1 are decoded into their raw octet strings.
351 429
352C<Convert::BER::XS> defines two profile variables you cna use out of the box: 430C<Convert::BER::XS> defines two profile variables you can use out of the box:
353 431
354=over 432=over
355 433
356=item C<$Convert::BER::XS::DEFAULT_PROFILE> 434=item C<$Convert::BER::XS::DEFAULT_PROFILE>
357 435
358This is the default profile, i.e. the profile that is used when no 436This is the default profile, i.e. the profile that is used when no
359profile is specified for de-/encoding. 437profile is specified for de-/encoding.
360 438
361You cna modify it, but remember that this modifies the defaults for all 439You can modify it, but remember that this modifies the defaults for all
362callers that rely on the defauit profile. 440callers that rely on the default profile.
363 441
364=item C<$Convert::BER::XS::SNMP_PROFILE> 442=item C<$Convert::BER::XS::SNMP_PROFILE>
365 443
366A profile with mappings for SNMP-specific application tags added. This is 444A profile with mappings for SNMP-specific application tags added. This is
367useful when de-/encoding SNMP data. 445useful when de-/encoding SNMP data.
368 446
369Example: 447Example:
448
370 $ber = ber_decode $data, $Convert::BER::XS::SNMP_PROFILE; 449 $ber = ber_decode $data, $Convert::BER::XS::SNMP_PROFILE;
371 450
372=back 451=back
373 452
374=head2 The Convert::BER::XS::Profile class 453=head2 The Convert::BER::XS::Profile class
387 466
388Note that currently, the mapping is stored in a flat array, so large 467Note that currently, the mapping is stored in a flat array, so large
389values of C<$tag> will consume large amounts of memory. 468values of C<$tag> will consume large amounts of memory.
390 469
391Example: 470Example:
471
392 $profile = new Convert::BER::XS::Profile; 472 $profile = new Convert::BER::XS::Profile;
393 $profile->set (ASN_APPLICATION, SNMP_COUNTER32, BER_TYPE_INT); 473 $profile->set (ASN_APPLICATION, SNMP_COUNTER32, BER_TYPE_INT);
394 $ber = ber_decode $data, $profile; 474 $ber = ber_decode $data, $profile;
395 475
396=item $type = $profile->get ($class, $tag) 476=item $type = $profile->get ($class, $tag)
438Encodes and decodes an OBJECT IDENTIFIER into dotted form without leading 518Encodes and decodes an OBJECT IDENTIFIER into dotted form without leading
439dot, e.g. C<1.3.6.1.213>. 519dot, e.g. C<1.3.6.1.213>.
440 520
441=item C<BER_TYPE_RELOID> 521=item C<BER_TYPE_RELOID>
442 522
443Same as C<BER_TYPE_OID> but uses relative OID encoding: ASN.1 has this 523Same as C<BER_TYPE_OID> but uses relative object identifier
444hack of encoding the first two OID components into a single integer in a 524encoding: ASN.1 has this hack of encoding the first two OID components
445weird attempt to save an insignificant amount of space in an otherwise 525into a single integer in a weird attempt to save an insignificant amount
446wasteful encoding, and relative OIDs are basically OIDs without this 526of space in an otherwise wasteful encoding, and relative OIDs are
447hack. The practical difference is that the second component of an OID 527basically OIDs without this hack. The practical difference is that the
448can only have the values 1..40, while relative OIDs do not have this 528second component of an OID can only have the values 1..40, while relative
449restriction. 529OIDs do not have this restriction.
450 530
451=item C<BER_TYPE_NULL> 531=item C<BER_TYPE_NULL>
452 532
453Decodes an C<ASN_NULL> value into C<undef>, and always encodes a 533Decodes an C<ASN_NULL> value into C<undef>, and always encodes a
454C<ASN_NULL> type, regardless of the perl value. 534C<ASN_NULL> type, regardless of the perl value.
462 542
463Decodes/encodes a BER real value. NOT IMPLEMENTED. 543Decodes/encodes a BER real value. NOT IMPLEMENTED.
464 544
465=item C<BER_TYPE_IPADDRESS> 545=item C<BER_TYPE_IPADDRESS>
466 546
467Decodes/encodes a four byte string into an IOv4 dotted-quad address string 547Decodes/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 548in Perl. Given the obsolete nature of this type, this is a low-effort
469implementation that simply uses C<sprintf> and C<sscanf>-style conversion, 549implementation that simply uses C<sprintf> and C<sscanf>-style conversion,
470so it won't handle all string forms supported by C<inet_aton>. 550so it won't handle all string forms supported by C<inet_aton> for example.
471 551
472=item C<BER_TYPE_CROAK> 552=item C<BER_TYPE_CROAK>
473 553
474Always croaks when encountered during encoding or decoding - the 554Always croaks when encountered during encoding or decoding - the
475default behaviour when encountering an unknown type is to treat it as 555default behaviour when encountering an unknown type is to treat it as
476C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard 556C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard
477error for some types, then CyBER_TYPE_CROAK> is for you. 557error for some types, then C<BER_TYPE_CROAK> is for you.
478 558
479=back 559=back
480 560
481=cut 561=cut
482 562
483our $DEFAULT_PROFILE = new Convert::BER::XS::Profile; 563our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
484our $SNMP_PROFILE = new Convert::BER::XS::Profile; 564our $SNMP_PROFILE = new Convert::BER::XS::Profile;
485 565
566# additional SNMP application types
486$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS); 567$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
487$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT); 568$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
488$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 569$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
489$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 570$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
490$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 571$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
492 573
493$DEFAULT_PROFILE->_set_default; 574$DEFAULT_PROFILE->_set_default;
494 575
4951; 5761;
496 577
497=head2 LIMITATIONS 578=head2 LIMITATIONS/NOTES
498 579
499This module can only en-/decode 64 bit signed and unsigned integers, and 580This module can only en-/decode 64 bit signed and unsigned integers, and
500only when your perl supports those. 581only when your perl supports those.
501 582
583This module does not generally care about ranges, i.e. it will happily
584de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative
585number into an C<SNMP_COUNTER64>.
586
502OBJECT IDENTIFIEERS cannot have unlimited length, although the limit is 587OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
503much larger than e.g. the one imposed by SNMP or other protocols. 588much larger than e.g. the one imposed by SNMP or other protocols,a nd is
589about 4kB.
504 590
505REAL values are not supported and will croak. 591REAL values are not supported and will currently croak.
506 592
507This module has undergone little to no testing so far. 593This module has undergone little to no testing so far.
594
595=head2 ITHREADS SUPPORT
596
597This module is unlikely to work when the (officially discouraged) ithreads
598are in use.
508 599
509=head1 AUTHOR 600=head1 AUTHOR
510 601
511 Marc Lehmann <schmorp@schmorp.de> 602 Marc Lehmann <schmorp@schmorp.de>
512 http://software.schmorp.de/pkg/Convert-BER-XS 603 http://software.schmorp.de/pkg/Convert-BER-XS

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines