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 (5 years, 1 month ago) by root
Branch:	MAIN
Changes since 1.2:	+30 -2 lines
Log Message:	* empty log message *
#	Content
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	# 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	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	# message is SNMP v1 or v2c?
47	if ($msg->[0][BER_DATA] == 0 \|\| $msg->[0][BER_DATA] == 1) {
48
49	# message is v1 trap?
50	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	=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	=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