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.33 by root, Sat Apr 20 17:23:21 2019 UTC vs.
Revision 1.49 by root, Sun Apr 21 23:10:11 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";
… …
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
… …
141 144
142=item C<:decode> 145=item C<:decode>
143 146
144C<ber_decode> and the match helper functions: 147C<ber_decode> and the match helper functions:
145 148
149 ber_decode ber-decode_prefix
146 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
147 152
148=item C<:encode> 153=item C<:encode>
149 154
150C<ber_encode> and the construction helper functions: 155C<ber_encode> and the construction helper functions:
151 156
152 ber_encode ber_int 157 ber_encode
158 ber_int
153 159
154=back 160=back
155 161
156=head2 ASN.1/BER/DER/... BASICS 162=head2 ASN.1/BER/DER/... BASICS
157 163
… …
253 259
254=head2 DECODING AND ENCODING 260=head2 DECODING AND ENCODING
255 261
256=over 262=over
257 263
258=item $tuple = ber_decoded $bindata[, $profile] 264=item $tuple = ber_decode $bindata[, $profile]
259 265
260Decodes binary BER data in C<$bindata> and returns the resulting BER 266Decodes binary BER data in C<$bindata> and returns the resulting BER
261tuple. 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
262valid. 268valid.
263 269
… …
275 $tuple = ber_decode $data; 281 $tuple = ber_decode $data;
276 282
277Example: as above, but use the provided SNMP profile. 283Example: as above, but use the provided SNMP profile.
278 284
279 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE; 285 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
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.
280 298
281=item $bindata = ber_encode $tuple[, $profile] 299=item $bindata = ber_encode $tuple[, $profile]
282 300
283Encodes the BER tuple into a BER/DER data structure. AS with 301Encodes the BER tuple into a BER/DER data structure. AS with
284Cyber_decode>, an optional profile can be given. 302Cyber_decode>, an optional profile can be given.
… …
394use Exporter qw(import); 412use Exporter qw(import);
395 413
396our $VERSION; 414our $VERSION;
397 415
398BEGIN { 416BEGIN {
399 $VERSION = 0.9; 417 $VERSION = 1.1;
400 XSLoader::load __PACKAGE__, $VERSION; 418 XSLoader::load __PACKAGE__, $VERSION;
401} 419}
402 420
403our %EXPORT_TAGS = ( 421our %EXPORT_TAGS = (
404 const_index => [qw( 422 const_index => [qw(
405 BER_CLASS BER_TAG BER_FLAGS BER_DATA 423 BER_CLASS BER_TAG BER_FLAGS BER_DATA
406 )], 424 )],
425 const_asn_class => [qw(
426 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
427 )],
407 const_asn => [qw( 428 const_asn_tag => [qw(
408 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
409 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
410 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
411 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
412 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
413 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
414
415 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
416 )], 435 )],
417 const_ber_type => [qw( 436 const_ber_type => [qw(
418 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
419 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
420 BER_TYPE_IPADDRESS BER_TYPE_CROAK 439 BER_TYPE_IPADDRESS BER_TYPE_CROAK
… …
422 const_snmp => [qw( 441 const_snmp => [qw(
423 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_GAUGE32 SNMP_UNSIGNED32 442 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_GAUGE32 SNMP_UNSIGNED32
424 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 443 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
425 )], 444 )],
426 decode => [qw( 445 decode => [qw(
427 ber_decode 446 ber_decode ber_decode_prefix
428 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
429 )], 449 )],
430 encode => [qw( 450 encode => [qw(
431 ber_encode 451 ber_encode
432 ber_int 452 ber_int
433 )], 453 )],
434); 454);
435 455
436our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 456our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
437 457
438$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)];
439$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$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
474
475=head2 DEBUGGING
476
477To aid debugging, you cna call the C<ber_dump> function to print a "nice"
478representation to STDOUT.
479
480=over
481
482=item ber_dump $tuple[, $profile[, $prefix]]
483
484In addition to specifying the BER C<$tuple> to dump, youc an also specify
485a C<$profile> and a C<$prefix> string that is printed in front of each line.
486
487If C<$profile> is C<$Convert::BER::XS::SNMP_PROFILE>, then C<ber_dump>
488will try to improve its output for SNMP data.
489
490The output usually contains three columns, the "human readable" tag, the
491BER type used to decode it, and the data value.
492
493This function is somewhat slow and uses a number of heuristics and tricks,
494so it really is only suitable for debug prints.
495
496Example output:
497
498 SEQUENCE
499 | OCTET_STRING bytes 800063784300454045045400000001
500 | OCTET_STRING bytes
501 | CONTEXT (7) CONSTRUCTED
502 | | INTEGER int 1058588941
503 | | INTEGER int 0
504 | | INTEGER int 0
505 | | SEQUENCE
506 | | | SEQUENCE
507 | | | | OID oid 1.3.6.1.2.1.1.3.0
508 | | | | TIMETICKS int 638085796
509
510=back
511
512=cut
513
514# reverse enum, very slow and ugly hack
515sub _re {
516 my ($export_tag, $value) = @_;
517
518 for my $symbol (@{ $EXPORT_TAGS{$export_tag} }) {
519 $value == eval $symbol
520 and return $symbol;
521 }
522
523 "($value)"
524}
525
526$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
527
528sub _ber_dump {
529 my ($ber, $profile, $indent) = @_;
530
531 if (my $seq = ber_is_seq $ber) {
532 printf "%sSEQUENCE\n", $indent;
533 &_ber_dump ($_, $profile, "$indent| ")
534 for @$seq;
535 } else {
536 my $asn = $ber->[BER_CLASS] == ASN_UNIVERSAL;
537
538 my $class = _re const_asn_class => $ber->[BER_CLASS];
539 my $tag = $asn ? _re const_asn_tag => $ber->[BER_TAG] : $ber->[BER_TAG];
540 my $type = _re const_ber_type => $profile->get ($ber->[BER_CLASS], $ber->[BER_TAG]);
541 my $data = $ber->[BER_DATA];
542
543 if ($profile == $SNMP_PROFILE and $ber->[BER_CLASS] == ASN_APPLICATION) {
544 $tag = _re const_snmp => $ber->[BER_TAG];
545 } elsif (!$asn) {
546 $tag = "$class ($tag)";
547 }
548
549 $class =~ s/^ASN_//;
550 $tag =~ s/^(ASN_|SNMP_)//;
551 $type =~ s/^BER_TYPE_//;
552
553 if ($ber->[BER_FLAGS]) {
554 printf "$indent%-16.16s CONSTRUCTED\n", $tag;
555 &_ber_dump ($_, $profile, "$indent| ")
556 for @$data;
557 } else {
558 if ($data =~ y/\x20-\x7e//c / (length $data || 1) > 0.2 or $data =~ /\x00./s) {
559 # assume binary
560 $data = unpack "H*", $data;
561 } else {
562 $data =~ s/[^\x20-\x7e]/./g;
563 $data = "\"$data\"" if $type =~ /string/i || !length $data;
564 }
565
566 substr $data, 40, 1e9, "..." if 40 < length $data;
567
568 printf "$indent%-16.16s %-6.6s %s\n", $tag, lc $type, $data;
569 }
570 }
571}
572
573sub ber_dump($;$$) {
574 _ber_dump $_[0], $_[1] || $DEFAULT_PROFILE, $_[2];
575}
440 576
441=head1 PROFILES 577=head1 PROFILES
442 578
443While any BER data can be correctly encoded and decoded out of the box, it 579While any BER data can be correctly encoded and decoded out of the box, it
444can be inconvenient to have to manually decode some values into a "better" 580can be inconvenient to have to manually decode some values into a "better"
… …
505 641
506Returns the BER type mapped to the given C<$class>/C<$tag> combination. 642Returns the BER type mapped to the given C<$class>/C<$tag> combination.
507 643
508=back 644=back
509 645
510=head2 BER TYPES 646=head2 BER Types
511 647
512This lists the predefined BER types - you can map any C<CLASS>/C<TAG> 648This lists the predefined BER types. BER types are formatters used
513combination to any C<BER_TYPE_*>. 649internally to format and encode BER values. You can assign any C<BER_TYPE>
650to any C<CLASS>/C<TAG> combination tgo change how that tag is decoded or
651encoded.
514 652
515=over 653=over
516 654
517=item C<BER_TYPE_BYTES> 655=item C<BER_TYPE_BYTES>
518 656
… …
598 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 736 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
599 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 737 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
600 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 738 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
601 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT); 739 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
602 740
603=cut
604
605our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
606
607$DEFAULT_PROFILE->_set_default;
608
609# additional SNMP application types
610our $SNMP_PROFILE = new Convert::BER::XS::Profile;
611
612$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
613$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
614$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
615$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
616$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
617$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
618
6191;
620
621=head2 LIMITATIONS/NOTES 741=head2 LIMITATIONS/NOTES
622 742
623This module can only en-/decode 64 bit signed and unsigned integers, and 743This module can only en-/decode 64 bit signed and unsigned integers, and
624only when your perl supports those. 744only when your perl supports those. So no UUID OIDs for now (unless you
745map the C<OBJECT IDENTIFIER> tag to something other than C<BER_TYPE_OID>).
625 746
626This module does not generally care about ranges, i.e. it will happily 747This module does not generally care about ranges, i.e. it will happily
627de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative 748de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
628number into an C<SNMP_COUNTER64>. 749number into an C<SNMP_COUNTER64>.
629 750
630OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 751OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
631much larger than e.g. the one imposed by SNMP or other protocols,a nd is 752much larger than e.g. the one imposed by SNMP or other protocols, and is
632about 4kB. 753about 4kB.
633 754
634Indefinite length encoding is not supported. 755Indefinite length encoding is not supported.
635 756
636Constructed strings are decoded just fine, but there should be a way to 757Constructed strings are decoded just fine, but there should be a way to
637join them for convenience. 758join them for convenience.
638 759
639REAL values are not supported and will currently croak. 760REAL values are not supported and will currently croak.
640 761
641The encoder and decoder tend to accept more formats than should be 762The encoder and decoder tend to accept more formats than should be
642strictly supported. 763strictly supported - security sensitive applications are strongly advised
764to review the code first.
643 765
644This module has undergone little to no testing so far. 766This module has undergone little to no testing so far.
645 767
646=head2 ITHREADS SUPPORT 768=head2 ITHREADS SUPPORT
647 769
… …
653 Marc Lehmann <schmorp@schmorp.de> 775 Marc Lehmann <schmorp@schmorp.de>
654 http://software.schmorp.de/pkg/Convert-BER-XS 776 http://software.schmorp.de/pkg/Convert-BER-XS
655 777
656=cut 778=cut
657 779
7801;
781

Diff Legend

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