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

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.26 by root, Sat Apr 20 15:23:55 2019 UTC vs.
Revision 1.33 by root, Sat Apr 20 17:23:21 2019 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, # constructed, 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?
…		…
100		100
101	=item C<:const_index>	101	=item C<:const_index>
102		102
103	The BER tuple array index constants:	103	The BER tuple array index constants:
104		104
105	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA	105	BER_CLASS BER_TAG BER_FLAGS BER_DATA
106		106
107	=item C<:const_asn>	107	=item C<:const_asn>
108		108
109	ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -	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	110	exactly thw two topmost bits from the identifier octet shifted 6 bits to
…		…
134		134
135	Constants only relevant to SNMP. These are the tag values used by SNMP in	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	136	the C<ASN_APPLICATION> namespace and have the exact numerical value as in
137	BER/RFC 2578.	137	BER/RFC 2578.
138		138
139	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64	139	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_GAUGE32
		140	SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
140		141
141	=item C<:decode>	142	=item C<:decode>
142		143
143	C<ber_decode> and the match helper functions:	144	C<ber_decode> and the match helper functions:
144		145
…		…
155	=head2 ASN.1/BER/DER/... BASICS	156	=head2 ASN.1/BER/DER/... BASICS
156		157
157	ASN.1 is a strange language that can be used to describe protocols and	158	ASN.1 is a strange language that can be used to describe protocols and
158	data structures. It supports various mappings to JSON, XML, but most	159	data structures. It supports various mappings to JSON, XML, but most
159	importantly, to a various binary encodings such as BER, that is the topic	160	importantly, to a various binary encodings such as BER, that is the topic
160	of this module, and is used in SNMP or LDAP for example.	161	of this module, and is used in SNMP, LDAP or X.509 for example.
161		162
162	While ASN.1 defines a schema that is useful to interpret encoded data,	163	While ASN.1 defines a schema that is useful to interpret encoded data,
163	the BER encoding is actually somewhat self-describing: you might not know	164	the BER encoding is actually somewhat self-describing: you might not know
164	whether something is a string or a number or a sequence or something else,	165	whether something is a string or a number or a sequence or something else,
165	but you can nevertheless decode the overall structure, even if you end up	166	but you can nevertheless decode the overall structure, even if you end up
…		…
182	=head2 DECODED BER REPRESENTATION	183	=head2 DECODED BER REPRESENTATION
183		184
184	This module represents every BER value as a 4-element tuple (actually an	185	This module represents every BER value as a 4-element tuple (actually an
185	array-reference):	186	array-reference):
186		187
187	[CLASS, TAG, CONSTRUCTED, DATA]	188	[CLASS, TAG, FLAGS, DATA]
188		189
189	For example:	190	For example:
190		191
191	[ASN_UNIVERSAL, ASN_INTEGER, 0, 177] # the integer 177	192	[ASN_UNIVERSAL, ASN_INTEGER, 0, 177] # the integer 177
192	[ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"	193	[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_OID, 0, "1.3.6.133"] # some OID
194	[ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence	195	[ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence
195		196
196	To avoid non-descriptive hardcoded array index numbers, this module	197	To avoid non-descriptive hardcoded array index numbers, this module
197	defines symbolic constants to access these members: C<BER_CLASS>,	198	defines symbolic constants to access these members: C<BER_CLASS>,
198	C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.	199	C<BER_TAG>, C<BER_FLAGS> and C<BER_DATA>.
199		200
200	Also, the first three members are integers with a little caveat: for	201	Also, the first three members are integers with a little caveat: for
201	performance reasons, these are readonly and shared, so you must not modify	202	performance reasons, these are readonly and shared, so you must not modify
202	them (increment, assign to them etc.) in any way. You may modify the	203	them (increment, assign to them etc.) in any way. You may modify the
203	I<DATA> member, and you may re-assign the array itself, e.g.:	204	I<DATA> member, and you may re-assign the array itself, e.g.:
204		205
205	$ber = ber_decode $binbuf;	206	$ber = ber_decode $binbuf;
206		207
207	# the following is NOT legal:	208	# the following is NOT legal:
208	$ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)	209	$ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/FLAGS are READ ONLY(!)
209		210
210	# but all of the following are fine:	211	# but all of the following are fine:
211	$ber->[BER_DATA] = "string";	212	$ber->[BER_DATA] = "string";
212	$ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];	213	$ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];
213	@$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);	214	@$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
…		…
231		232
232	The most common tags in SNMP's C<ASN_APPLICATION> namespace are	233	The most common tags in SNMP's C<ASN_APPLICATION> namespace are
233	C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and	234	C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
234	C<SNMP_COUNTER64>.	235	C<SNMP_COUNTER64>.
235		236
236	The I<CONSTRUCTED> flag is really just a boolean - if it is false,	237	The I<FLAGS> value is really just a boolean at this time (but might
237	the value is "primitive" and contains no subvalues, kind of like a	238	get extended) - if it is C<0>, the value is "primitive" and contains
238	non-reference perl scalar. If it is true, then the value is "constructed"	239	no subvalues, kind of like a non-reference perl scalar. If it is C<1>,
239	which just means it contains a list of subvalues which this module will	240	then the value is "constructed" which just means it contains a list of
240	en-/decode as BER tuples themselves.	241	subvalues which this module will en-/decode as BER tuples themselves.
241		242
242	The I<DATA> value is either a reference to an array of further tuples (if	243	The I<DATA> value is either a reference to an array of further tuples
243	the value is I<CONSTRUCTED>), some decoded representation of the value,	244	(if the value is I<FLAGS>), some decoded representation of the value, if
244	if this module knows how to decode it (e.g. for the integer types above)	245	this module knows how to decode it (e.g. for the integer types above) or
245	or a binary string with the raw octets if this module doesn't know how to	246	a binary string with the raw octets if this module doesn't know how to
246	interpret the namespace/tag.	247	interpret the namespace/tag.
247		248
248	Thus, you can always decode a BER data structure and at worst you get a	249	Thus, you can always decode a BER data structure and at worst you get a
249	string in place of some nice decoded value.	250	string in place of some nice decoded value.
250		251
…		…
280	=item $bindata = ber_encode $tuple[, $profile]	281	=item $bindata = ber_encode $tuple[, $profile]
281		282
282	Encodes the BER tuple into a BER/DER data structure. AS with	283	Encodes the BER tuple into a BER/DER data structure. AS with
283	Cyber_decode>, an optional profile can be given.	284	Cyber_decode>, an optional profile can be given.
284		285
		286	The encoded data should be both BER and DER ("shortest form") compliant
		287	unless the input says otherwise (e.g. it uses constructed strings).
		288
