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.32 by root, Sat Apr 20 16:12:53 2019 UTC vs.
Revision 1.55 by root, Tue Apr 23 21:20:25 2019 UTC

… …
8 8
9 my $ber = ber_decode $buf, $Convert::BER::XS::SNMP_PROFILE 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, flags, data) 13 # (class, tag, flags, 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?
… …
36 [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value 36 [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
37 ] 37 ]
38 ] 38 ]
39 ], 39 ],
40 ... 40 ...
41 # let's dump it, for debugging
42
43 ber_dump $ber, $Convert::BER::XS::SNMP_PROFILE;
41 44
42 # let's decode it a bit with some helper functions 45 # let's decode it a bit with some helper functions
43 46
44 my $msg = ber_is_seq $ber 47 my $msg = ber_is_seq $ber
45 or die "SNMP message does not start with a sequence"; 48 or die "SNMP message does not start with a sequence";
… …
105 BER_CLASS BER_TAG BER_FLAGS BER_DATA 108 BER_CLASS BER_TAG BER_FLAGS BER_DATA
106 109
107=item C<:const_asn> 110=item C<:const_asn>
108 111
109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively - 112ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
110exactly thw two topmost bits from the identifier octet shifted 6 bits to 113exactly the two topmost bits from the identifier octet shifted 6 bits to
111the right): 114the right):
112 115
113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE 116 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
114 117
115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their 118ASN 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. 119numerical value corresponds exactly to the numbers used in BER/X.690.
117 120
118 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 121 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OID
119 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 122 ASN_OBJECT_IDENTIFIER ASN_OBJECT_DESCRIPTOR ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
120 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 123 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 124 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 125 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 126 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
124 127
… …
134 137
135Constants only relevant to SNMP. These are the tag values used by SNMP in 138Constants 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 139the C<ASN_APPLICATION> namespace and have the exact numerical value as in
137BER/RFC 2578. 140BER/RFC 2578.
138 141
139 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 142 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_GAUGE32
143 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
140 144
141=item C<:decode> 145=item C<:decode>
142 146
143C<ber_decode> and the match helper functions: 147C<ber_decode> and the match helper functions:
144 148
149 ber_decode ber-decode_prefix
145 ber_decode ber_is ber_is_seq ber_is_int ber_is_oid 150 ber_is ber_is_seq ber_is_int ber_is_oid
151 ber_dump
146 152
147=item C<:encode> 153=item C<:encode>
148 154
149C<ber_encode> and the construction helper functions: 155C<ber_encode> and the construction helper functions:
150 156
151 ber_encode ber_int 157 ber_encode
158 ber_int
152 159
153=back 160=back
154 161
155=head2 ASN.1/BER/DER/... BASICS 162=head2 ASN.1/BER/DER/... BASICS
156 163
… …
252 259
253=head2 DECODING AND ENCODING 260=head2 DECODING AND ENCODING
254 261
255=over 262=over
256 263
257=item $tuple = ber_decoded $bindata[, $profile] 264=item $tuple = ber_decode $bindata[, $profile]
258 265
259Decodes binary BER data in C<$bindata> and returns the resulting BER 266Decodes binary BER data in C<$bindata> and returns the resulting BER
260tuple. Croaks on any decoding error, so the returned C<$tuple> is always 267tuple. Croaks on any decoding error, so the returned C<$tuple> is always
261valid. 268valid.
262 269
… …
275 282
276Example: as above, but use the provided SNMP profile. 283Example: as above, but use the provided SNMP profile.
277 284
278 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE; 285 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
279 286
287=item ($tuple, $bytes) = ber_decode_prefix $bindata[, $profile]
288
289Works like C<ber_decode>, except it doesn't croak when there is data after
290the BER data, but instead returns the decoded value and the number of
291bytes it decoded.
292
293This is useful when you have BER data at the start of a buffer and other
294data after, and you need to find the length.
295
296Also, since BER is self-delimited, this can be used to decode multiple BER
297values joined together.
298
280=item $bindata = ber_encode $tuple[, $profile] 299=item $bindata = ber_encode $tuple[, $profile]
281 300
282Encodes the BER tuple into a BER/DER data structure. AS with 301Encodes the BER tuple into a BER/DER data structure. As with
283Cyber_decode>, an optional profile can be given. 302Cyber_decode>, an optional profile can be given.
284 303
285The encoded data should be both BER and DER ("shortest form") compliant 304The encoded data should be both BER and DER ("shortest form") compliant
286unless the input says otherwise (e.g. it uses constructed strings). 305unless the input says otherwise (e.g. it uses constructed strings).
287 306
… …
393use Exporter qw(import); 412use Exporter qw(import);
394 413
395our $VERSION; 414our $VERSION;
396 415
397BEGIN { 416BEGIN {
398 $VERSION = 0.9; 417 $VERSION = 1.11;
399 XSLoader::load __PACKAGE__, $VERSION; 418 XSLoader::load __PACKAGE__, $VERSION;
400} 419}
401 420
402our %EXPORT_TAGS = ( 421our %EXPORT_TAGS = (
403 const_index => [qw( 422 const_index => [qw(
404 BER_CLASS BER_TAG BER_FLAGS BER_DATA 423 BER_CLASS BER_TAG BER_FLAGS BER_DATA
405 )], 424 )],
425 const_asn_class => [qw(
426 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
427 )],
406 const_asn => [qw( 428 const_asn_tag => [qw(
407 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 429 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OID ASN_OBJECT_IDENTIFIER
408 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 430 ASN_OBJECT_DESCRIPTOR ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
409 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 431 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
410 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 432 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
411 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 433 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
412 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 434 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
413
414 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
415 )], 435 )],
416 const_ber_type => [qw( 436 const_ber_type => [qw(
417 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT 437 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
418 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL 438 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
419 BER_TYPE_IPADDRESS BER_TYPE_CROAK 439 BER_TYPE_IPADDRESS BER_TYPE_CROAK
420 )], 440 )],
421 const_snmp => [qw( 441 const_snmp => [qw(
422 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 442 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_GAUGE32 SNMP_UNSIGNED32
443 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
423 )], 444 )],
424 decode => [qw( 445 decode => [qw(
425 ber_decode 446 ber_decode ber_decode_prefix
426 ber_is ber_is_seq ber_is_int ber_is_oid 447 ber_is ber_is_seq ber_is_int ber_is_oid
448 ber_dump
427 )], 449 )],
428 encode => [qw( 450 encode => [qw(
429 ber_encode 451 ber_encode
430 ber_int 452 ber_int
431 )], 453 )],
432); 454);
433 455
434our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 456our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
435 457
436$EXPORT_TAGS{all} = \@EXPORT_OK; 458$EXPORT_TAGS{all} = \@EXPORT_OK;
459$EXPORT_TAGS{const_asn} = [map @{ $EXPORT_TAGS{$_} }, qw(const_asn_class const_asn_tag)];
437$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)]; 460$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
461
462our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
463
464$DEFAULT_PROFILE->_set_default;
465
466# additional SNMP application types
467our $SNMP_PROFILE = new Convert::BER::XS::Profile;
468
469$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
470$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
471$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
472$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
473
474=head2 DEBUGGING
475
476To aid debugging, you cna call the C<ber_dump> function to print a "nice"
477representation to STDOUT.
478
479=over
480
481=item ber_dump $tuple[, $profile[, $prefix]]
482
483In addition to specifying the BER C<$tuple> to dump, you can also specify
484a C<$profile> and a C<$prefix> string that is printed in front of each line.
485
486If C<$profile> is C<$Convert::BER::XS::SNMP_PROFILE>, then C<ber_dump>
487will try to improve its output for SNMP data.
488
489The output usually contains three columns, the "human readable" tag, the
490BER type used to decode it, and the data value.
491
492This function is somewhat slow and uses a number of heuristics and tricks,
493so it really is only suitable for debug prints.
494
495Example output:
496
497 SEQUENCE
498 | OCTET_STRING bytes 800063784300454045045400000001
499 | OCTET_STRING bytes
500 | CONTEXT (7) CONSTRUCTED
501 | | INTEGER int 1058588941
502 | | INTEGER int 0
503 | | INTEGER int 0
504 | | SEQUENCE
505 | | | SEQUENCE
506 | | | | OID oid 1.3.6.1.2.1.1.3.0
507 | | | | TIMETICKS int 638085796
508
509=back
510
511=cut
512
513# reverse enum, very slow and ugly hack
514sub _re {
515 my ($export_tag, $value) = @_;
516
517 for my $symbol (@{ $EXPORT_TAGS{$export_tag} }) {
518 $value == eval $symbol
519 and return $symbol;
520 }
521
522 "($value)"
523}
524
525$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
526
527sub _ber_dump {
528 my ($ber, $profile, $indent) = @_;
529
530 if (my $seq = ber_is_seq $ber) {
531 printf "%sSEQUENCE\n", $indent;
532 &_ber_dump ($_, $profile, "$indent| ")
533 for @$seq;
534 } else {
535 my $asn = $ber->[BER_CLASS] == ASN_UNIVERSAL;
536
537 my $class = _re const_asn_class => $ber->[BER_CLASS];
538 my $tag = $asn ? _re const_asn_tag => $ber->[BER_TAG] : $ber->[BER_TAG];
539 my $type = _re const_ber_type => $profile->get ($ber->[BER_CLASS], $ber->[BER_TAG]);
540 my $data = $ber->[BER_DATA];
541
542 if ($profile == $SNMP_PROFILE and $ber->[BER_CLASS] == ASN_APPLICATION) {
543 $tag = _re const_snmp => $ber->[BER_TAG];
544 } elsif (!$asn) {
545 $tag = "$class ($tag)";
546 }
547
548 $class =~ s/^ASN_//;
549 $tag =~ s/^(ASN_|SNMP_)//;
550 $type =~ s/^BER_TYPE_//;
551
552 if ($ber->[BER_FLAGS]) {
553 printf "$indent%-16.16s\n", $tag;
554 &_ber_dump ($_, $profile, "$indent| ")
555 for @$data;
556 } else {
557 if ($data =~ y/\x20-\x7e//c / (length $data || 1) > 0.2 or $data =~ /\x00./s) {
558 # assume binary
559 $data = unpack "H*", $data;
560 } else {
561 $data =~ s/[^\x20-\x7e]/./g;
562 $data = "\"$data\"" if $tag =~ /string/i || !length $data;
563 }
564
565 substr $data, 40, 1e9, "..." if 40 < length $data;
566
567 printf "$indent%-16.16s %-6.6s %s\n", $tag, lc $type, $data;
568 }
569 }
570}
571
572sub ber_dump($;$$) {
573 _ber_dump $_[0], $_[1] || $DEFAULT_PROFILE, $_[2];
574}
438 575
439=head1 PROFILES 576=head1 PROFILES
440 577
441While any BER data can be correctly encoded and decoded out of the box, it 578While any BER data can be correctly encoded and decoded out of the box, it
442can be inconvenient to have to manually decode some values into a "better" 579can be inconvenient to have to manually decode some values into a "better"
… …
503 640
504Returns the BER type mapped to the given C<$class>/C<$tag> combination. 641Returns the BER type mapped to the given C<$class>/C<$tag> combination.
505 642
506=back 643=back
507 644
508=head2 BER TYPES 645=head2 BER Types
509 646
510This lists the predefined BER types - you can map any C<CLASS>/C<TAG> 647This lists the predefined BER types. BER types are formatters used
511combination to any C<BER_TYPE_*>. 648internally to format and encode BER values. You can assign any C<BER_TYPE>
649to any C<CLASS>/C<TAG> combination tgo change how that tag is decoded or
650encoded.
512 651
513=over 652=over
514 653
515=item C<BER_TYPE_BYTES> 654=item C<BER_TYPE_BYTES>
516 655
… …
593 732
594 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS); 733 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
595 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT); 734 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
596 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 735 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
597 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 736 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
598 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 737 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_BYTES);
599 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT); 738 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
600 739
601=cut
602
603our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
604
605$DEFAULT_PROFILE->_set_default;
606
607# additional SNMP application types
608our $SNMP_PROFILE = new Convert::BER::XS::Profile;
609
610$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
611$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
612$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
613$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
614$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
615$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
616
6171;
618
619=head2 LIMITATIONS/NOTES 740=head2 LIMITATIONS/NOTES
620 741
621This module can only en-/decode 64 bit signed and unsigned integers, and 742This module can only en-/decode 64 bit signed and unsigned integers, and
622only when your perl supports those. 743only when your perl supports those. So no UUID OIDs for now (unless you
744map the C<OBJECT IDENTIFIER> tag to something other than C<BER_TYPE_OID>).
623 745
624This module does not generally care about ranges, i.e. it will happily 746This module does not generally care about ranges, i.e. it will happily
625de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative 747de-/encode 64 bit integers into an C<SNMP_UNSIGNED32> value, or a negative
626number into an C<SNMP_COUNTER64>. 748number into an C<SNMP_COUNTER64>.
627 749
628OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 750OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
629much larger than e.g. the one imposed by SNMP or other protocols,a nd is 751much larger than e.g. the one imposed by SNMP or other protocols, and is
630about 4kB. 752about 4kB.
631
632Indefinite length encoding is not supported.
633 753
634Constructed strings are decoded just fine, but there should be a way to 754Constructed strings are decoded just fine, but there should be a way to
635join them for convenience. 755join them for convenience.
636 756
637REAL values are not supported and will currently croak. 757REAL values are not supported and will currently croak.
638 758
639The encoder and decoder tend to accept more formats than should be
640strictly supported.
641
642This module has undergone little to no testing so far.
643
644=head2 ITHREADS SUPPORT 759=head2 ITHREADS SUPPORT
645 760
646This module is unlikely to work when the (officially discouraged) ithreads 761This module is unlikely to work when the (officially discouraged) ithreads
647are in use. 762are in use.
648 763
… …
651 Marc Lehmann <schmorp@schmorp.de> 766 Marc Lehmann <schmorp@schmorp.de>
652 http://software.schmorp.de/pkg/Convert-BER-XS 767 http://software.schmorp.de/pkg/Convert-BER-XS
653 768
654=cut 769=cut
655 770
7711;
772

Diff Legend

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