cvsroot/Convert-BER-XS/XS.pm

=head1 NAME

Convert::BER::XS - I<very> low level BER decoding

=head1 SYNOPSIS

 use Convert::BER::XS ':all';

 my $ber = ber_decode $buf
    or die "unable to decode SNMP v1/v2c Message";

 # the above results in a data structure consisting of (class, tag,
 # constructed, data) tuples. here is such a message, SNMPv1 trap
 # with a cisoc mac change notification

 [ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
   [
      [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
      [ ASN_UNIVERSAL, 4, 0, "public" ], # community
      [ ASN_CONTEXT, 4, 1, # CHOICE, constructed
         [
            [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
            [ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1
            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
            [ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
            [ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
            [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
               [
                  [ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
                     [
                        [ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], # the oid
                        [ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
                        ]
                     ]
                  ],
                  ...

 # let's decode it a bit with some helper functions

 my $msg = ber_is_seq $ber
    or die "SNMP message does not start with a sequence";

 ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER32, 0
    or die "SNMP message does not start with snmp version\n";

 # message is SNMP v1 or v2c?
 if ($msg->[0][BER_DATA] == 0 || $msg->[0][BER_DATA] == 1) {

    # message is v1 trap?
    if (ber_is $msg->[2], ASN_CONTEXT, 4, 1) {
       my $trap = $msg->[2][BER_DATA];

       # check whether trap is a cisco mac notification mac changed message
       if (
          (ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects
          and (ber_is_i32 $trap->[2], 6)
          and (ber_is_i32 $trap->[3], 1) # mac changed msg
       ) {
          ... and so on

=head1 DESCRIPTION

This module implements a I<very> low level BER/DER decoder, and in the
future, probably also an encoder (tell me if you want an encoder, this
might speed up the process of getting one).

If is tuned for low memory and high speed, while still maintaining some
level of user-friendlyness.

Currently, not much is documented, as this is an initial release to
reserve CPAN namespace, stay tuned for a few days.

=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>

This module is I<not> the XS version of L<Convert::BER>, but a different
take at doing the same thing. I imagine this module would be a good base
for speeding up either fo these, or write a similar module, or write your
own LDAP or SNMP module for example.

=cut

package Convert::BER::XS;

use common::sense;

use XSLoader ();
use Exporter qw(import);

our $VERSION = '0.0';

XSLoader::load __PACKAGE__, $VERSION;

our %EXPORT_TAGS = (
   all => [qw(
      ber_decode
      ber_is ber_is_seq ber_is_i32 ber_is_oid
      BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
      ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER ASN_TAG_BER ASN_TAG_MASK
      ASN_CONSTRUCTED ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE ASN_CLASS_MASK ASN_CLASS_SHIFT
      ASN_SEQUENCE ASN_IPADDRESS ASN_COUNTER32 ASN_UNSIGNED32 ASN_TIMETICKS ASN_OPAQUE ASN_COUNTER64
   )],
);

our @EXPORT_OK = map @$_, values %EXPORT_TAGS;

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/Convert-BER-XS

=cut

Revision:	1.3
Committed:	Fri Apr 19 16:49:02 2019 UTC (7 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.2:	+30 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Convert::BER::XS - I<very> low level BER decoding
4
5			=head1 SYNOPSIS
6
7			use Convert::BER::XS ':all';
8
9			my $ber = ber_decode $buf
10			or die "unable to decode SNMP v1/v2c Message";
11
12	root	1.3	# the above results in a data structure consisting of (class, tag,
13			# constructed, data) tuples. here is such a message, SNMPv1 trap
14			# with a cisoc mac change notification
15
16			[ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
17			[
18			[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
19			[ ASN_UNIVERSAL, 4, 0, "public" ], # community
20			[ ASN_CONTEXT, 4, 1, # CHOICE, constructed
21			[
22			[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
23			[ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1
24			[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
25			[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
26			[ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
27			[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
28			[
29			[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
30			[
31			[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], # the oid
32			[ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
33			]
34			]
35			],
36			...
37
38			# let's decode it a bit with some helper functions
39
40	root	1.1	my $msg = ber_is_seq $ber
41			or die "SNMP message does not start with a sequence";
42
43			ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER32, 0
44			or die "SNMP message does not start with snmp version\n";
45
46	root	1.3	# message is SNMP v1 or v2c?
47	root	1.1	if ($msg->[0][BER_DATA] == 0 \|\| $msg->[0][BER_DATA] == 1) {
48
49	root	1.3	# message is v1 trap?
50	root	1.1	if (ber_is $msg->[2], ASN_CONTEXT, 4, 1) {
51			my $trap = $msg->[2][BER_DATA];
52
53			# check whether trap is a cisco mac notification mac changed message
54			if (
55			(ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects
56			and (ber_is_i32 $trap->[2], 6)
57			and (ber_is_i32 $trap->[3], 1) # mac changed msg
58			) {
59			... and so on
60
61			=head1 DESCRIPTION
62
63			This module implements a I<very> low level BER/DER decoder, and in the
64			future, probably also an encoder (tell me if you want an encoder, this
65			might speed up the process of getting one).
66
67			If is tuned for low memory and high speed, while still maintaining some
68			level of user-friendlyness.
69
70			Currently, not much is documented, as this is an initial release to
71			reserve CPAN namespace, stay tuned for a few days.
72
73	root	1.2	=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
74
75			This module is I<not> the XS version of L<Convert::BER>, but a different
76			take at doing the same thing. I imagine this module would be a good base
77			for speeding up either fo these, or write a similar module, or write your
78			own LDAP or SNMP module for example.
79
80	root	1.1	=cut
81
82			package Convert::BER::XS;
83
84			use common::sense;
85
86			use XSLoader ();
87			use Exporter qw(import);
88
89			our $VERSION = '0.0';
90
91			XSLoader::load __PACKAGE__, $VERSION;
92
93			our %EXPORT_TAGS = (
94			all => [qw(
95			ber_decode
96			ber_is ber_is_seq ber_is_i32 ber_is_oid
97			BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
98			ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER ASN_TAG_BER ASN_TAG_MASK
99			ASN_CONSTRUCTED ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE ASN_CLASS_MASK ASN_CLASS_SHIFT
100			ASN_SEQUENCE ASN_IPADDRESS ASN_COUNTER32 ASN_UNSIGNED32 ASN_TIMETICKS ASN_OPAQUE ASN_COUNTER64
101			)],
102			);
103
104			our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
105
106			1;
107
108			=head1 AUTHOR
109
110			Marc Lehmann <schmorp@schmorp.de>
111			http://software.schmorp.de/pkg/Convert-BER-XS
112
113			=cut
114