285	=back	289	=back
286		290
287	=head2 HELPER FUNCTIONS	291	=head2 HELPER FUNCTIONS
288		292
289	Working with a 4-tuple for every value can be annoying. Or, rather, I<is>	293	Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
…		…
300	a ease-of-use exception, they usually also accept C<undef> instead of a	304	a ease-of-use exception, they usually also accept C<undef> instead of a
301	tuple reference, in which case they silently fail to match.	305	tuple reference, in which case they silently fail to match.
302		306
303	=over	307	=over
304		308
305	=item $bool = ber_is $tuple, $class, $tag, $constructed, $data	309	=item $bool = ber_is $tuple, $class, $tag, $flags, $data
306		310
307	This takes a BER C<$tuple> and matches its elements against the provided	311	This takes a BER C<$tuple> and matches its elements against the provided
308	values, all of which are optional - values that are either missing or	312	values, all of which are optional - values that are either missing or
309	C<undef> will be ignored, the others will be matched exactly (e.g. as if	313	C<undef> will be ignored, the others will be matched exactly (e.g. as if
310	you used C<==> or C<eq> (for C<$data>)).	314	you used C<==> or C<eq> (for C<$data>)).
…		…
390	use Exporter qw(import);	394	use Exporter qw(import);
391		395
392	our $VERSION;	396	our $VERSION;
393		397
394	BEGIN {	398	BEGIN {
395	$VERSION = 0.8;	399	$VERSION = 0.9;
396	XSLoader::load __PACKAGE__, $VERSION;	400	XSLoader::load __PACKAGE__, $VERSION;
397	}	401	}
398		402
399	our %EXPORT_TAGS = (	403	our %EXPORT_TAGS = (
400	const_index => [qw(	404	const_index => [qw(
401	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA	405	BER_CLASS BER_TAG BER_FLAGS BER_DATA
402	)],	406	)],
403	const_asn => [qw(	407	const_asn => [qw(
404	ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER	408	ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
405	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED	409	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
406	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING	410	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
…		…
414	BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT	418	BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
415	BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL	419	BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
416	BER_TYPE_IPADDRESS BER_TYPE_CROAK	420	BER_TYPE_IPADDRESS BER_TYPE_CROAK
417	)],	421	)],
418	const_snmp => [qw(	422	const_snmp => [qw(
419	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64	423	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_GAUGE32 SNMP_UNSIGNED32
		424	SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
420	)],	425	)],
421	decode => [qw(	426	decode => [qw(
422	ber_decode	427	ber_decode
423	ber_is ber_is_seq ber_is_int ber_is_oid	428	ber_is ber_is_seq ber_is_int ber_is_oid
424	)],	429	)],
…		…
579	C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard	584	C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard
580	error for some types, then C<BER_TYPE_CROAK> is for you.	585	error for some types, then C<BER_TYPE_CROAK> is for you.
581		586
582	=back	587	=back
583		588
		589	=head2 Example Profile
		590
		591	The following creates a profile suitable for SNMP - it's exactly identical
		592	to the C<$Convert::BER::XS::SNMP_PROFILE> profile.
		593
		594	our $SNMP_PROFILE = new Convert::BER::XS::Profile;
		595
		596	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
		597	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
		598	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
		599	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
		600	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
		601	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
		602
584	=cut	603	=cut
585		604
586	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;	605	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
587	our $SNMP_PROFILE = new Convert::BER::XS::Profile;	606
		607	$DEFAULT_PROFILE->_set_default;
588		608
589	# additional SNMP application types	609	# additional SNMP application types
		610	our $SNMP_PROFILE = new Convert::BER::XS::Profile;
		611
590	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);	612	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
591	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);	613	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
592	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);	614	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
593	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);	615	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
594	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);	616	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
595	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);	617	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
596		618
597	$DEFAULT_PROFILE->_set_default;
598
599	1;	619	1;
600		620
601	=head2 LIMITATIONS/NOTES	621	=head2 LIMITATIONS/NOTES
602		622
603	This module can only en-/decode 64 bit signed and unsigned integers, and	623	This module can only en-/decode 64 bit signed and unsigned integers, and
…		…
609		629
610	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is	630	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
611	much larger than e.g. the one imposed by SNMP or other protocols,a nd is	631	much larger than e.g. the one imposed by SNMP or other protocols,a nd is
612	about 4kB.	632	about 4kB.
613		633
		634	Indefinite length encoding is not supported.
		635
		636	Constructed strings are decoded just fine, but there should be a way to
		637	join them for convenience.
		638
614	REAL values are not supported and will currently croak.	639	REAL values are not supported and will currently croak.
		640
		641	The encoder and decoder tend to accept more formats than should be
		642	strictly supported.
615		643
616	This module has undergone little to no testing so far.	644	This module has undergone little to no testing so far.
617		645
618	=head2 ITHREADS SUPPORT	646	=head2 ITHREADS SUPPORT
619		647

Diff Legend

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

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.26 by root, Sat Apr 20 15:23:55 2019 UTC vs. Revision 1.33 by root, Sat Apr 20 17:23:21 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.26 by root, Sat Apr 20 15:23:55 2019 UTC vs.
Revision 1.33 by root, Sat Apr 20 17:23:21 2019 UTC