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

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.4 by root, Fri Apr 19 19:46:29 2019 UTC vs.
Revision 1.9 by root, Fri Apr 19 20:43:12 2019 UTC

…		…
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
10	or die "unable to decode SNMP v1/v2c Message";	10	or die "unable to decode SNMP message";
11		11
12	# the above results in a data structure consisting of (class, tag,	12	# The above results in a data structure consisting of (class, tag,
13	# constructed, data) tuples. here is such a message, SNMPv1 trap	13	# constructed, data) tuples. Below is such a message, SNMPv1 trap
14	# with a cisoc mac change notification	14	# with a Cisco mac change notification.
		15	# Did you know that Cisco is in the news almost every week because
		16	# of some backdoor password or other extremely stupid security bug?
15		17
16	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1,	18	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1,
17	[	19	[
18	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1	20	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 0 ], # snmp version 1
19	[ ASN_UNIVERSAL, 4, 0, "public" ], # community	21	[ ASN_UNIVERSAL, 4, 0, "public" ], # community
20	[ ASN_CONTEXT, 4, 1, # CHOICE, constructed	22	[ ASN_CONTEXT, 4, 1, # CHOICE, constructed - trap PDU
21	[	23	[
22	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.2" ], # enterprise oid	24	[ 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	25	[ ASN_APPLICATION, 0, 0, "\x0a\x00\x00\x01" ], # SNMP IpAddress, 10.0.0.1
24	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap	26	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 6 ], # generic trap
25	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap	27	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap
26	[ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks	28	[ ASN_APPLICATION, ASN_TIMETICKS, 0, 1817903850 ], # SNMP TimeTicks
27	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist	29	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # the varbindlist
28	[	30	[
29	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair	31	[ ASN_UNIVERSAL, ASN_SEQUENCE, 1, # a single varbind, "key value" pair
30	[	32	[
31	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ], # the oid	33	[ ASN_UNIVERSAL, ASN_OBJECT_IDENTIFIER, 0, "1.3.6.1.4.1.9.9.215.1.1.8.1.2.1" ],
32	[ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value	34	[ ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "...data..." # the value
33	]	35	]
34	]	36	]
35	],	37	],
36	...	38	...
…		…
62		64
63	my $buf = ber_encode $ber;	65	my $buf = ber_encode $ber;
64		66
65	=head1 DESCRIPTION	67	=head1 DESCRIPTION
66		68
		69	WARNING: Before release 1.0, the API is not considered stable in any way.
		70
67	This module implements a I<very> low level BER/DER en-/decoder.	71	This module implements a I<very> low level BER/DER en-/decoder.
68		72
69	If is tuned for low memory and high speed, while still maintaining some	73	If is tuned for low memory and high speed, while still maintaining some
70	level of user-friendlyness.	74	level of user-friendlyness.
71		75
…		…
104	This module represents every BER value as a 4-element tuple (actually an	108	This module represents every BER value as a 4-element tuple (actually an
105	array-reference):	109	array-reference):
106		110
107	[CLASS, TAG, CONSTRUCTED, DATA]	111	[CLASS, TAG, CONSTRUCTED, DATA]
108		112
		113	To avoid non-descriptive hardcoded array index numbers, this module
		114	defines symbolic constants to access these members: C<BER_CLASS>,
		115	C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.
		116
		117	Also, the first three members are integers with a little caveat: for
		118	performance reasons, these are readonly and shared, so you must not modify
		119	them (increment, assign to them etc.) in any way. You may modify the
		120	I<DATA> member, and you may re-assign the array itself, e.g.:
		121
		122	$ber = ber_decode $binbuf;
		123
		124	# the following is NOT legal:
		125	$ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, class/tag/constructed are readonly(!)
		126
		127	# but all of the following are fine:
		128	$ber->[BER_DATA] = "string";
		129	$ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123];
		130	@$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 1000);
		131
109	I<CLASS> is something like a namespace for I<TAG>s - there is the	132	I<CLASS> is something like a namespace for I<TAG>s - there is the
110	C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1	133	C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
111	implementations, the C<ASN_APPLICATION> namespace which defines tags for	134	implementations, the C<ASN_APPLICATION> namespace which defines tags for
112	specific applications (for example, the SNMP C<Unsigned32> type is in this	135	specific applications (for example, the SNMP C<Unsigned32> type is in this
113	namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.	136	namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
…		…
143	Thus, you can always decode a BER data structure and at worst you get a	166	Thus, you can always decode a BER data structure and at worst you get a
144	string in place of some nice decoded value.	167	string in place of some nice decoded value.
145		168
146	See the SYNOPSIS for an example of such an encoded tuple representation.	169	See the SYNOPSIS for an example of such an encoded tuple representation.
147		170
		171	=head2 DECODING AND ENCODING
		172
		173	=over
		174
		175	=item $tuple = ber_decoded $bindata
		176
		177	Decodes binary BER data in C<$bindata> and returns the resulting BER
		178	tuple. Croaks on any decoding error, so the returned C<$tuple> is always
		179	valid.
		180
		181	=item $bindata = ber_encode $tuple
		182
		183	Encodes the BER tuple into a BER/DER data structure.
		184
		185	=back
		186
		187	=head2 HELPER FUNCTIONS
		188
		189	Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
		190	annoying. To reduce this a bit, this module defines a number of helper
		191	functions, both to match BER tuples and to conmstruct BER tuples:
		192
		193	=head3 MATCH HELPERS
		194
		195	Thse functions accept a BER tuple as first argument and either paertially
		196	or fully match it. They often come in two forms, one which exactly matches
		197	a value, and one which only matches the type and returns the value.
		198
		199	They do check whether valid tuples are passed in and croak otherwise. As
		200	a ease-of-use exception, they usually also accept C<undef> instead of a
		201	tuple reference. in which case they silently fail to match.
		202
		203	=over
		204
		205	=item $bool = ber_is $tuple, $class, $tag, $constructed, $data
		206
		207	This takes a BER C<$tuple> and matches its elements agains the privded
		208	values, all of which are optional - values that are either missing or
		209	C<undef> will be ignored, the others will be matched exactly (e.g. as if
		210	you used C<==> or C<eq> (for C<$data>)).
		211
		212	Some examples:
		213
		214	ber_is $tuple, ASN_UNIVERSAL, ASN_SEQUENCE, 1
		215	orf die "tuple is not an ASN SEQUENCE";
		216
		217	ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
		218	or die "tuple is not an ASN NULL value";
		219
		220	ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50
		221	or die "BER integer must be 50";
		222
		223	=item $seq = ber_is_seq $tuple
		224
		225	Returns the sequence members (the array of subvalues) if the C<$tuple> is
		226	an ASN SEQUENCE, i.e. the C<BER_DATA> member. If the C<$tuple> is not a
		227	sequence it returns C<undef>. For example, SNMP version 1/2c/3 packets all
		228	consist of an outer SEQUENCE value:
		229
		230	my $ber = ber_decode $snmp_data;
		231
		232	my $snmp = ber_is_seq $ber
		233	or die "SNMP packet invalid: does not start with SEQUENCE";
		234
		235	# now we know $snmp is a sequence, so decode the SNMP version
		236
		237	my $version = ber_is_i32 $snmp->[0]
		238	or die "SNMP packet invalid: does not start with version number";
		239
		240	=item $bool = ber_is_i32 $tuple, $i32
		241
		242	Returns a true value if the C<$tuple> represents an ASN INTEGER32 with
		243	the value C<$i32>.
		244
		245	=item $i32 = ber_is_i32 $tuple
		246
		247	Returns true (and extracts the integer value) if the C<$tuple> is an ASN
		248	INTEGER32. For C<0>, this function returns a special value that is 0 but
		249	true.
		250
		251	=item $bool = ber_is_oid $tuple, $oid_string
		252
		253	Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
		254	that exactly matches C$oid_string>. Exmaple:
		255
		256	ber_is_oid $tuple, "1.3.6.1.4"
		257	or die "oid must be 1.3.6.1.4";
		258
		259	=item $oid = ber_is_oid $tuple
		260
		261	Returns true (and extracts the OID string) if the C<$tuple> is an ASN
		262	OBJECT IDENTIFIER. Otherwise, it returns C<undef>.
		263
		264	=back
		265
		266	=head3 CONSTRUCTION HELPERS
		267
		268	=over
		269
		270	=item $tuple = ber_i32 $value
		271
		272	Constructs a new C<ASN_INTEGER32> tuple.
		273
		274	=back
		275
148	=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>	276	=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
149		277
150	This module is I<not> the XS version of L<Convert::BER>, but a different	278	This module is I<not> the XS version of L<Convert::BER>, but a different
151	take at doing the same thing. I imagine this module would be a good base	279	take at doing the same thing. I imagine this module would be a good base
152	for speeding up either of these, or write a similar module, or write your	280	for speeding up either of these, or write a similar module, or write your
…		…
159	use common::sense;	287	use common::sense;
160		288
161	use XSLoader ();	289	use XSLoader ();
162	use Exporter qw(import);	290	use Exporter qw(import);
163		291
164	our $VERSION = '0.0';	292	our $VERSION = 0.2;
165		293
166	XSLoader::load __PACKAGE__, $VERSION;	294	XSLoader::load __PACKAGE__, $VERSION;
167		295
168	our %EXPORT_TAGS = (	296	our %EXPORT_TAGS = (
169	const => [qw(	297	const => [qw(

Diff Legend

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

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.4 by root, Fri Apr 19 19:46:29 2019 UTC vs. Revision 1.9 by root, Fri Apr 19 20:43:12 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.4 by root, Fri Apr 19 19:46:29 2019 UTC vs.
Revision 1.9 by root, Fri Apr 19 20:43:12 2019 UTC