[ViewVC] Diff of: cvs/Convert-BER-XS/XS.pm

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.17 by root, Sat Apr 20 13:46:14 2019 UTC vs.
Revision 1.23 by root, Sat Apr 20 14:53:29 2019 UTC

…		…
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use Convert::BER::XS ':all';	7	use Convert::BER::XS ':all';
8		8
9	my $ber = ber_decode $buf	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, # constructed, data)	13	# (class, tag, # constructed, 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?
19		19
20	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1,	20	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
21	[	21	[
22	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1	22	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
23	[ ASN_UNIVERSAL, 4, 0, "public" ], # community	23	[ ASN_UNIVERSAL, 4, 0, "public" ], # community
24	[ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU	24	[ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
25	[	25	[
26	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid	26	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid
27	[ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1	27	[ ASN_APPLICATION, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress
28	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap	28	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
29	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap	29	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
30	[ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks	30	[ ASN_APPLICATION, SNMP_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
31	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist	31	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
32	[	32	[
33	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair	33	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
34	[	34	[
35	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],	35	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],
…		…
62	) {	62	) {
63	... and so on	63	... and so on
64		64
65	# finally, let's encode it again and hope it results in the same bit pattern	65	# finally, let's encode it again and hope it results in the same bit pattern
66		66
67	my $buf = ber_encode $ber;	67	my $buf = ber_encode $ber, $Convert::BER::XS::SNMP_PROFILE;
68		68
69	=head1 DESCRIPTION	69	=head1 DESCRIPTION
70		70
71	WARNING: Before release 1.0, the API is not considered stable in any way.	71	WARNING: Before release 1.0, the API is not considered stable in any way.
72		72
73	This module implements a I<very> low level BER/DER en-/decoder.	73	This module implements a I<very> low level BER/DER en-/decoder.
74		74
75	If is tuned for low memory and high speed, while still maintaining some	75	It is tuned for low memory and high speed, while still maintaining some
76	level of user-friendlyness.	76	level of user-friendlyness.
		77
		78	=head2 EXPORT TAGS AND CONSTANTS
		79
		80	By default this module doesn't export any symbols, but if you don't want
		81	to break your keyboard, editor or eyesight with extremely long names, I
		82	recommend importing the C<:all> tag. Still, you can selectively import
		83	things.
		84
		85	=over
		86
		87	=item C<:all>
		88
		89	All of the below. Really. Recommended for at least first steps, or if you
		90	don't care about a few kilobytes of wasted memory (and namespace).
		91
		92	=item C<:const>
		93
		94	All of the strictly ASN.1-related constants defined by this module, the
		95	same as C<:const_asn :const_index>. Notably, this does not contain
		96	C<:const_ber_type> and C<:const_snmp>.
		97
		98	A good set to get everything you need to decode and match BER data would be
		99	C<:decode :const>.
		100
		101	=item C<:const_index>
		102
		103	The BER tuple array index constants:
		104
		105	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
		106
		107	=item C<:const_asn>
		108
		109	ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
		110	exactly thw two topmost bits from the identifier octet shifted 6 bits to
		111	the right):
		112
		113	ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
		114
		115	ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
		116	numerical value corresponds exactly to the numbers used in BER/X.690.
		117
		118	ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
		119	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
		120	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
		122	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
		124
		125	=item C<:const_ber_type>
		126
		127	The BER type constants, explained in the PROFILES section.
		128
		129	BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
		130	BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
		131	BER_TYPE_IPADDRESS BER_TYPE_CROAK
		132
		133	=item C<:const_snmp>
		134
		135	Constants only relevant to SNMP. These are the tag values used by SNMP in
		136	the C<ASN_APPLICATION> namespace and have the exact numerical value as in
		137	BER/RFC 2578.
		138
		139	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
		140
		141	=item C<:decode>
		142
		143	C<ber_decode> and the match helper functions:
		144
		145	ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid
		146
		147	=item C<:encode>
		148
		149	C<ber_encode> and the construction helper functions:
		150
		151	ber_encode ber_i32
		152
		153	=back
77		154
78	=head2 ASN.1/BER/DER/... BASICS	155	=head2 ASN.1/BER/DER/... BASICS
79		156
80	ASN.1 is a strange language that can be used to describe protocols and	157	ASN.1 is a strange language that can be used to describe protocols and
81	data structures. It supports various mappings to JSON, XML, but most	158	data structures. It supports various mappings to JSON, XML, but most
…		…
92	and also have a flag that says whether a value consists of subvalues (is	169	and also have a flag that says whether a value consists of subvalues (is
93	"constructed") or not (is "primitive").	170	"constructed") or not (is "primitive").
94		171
95	Tags are simple integers, and ASN.1 defines a somewhat weird assortment of	172	Tags are simple integers, and ASN.1 defines a somewhat weird assortment of
96	those - for example, you have 32 bit signed integers and 16(!) different	173	those - for example, you have 32 bit signed integers and 16(!) different
97	string types, but there is no unsigned32 type for example. Different	174	string types, but there is no Unsigned32 type for example. Different
98	applications work around this in different ways, for example, SNMP defines	175	applications work around this in different ways, for example, SNMP defines
99	application-specific Gauge32, Counter32 and Unsigned32, which are mapped	176	application-specific Gauge32, Counter32 and Unsigned32, which are mapped
100	to two different tags: you can distinguish between Counter32 and the	177	to two different tags: you can distinguish between Counter32 and the
101	others, but not between Gause32 and Unsigned32, without the ASN.1 schema.	178	others, but not between Gause32 and Unsigned32, without the ASN.1 schema.
102		179
…		…
106		183
107	This module represents every BER value as a 4-element tuple (actually an	184	This module represents every BER value as a 4-element tuple (actually an
108	array-reference):	185	array-reference):
109		186
110	[CLASS, TAG, CONSTRUCTED, DATA]	187	[CLASS, TAG, CONSTRUCTED, DATA]
		188
		189	For example:
		190
		191	[ASN_UNIVERSAL, ASN_INTEGER32, 0, 177] # the integer 177
		192	[ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"
		193	[ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID
		194	[ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequencE
111		195
112	To avoid non-descriptive hardcoded array index numbers, this module	196	To avoid non-descriptive hardcoded array index numbers, this module
113	defines symbolic constants to access these members: C<BER_CLASS>,	197	defines symbolic constants to access these members: C<BER_CLASS>,
114	C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.	198	C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.
115		199
…		…
289	use Exporter qw(import);	373	use Exporter qw(import);
290		374
291	our $VERSION;	375	our $VERSION;
292		376
293	BEGIN {	377	BEGIN {
294	$VERSION = 0.7;	378	$VERSION = 0.8;
295	XSLoader::load __PACKAGE__, $VERSION;	379	XSLoader::load __PACKAGE__, $VERSION;
296	}	380	}
297		381
298	our %EXPORT_TAGS = (	382	our %EXPORT_TAGS = (
299	const => [qw(	383	const_index => [qw(
300	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA	384	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
301		385	)],
		386	const_asn => [qw(
302	ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER	387	ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
303	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED	388	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
304	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING	389	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
305	ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING	390	ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
306	ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING	391	ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
307	ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING	392	ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
308		393
309	ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE	394	ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
310		395	)],
		396	const_ber_type => [qw(
311	BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT	397	BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
312	BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL	398	BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
313	BER_TYPE_IPADDRESS BER_TYPE_CROAK	399	BER_TYPE_IPADDRESS BER_TYPE_CROAK
314	)],	400	)],
315	const_snmp => [qw(	401	const_snmp => [qw(
316	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64	402	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
317	)],	403	)],
318	encode => [qw(	404	decode => [qw(
319	ber_decode	405	ber_decode
320	ber_is ber_is_seq ber_is_i32 ber_is_oid	406	ber_is ber_is_seq ber_is_i32 ber_is_oid
321	)],	407	)],
322	decode => [qw(	408	encode => [qw(
323	ber_encode	409	ber_encode
324	ber_i32	410	ber_i32
325	)],	411	)],
326	);	412	);
327		413
328	our @EXPORT_OK = map @$_, values %EXPORT_TAGS;	414	our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
329		415
330	$EXPORT_TAGS{all} = \@EXPORT_OK;	416	$EXPORT_TAGS{all} = \@EXPORT_OK;
		417	$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
		418	use Data::Dump; ddx \%EXPORT_TAGS;
331		419
332	=head1 PROFILES	420	=head1 PROFILES
333		421
334	While any BER data can be correctly encoded and decoded out of the box, it	422	While any BER data can be correctly encoded and decoded out of the box, it
335	can be inconvenient to have to manually decode some values into a "better"	423	can be inconvenient to have to manually decode some values into a "better"
…		…
480	=cut	568	=cut
481		569
482	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;	570	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
483	our $SNMP_PROFILE = new Convert::BER::XS::Profile;	571	our $SNMP_PROFILE = new Convert::BER::XS::Profile;
484		572
		573	# additional SNMP application types
485	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);	574	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
486	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);	575	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
487	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);	576	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
488	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);	577	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
489	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);	578	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
…		…
491		580
492	$DEFAULT_PROFILE->_set_default;	581	$DEFAULT_PROFILE->_set_default;
493		582
494	1;	583	1;
495		584
496	=head2 LIMITATIONS	585	=head2 LIMITATIONS/NOTES
497		586
498	This module can only en-/decode 64 bit signed and unsigned integers, and	587	This module can only en-/decode 64 bit signed and unsigned integers, and
499	only when your perl supports those.	588	only when your perl supports those.
500		589
		590	This module does not generally care about ranges, i.e. it will happily
		591	de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative
		592	number into an C<SNMP_COUNTER64>.
		593
501	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is	594	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
502	much larger than e.g. the one imposed by SNMP or other protocols.	595	much larger than e.g. the one imposed by SNMP or other protocols,a nd is
		596	about 4kB.
503		597
504	REAL values are not supported and will croak.	598	REAL values are not supported and will currently croak.
505		599
506	This module has undergone little to no testing so far.	600	This module has undergone little to no testing so far.
507		601
508	=head2 ITHREADS SUPPORT	602	=head2 ITHREADS SUPPORT
509		603

Diff Legend

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

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.17 by root, Sat Apr 20 13:46:14 2019 UTC vs. Revision 1.23 by root, Sat Apr 20 14:53:29 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.17 by root, Sat Apr 20 13:46:14 2019 UTC vs.
Revision 1.23 by root, Sat Apr 20 14:53:29 2019 UTC