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.35 by root, Sat Apr 20 21:51:40 2019 UTC vs.
Revision 1.60 by root, Thu Feb 6 11:51:40 2020 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
143 146
144C<ber_decode> and the match helper functions: 147C<ber_decode> and the match helper functions:
145 148
146 ber_decode ber-decode_prefix 149 ber_decode ber-decode_prefix
147 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
148 152
149=item C<:encode> 153=item C<:encode>
150 154
151C<ber_encode> and the construction helper functions: 155C<ber_encode> and the construction helper functions:
152 156
292Also, since BER is self-delimited, this can be used to decode multiple BER 296Also, since BER is self-delimited, this can be used to decode multiple BER
293values joined together. 297values joined together.
294 298
295=item $bindata = ber_encode $tuple[, $profile] 299=item $bindata = ber_encode $tuple[, $profile]
296 300
297Encodes the BER tuple into a BER/DER data structure. AS with 301Encodes the BER tuple into a BER/DER data structure. As with
298Cyber_decode>, an optional profile can be given. 302Cyber_decode>, an optional profile can be given.
299 303
300The encoded data should be both BER and DER ("shortest form") compliant 304The encoded data should be both BER and DER ("shortest form") compliant
301unless the input says otherwise (e.g. it uses constructed strings). 305unless the input says otherwise (e.g. it uses constructed strings).
302 306
405use common::sense; 409use common::sense;
406 410
407use XSLoader (); 411use XSLoader ();
408use Exporter qw(import); 412use Exporter qw(import);
409 413
414use Carp ();
415
410our $VERSION; 416our $VERSION;
411 417
412BEGIN { 418BEGIN {
413 $VERSION = '1.0'; 419 $VERSION = 1.21;
414 XSLoader::load __PACKAGE__, $VERSION; 420 XSLoader::load __PACKAGE__, $VERSION;
415} 421}
416 422
417our %EXPORT_TAGS = ( 423our %EXPORT_TAGS = (
418 const_index => [qw( 424 const_index => [qw(
419 BER_CLASS BER_TAG BER_FLAGS BER_DATA 425 BER_CLASS BER_TAG BER_FLAGS BER_DATA
420 )], 426 )],
427 const_asn_class => [qw(
428 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
429 )],
421 const_asn => [qw( 430 const_asn_tag => [qw(
422 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 431 ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OID ASN_OBJECT_IDENTIFIER
423 ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED 432 ASN_OBJECT_DESCRIPTOR ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
424 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING 433 ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
425 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 434 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
426 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 435 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
427 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 436 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
428
429 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
430 )], 437 )],
431 const_ber_type => [qw( 438 const_ber_type => [qw(
432 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT 439 BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
433 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL 440 BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
434 BER_TYPE_IPADDRESS BER_TYPE_CROAK 441 BER_TYPE_IPADDRESS BER_TYPE_CROAK
438 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 445 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
439 )], 446 )],
440 decode => [qw( 447 decode => [qw(
441 ber_decode ber_decode_prefix 448 ber_decode ber_decode_prefix
442 ber_is ber_is_seq ber_is_int ber_is_oid 449 ber_is ber_is_seq ber_is_int ber_is_oid
450 ber_dump
443 )], 451 )],
444 encode => [qw( 452 encode => [qw(
445 ber_encode 453 ber_encode
446 ber_int 454 ber_int
447 )], 455 )],
448); 456);
449 457
450our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 458our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
451 459
452$EXPORT_TAGS{all} = \@EXPORT_OK; 460$EXPORT_TAGS{all} = \@EXPORT_OK;
461$EXPORT_TAGS{const_asn} = [map @{ $EXPORT_TAGS{$_} }, qw(const_asn_class const_asn_tag)];
453$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)]; 462$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
463
464our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
465
466$DEFAULT_PROFILE->_set_default;
467
468# additional SNMP application types
469our $SNMP_PROFILE = new Convert::BER::XS::Profile;
470
471$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
472$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
473$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
474$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
475
476# decodes REAL values according to ECMA-63
477# this is pretty strict, except it doesn't catch -0.
478# I don't have access to ISO 6093 (or BS 6727, or ANSI X.3-42)), so this is all guesswork.
479sub _decode_real_decimal {
480 my ($format, $val) = @_;
481
482 $val =~ y/,/./; # probably not in ISO-6093
483
484 if ($format == 1) {
485 $val =~ /^ \ * [+-]? [0-9]+ \z/x
486 or Carp::croak "BER_TYPE_REAL NR1 value not in NR1 format ($val) (X.690 8.5.8)";
487 } elsif ($format == 2) {
488 $val =~ /^ \ * [+-]? (?: [0-9]+\.[0-9]* | [0-9]*\.[0-9]+ ) \z/x
489 or Carp::croak "BER_TYPE_REAL NR2 value not in NR2 format ($val) (X.690 8.5.8)";
490 } elsif ($format == 3) {
491 $val =~ /^ \ * [+-] (?: [0-9]+\.[0-9]* | [0-9]*\.[0-9]+ ) [eE] [+-]? [0-9]+ \z/x
492 or Carp::croak "BER_TYPE_REAL NR3 value not in NR3 format ($val) (X.690 8.5.8)";
493 } else {
494 Carp::croak "BER_TYPE_REAL invalid decimal numerical representation format $format";
495 }
496
497 $val
498}
499
500# this is a mess, but perl's support for floating point formatting is nearly nonexistant
501sub _encode_real_decimal {
502 my ($val, $nvdig) = @_;
503
504 $val = sprintf "%.*G", $nvdig + 1, $val;
505
506 if ($val =~ /E/) {
507 $val =~ s/E(?=[^+-])/E+/;
508 $val =~ s/E/.E/ if $val !~ /\./;
509 $val =~ s/^/+/ unless $val =~ /^-/;
510
511 return "\x03$val" # NR3
512 }
513
514 $val =~ /\./
515 ? "\x02$val" # NR2
516 : "\x01$val" # NR1
517}
518
519=head2 DEBUGGING
520
521To aid debugging, you can call the C<ber_dump> function to print a "nice"
522representation to STDOUT.
523
524=over
525
526=item ber_dump $tuple[, $profile[, $prefix]]
527
528In addition to specifying the BER C<$tuple> to dump, you can also specify
529a C<$profile> and a C<$prefix> string that is printed in front of each line.
530
531If C<$profile> is C<$Convert::BER::XS::SNMP_PROFILE>, then C<ber_dump>
532will try to improve its output for SNMP data.
533
534The output usually contains three columns, the "human readable" tag, the
535BER type used to decode it, and the data value.
536
537This function is somewhat slow and uses a number of heuristics and tricks,
538so it really is only suitable for debug prints.
539
540Example output:
541
542 SEQUENCE
543 | OCTET_STRING bytes 800063784300454045045400000001
544 | OCTET_STRING bytes
545 | CONTEXT (7) CONSTRUCTED
546 | | INTEGER int 1058588941
547 | | INTEGER int 0
548 | | INTEGER int 0
549 | | SEQUENCE
550 | | | SEQUENCE
551 | | | | OID oid 1.3.6.1.2.1.1.3.0
552 | | | | TIMETICKS int 638085796
553
554=back
555
556=cut
557
558# reverse enum, very slow and ugly hack
559sub _re {
560 my ($export_tag, $value) = @_;
561
562 for my $symbol (@{ $EXPORT_TAGS{$export_tag} }) {
563 $value == eval $symbol
564 and return $symbol;
565 }
566
567 "($value)"
568}
569
570$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
571
572sub _ber_dump {
573 my ($ber, $profile, $indent) = @_;
574
575 if (my $seq = ber_is_seq $ber) {
576 printf "%sSEQUENCE\n", $indent;
577 &_ber_dump ($_, $profile, "$indent| ")
578 for @$seq;
579 } else {
580 my $asn = $ber->[BER_CLASS] == ASN_UNIVERSAL;
581
582 my $class = _re const_asn_class => $ber->[BER_CLASS];
583 my $tag = $asn ? _re const_asn_tag => $ber->[BER_TAG] : $ber->[BER_TAG];
584 my $type = _re const_ber_type => $profile->get ($ber->[BER_CLASS], $ber->[BER_TAG]);
585 my $data = $ber->[BER_DATA];
586
587 if ($profile == $SNMP_PROFILE and $ber->[BER_CLASS] == ASN_APPLICATION) {
588 $tag = _re const_snmp => $ber->[BER_TAG];
589 } elsif (!$asn) {
590 $tag = "$class ($tag)";
591 }
592
593 $class =~ s/^ASN_//;
594 $tag =~ s/^(ASN_|SNMP_)//;
595 $type =~ s/^BER_TYPE_//;
596
597 if ($ber->[BER_FLAGS]) {
598 printf "$indent%-16.16s\n", $tag;
599 &_ber_dump ($_, $profile, "$indent| ")
600 for @$data;
601 } else {
602 if ($data =~ y/\x20-\x7e//c / (length $data || 1) > 0.2 or $data =~ /\x00./s) {
603 # assume binary
604 $data = unpack "H*", $data;
605 } else {
606 $data =~ s/[^\x20-\x7e]/./g;
607 $data = "\"$data\"" if $tag =~ /string/i || !length $data;
608 }
609
610 substr $data, 40, 1e9, "..." if 40 < length $data;
611
612 printf "$indent%-16.16s %-6.6s %s\n", $tag, lc $type, $data;
613 }
614 }
615}
616
617sub ber_dump($;$$) {
618 _ber_dump $_[0], $_[1] || $DEFAULT_PROFILE, $_[2];
619}
454 620
455=head1 PROFILES 621=head1 PROFILES
456 622
457While any BER data can be correctly encoded and decoded out of the box, it 623While any BER data can be correctly encoded and decoded out of the box, it
458can be inconvenient to have to manually decode some values into a "better" 624can be inconvenient to have to manually decode some values into a "better"
519 685
520Returns the BER type mapped to the given C<$class>/C<$tag> combination. 686Returns the BER type mapped to the given C<$class>/C<$tag> combination.
521 687
522=back 688=back
523 689
524=head2 BER TYPES 690=head2 BER Types
525 691
526This lists the predefined BER types - you can map any C<CLASS>/C<TAG> 692This lists the predefined BER types. BER types are formatters used
527combination to any C<BER_TYPE_*>. 693internally to format and encode BER values. You can assign any C<BER_TYPE>
694to any C<CLASS>/C<TAG> combination tgo change how that tag is decoded or
695encoded.
528 696
529=over 697=over
530 698
531=item C<BER_TYPE_BYTES> 699=item C<BER_TYPE_BYTES>
532 700
609 777
610 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS); 778 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
611 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT); 779 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
612 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 780 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
613 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 781 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
614 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 782 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_BYTES);
615 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT); 783 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
616 784
617=cut
618
619our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
620
621$DEFAULT_PROFILE->_set_default;
622
623# additional SNMP application types
624our $SNMP_PROFILE = new Convert::BER::XS::Profile;
625
626$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
627$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
628$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
629$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
630$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
631$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
632
6331;
634
635=head2 LIMITATIONS/NOTES 785=head2 LIMITATIONS/NOTES
636 786
637This module can only en-/decode 64 bit signed and unsigned integers, and 787This module can only en-/decode 64 bit signed and unsigned
638only when your perl supports those. 788integers/tags/lengths, and only when your perl supports those. So no UUID
789OIDs for now (unless you map the C<OBJECT IDENTIFIER> tag to something
790other than C<BER_TYPE_OID>).
639 791
640This module does not generally care about ranges, i.e. it will happily 792This module does not generally care about ranges, i.e. it will happily
641de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative 793de-/encode 64 bit integers into an C<SNMP_UNSIGNED32> value, or a negative
642number into an C<SNMP_COUNTER64>. 794number into an C<SNMP_COUNTER64>.
643 795
644OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 796OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
645much larger than e.g. the one imposed by SNMP or other protocols,a nd is 797much larger than e.g. the one imposed by SNMP or other protocols, and is
646about 4kB. 798about 4kB.
647
648Indefinite length encoding is not supported.
649 799
650Constructed strings are decoded just fine, but there should be a way to 800Constructed strings are decoded just fine, but there should be a way to
651join them for convenience. 801join them for convenience.
652 802
653REAL values are not supported and will currently croak. 803REAL values will always be encoded in decimal form and ssometimes is
654 804forced into a perl "NV" type, potentially losing precision.
655The encoder and decoder tend to accept more formats than should be
656strictly supported.
657
658This module has undergone little to no testing so far.
659 805
660=head2 ITHREADS SUPPORT 806=head2 ITHREADS SUPPORT
661 807
662This module is unlikely to work when the (officially discouraged) ithreads 808This module is unlikely to work in any other than the loading thread when
663are in use. 809the (officially discouraged) ithreads are in use.
664 810
665=head1 AUTHOR 811=head1 AUTHOR
666 812
667 Marc Lehmann <schmorp@schmorp.de> 813 Marc Lehmann <schmorp@schmorp.de>
668 http://software.schmorp.de/pkg/Convert-BER-XS 814 http://software.schmorp.de/pkg/Convert-BER-XS
669 815
670=cut 816=cut
671 817
8181;
819

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines