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

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.20 by root, Sat Apr 20 14:47:23 2019 UTC vs.
Revision 1.31 by root, Sat Apr 20 15:49:04 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?
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_INTEGER, 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, SNMP_IPADDRESS, 0, "10.0.0.1" ], # SNMP IpAddress	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_INTEGER, 0, 6 ], # generic trap
29	[ ASN_UNIVERSAL, ASN_INTEGER32, 0, 1 ], # specific trap	29	[ ASN_UNIVERSAL, ASN_INTEGER, 0, 1 ], # specific trap
30	[ ASN_APPLICATION, SNMP_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	[
…		…
42	# let's decode it a bit with some helper functions	42	# let's decode it a bit with some helper functions
43		43
44	my $msg = ber_is_seq $ber	44	my $msg = ber_is_seq $ber
45	or die "SNMP message does not start with a sequence";	45	or die "SNMP message does not start with a sequence";
46		46
47	ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER32, 0	47	ber_is $msg->[0], ASN_UNIVERSAL, ASN_INTEGER, 0
48	or die "SNMP message does not start with snmp version\n";	48	or die "SNMP message does not start with snmp version\n";
49		49
50	# message is SNMP v1 or v2c?	50	# message is SNMP v1 or v2c?
51	if ($msg->[0][BER_DATA] == 0 \|\| $msg->[0][BER_DATA] == 1) {	51	if ($msg->[0][BER_DATA] == 0 \|\| $msg->[0][BER_DATA] == 1) {
52		52
…		…
55	my $trap = $msg->[2][BER_DATA];	55	my $trap = $msg->[2][BER_DATA];
56		56
57	# check whether trap is a cisco mac notification mac changed message	57	# check whether trap is a cisco mac notification mac changed message
58	if (	58	if (
59	(ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects	59	(ber_is_oid $trap->[0], "1.3.6.1.4.1.9.9.215.2") # cmnInterfaceObjects
60	and (ber_is_i32 $trap->[2], 6)	60	and (ber_is_int $trap->[2], 6)
61	and (ber_is_i32 $trap->[3], 1) # mac changed msg	61	and (ber_is_int $trap->[3], 1) # mac changed msg
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
…		…
76	level of user-friendlyness.	76	level of user-friendlyness.
77		77
78	=head2 EXPORT TAGS AND CONSTANTS	78	=head2 EXPORT TAGS AND CONSTANTS
79		79
80	By default this module doesn't export any symbols, but if you don't want	80	By default this module doesn't export any symbols, but if you don't want
81	to break your keyboard, editor or eyesigh with extreemly long names, I	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	82	recommend importing the C<:all> tag. Still, you can selectively import
83	things:	83	things.
84		84
85	=over	85	=over
86		86
87	=item :all	87	=item C<:all>
88		88
89	All of the below. Really. Rcommended for at least first steps, or if you	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).	90	don't care about a few kilobytes of wasted memory (and namespace).
91		91
92	=item :const	92	=item C<:const>
93		93
94	All of the stricly ASN.1-related constants defined by this module, the	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	95	same as C<:const_asn :const_index>. Notably, this does not contain
96	C<:const_ber_type> and C<:const_snmp>.	96	C<:const_ber_type> and C<:const_snmp>.
97		97
98	A good set to get everything you need to decode and match BER data would be	98	A good set to get everything you need to decode and match BER data would be
99	C<:decode :const>.	99	C<:decode :const>.
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>, reespectively -	109	ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
110	exactly thw two topmost bits from the identifdier octet shifted 6 bits to	110	exactly thw two topmost bits from the identifier octet shifted 6 bits to
111	the right):	111	the right):
112		112
113	ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE	113	ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
114		114
115	ASN tag values (some of which are aliases, such as C<ASN_OID>). Their	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.	116	numerical value corresponds exactly to the numbers used in BER/X.690.
117		117
118	ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER	118	ASN_BOOLEAN ASN_INTEGER 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	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	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	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	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	123	ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
…		…
140		140
141	=item C<:decode>	141	=item C<:decode>
142		142
143	C<ber_decode> and the match helper functions:	143	C<ber_decode> and the match helper functions:
144		144
145	ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid	145	ber_decode ber_is ber_is_seq ber_is_int ber_is_oid
146		146
147	=item C<:encode>	147	=item C<:encode>
148		148
149	C<ber_encode> and the construction helper functions:	149	C<ber_encode> and the construction helper functions:
150		150
151	ber_encode ber_i32	151	ber_encode ber_int
152		152
153	=back	153	=back
154		154
155	=head2 ASN.1/BER/DER/... BASICS	155	=head2 ASN.1/BER/DER/... BASICS
156		156
157	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
158	data structures. It supports various mappings to JSON, XML, but most	158	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	159	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.	160	of this module, and is used in SNMP, LDAP or X.509 for example.
161		161
162	While ASN.1 defines a schema that is useful to interpret encoded data,	162	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	163	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,	164	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	165	but you can nevertheless decode the overall structure, even if you end up
…		…
167		167
168	This works because BER values are tagged with a type and a namespace,	168	This works because BER values are tagged with a type and a namespace,
169	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
170	"constructed") or not (is "primitive").	170	"constructed") or not (is "primitive").
171		171
172	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
173	those - for example, you have 32 bit signed integers and 16(!) different	173	of those - for example, you have one integers and 16(!) different
174	string types, but there is no unsigned32 type for example. Different	174	string types, but there is no Unsigned32 type for example. Different
175	applications work around this in different ways, for example, SNMP defines	175	applications work around this in different ways, for example, SNMP defines
176	application-specific Gauge32, Counter32 and Unsigned32, which are mapped	176	application-specific Gauge32, Counter32 and Unsigned32, which are mapped
177	to two different tags: you can distinguish between Counter32 and the	177	to two different tags: you can distinguish between Counter32 and the
178	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.
179		179
…		…
182	=head2 DECODED BER REPRESENTATION	182	=head2 DECODED BER REPRESENTATION
183		183
184	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
185	array-reference):	185	array-reference):
186		186
187	[CLASS, TAG, CONSTRUCTED, DATA]	187	[CLASS, TAG, FLAGS, DATA]
		188
		189	For example:
		190
		191	[ASN_UNIVERSAL, ASN_INTEGER, 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
188		195
189	To avoid non-descriptive hardcoded array index numbers, this module	196	To avoid non-descriptive hardcoded array index numbers, this module
190	defines symbolic constants to access these members: C<BER_CLASS>,	197	defines symbolic constants to access these members: C<BER_CLASS>,
191	C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>.	198	C<BER_TAG>, C<BER_FLAGS> and C<BER_DATA>.
192		199
193	Also, the first three members are integers with a little caveat: for	200	Also, the first three members are integers with a little caveat: for
194	performance reasons, these are readonly and shared, so you must not modify	201	performance reasons, these are readonly and shared, so you must not modify
195	them (increment, assign to them etc.) in any way. You may modify the	202	them (increment, assign to them etc.) in any way. You may modify the
196	I<DATA> member, and you may re-assign the array itself, e.g.:	203	I<DATA> member, and you may re-assign the array itself, e.g.:
197		204
198	$ber = ber_decode $binbuf;	205	$ber = ber_decode $binbuf;
199		206
200	# the following is NOT legal:	207	# the following is NOT legal:
201	$ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)	208	$ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/FLAGS are READ ONLY(!)
202		209
203	# but all of the following are fine:	210	# but all of the following are fine:
204	$ber->[BER_DATA] = "string";	211	$ber->[BER_DATA] = "string";
205	$ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123];	212	$ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];
206	@$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);	213	@$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
207		214
208	I<CLASS> is something like a namespace for I<TAG>s - there is the	215	I<CLASS> is something like a namespace for I<TAG>s - there is the
209	C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1	216	C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
210	implementations, the C<ASN_APPLICATION> namespace which defines tags for	217	implementations, the C<ASN_APPLICATION> namespace which defines tags for
211	specific applications (for example, the SNMP C<Unsigned32> type is in this	218	specific applications (for example, the SNMP C<Unsigned32> type is in this
212	namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.	219	namespace), a special-purpose context namespace (C<ASN_CONTEXT>, used e.g.
213	for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>).	220	for C<CHOICE>) and a private namespace (C<ASN_PRIVATE>).
214		221
215	The meaning of the I<TAG> depends on the namespace, and defines a	222	The meaning of the I<TAG> depends on the namespace, and defines a
216	(partial) interpretation of the data value. For example, right now, SNMP	223	(partial) interpretation of the data value. For example, SNMP defines
217	application namespace knowledge ix hardcoded into this module, so it	224	extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
218	knows that SNMP C<Unsigned32> values need to be decoded into actual perl	225	of these, you need to tell this module how to handle those via profiles.
219	integers.
220		226
221	The most common tags in the C<ASN_UNIVERSAL> namespace are	227	The most common tags in the C<ASN_UNIVERSAL> namespace are
222	C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,	228	C<ASN_INTEGER>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
223	C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and	229	C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
224	C<ASN_IA5_STRING>.	230	C<ASN_IA5_STRING>.
225		231
226	The most common tags in SNMP's C<ASN_APPLICATION> namespace	232	The most common tags in SNMP's C<ASN_APPLICATION> namespace are
227	are C<SNMP_IPADDRESS>, C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>,	233	C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
228	C<SNMP_TIMETICKS>, C<SNMP_OPAQUE> and C<SNMP_COUNTER64>.	234	C<SNMP_COUNTER64>.
229		235
230	The I<CONSTRUCTED> flag is really just a boolean - if it is false, the	236	The I<FLAGS> value is really just a boolean at this time (but might
231	the value is "primitive" and contains no subvalues, kind of like a	237	get extended) - if it is C<0>, the value is "primitive" and contains
232	non-reference perl scalar. IF it is true, then the value is "constructed"	238	no subvalues, kind of like a non-reference perl scalar. If it is C<1>,
233	which just means it contains a list of subvalues which this module will	239	then the value is "constructed" which just means it contains a list of
234	en-/decode as BER tuples themselves.	240	subvalues which this module will en-/decode as BER tuples themselves.
235		241
236	The I<DATA> value is either a reference to an array of further tuples (if	242	The I<DATA> value is either a reference to an array of further tuples
237	the value is I<CONSTRUCTED>), some decoded representation of the value,	243	(if the value is I<FLAGS>), some decoded representation of the value, if
238	if this module knows how to decode it (e.g. for the integer types above)	244	this module knows how to decode it (e.g. for the integer types above) or
239	or a binary string with the raw octets if this module doesn't know how to	245	a binary string with the raw octets if this module doesn't know how to
240	interpret the namespace/tag.	246	interpret the namespace/tag.
241		247
242	Thus, you can always decode a BER data structure and at worst you get a	248	Thus, you can always decode a BER data structure and at worst you get a
243	string in place of some nice decoded value.	249	string in place of some nice decoded value.
244		250
…		…
246		252
247	=head2 DECODING AND ENCODING	253	=head2 DECODING AND ENCODING
248		254
249	=over	255	=over
250		256
251	=item $tuple = ber_decoded $bindata	257	=item $tuple = ber_decoded $bindata[, $profile]
252		258
253	Decodes binary BER data in C<$bindata> and returns the resulting BER	259	Decodes binary BER data in C<$bindata> and returns the resulting BER
254	tuple. Croaks on any decoding error, so the returned C<$tuple> is always	260	tuple. Croaks on any decoding error, so the returned C<$tuple> is always
255	valid.	261	valid.
256		262
		263	How tags are interpreted is defined by the second argument, which must
		264	be a C<Convert::BER::XS::Profile> object. If it is missing, the default
		265	profile will be used (C<$Convert::BER::XS::DEFAULT_PROFILE>).
		266
		267	In addition to rolling your own, this module provides a
		268	C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP
		269	types.
		270
		271	Example: decode a BER blob using the default profile - SNMP values will be
		272	decided as raw strings.
		273
		274	$tuple = ber_decode $data;
		275
		276	Example: as above, but use the provided SNMP profile.
		277
		278	$tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
		279
257	=item $bindata = ber_encode $tuple	280	=item $bindata = ber_encode $tuple[, $profile]
258		281
259	Encodes the BER tuple into a BER/DER data structure.	282	Encodes the BER tuple into a BER/DER data structure. AS with
		283	Cyber_decode>, an optional profile can be given.
		284
		285	The encoded data should be both BER and DER ("shortest form") compliant
		286	unless the input says otherwise (e.g. it uses constructed strings).
260		287
261	=back	288	=back
262		289
263	=head2 HELPER FUNCTIONS	290	=head2 HELPER FUNCTIONS
264		291
265	Working with a 4-tuple for every value can be annoying. Or, rather, I<is>	292	Working with a 4-tuple for every value can be annoying. Or, rather, I<is>
266	annoying. To reduce this a bit, this module defines a number of helper	293	annoying. To reduce this a bit, this module defines a number of helper
267	functions, both to match BER tuples and to conmstruct BER tuples:	294	functions, both to match BER tuples and to construct BER tuples:
268		295
269	=head3 MATCH HELPERS	296	=head3 MATCH HELPERS
270		297
271	Thse functions accept a BER tuple as first argument and either paertially	298	These functions accept a BER tuple as first argument and either partially
272	or fully match it. They often come in two forms, one which exactly matches	299	or fully match it. They often come in two forms, one which exactly matches
273	a value, and one which only matches the type and returns the value.	300	a value, and one which only matches the type and returns the value.
274		301
275	They do check whether valid tuples are passed in and croak otherwise. As	302	They do check whether valid tuples are passed in and croak otherwise. As
276	a ease-of-use exception, they usually also accept C<undef> instead of a	303	a ease-of-use exception, they usually also accept C<undef> instead of a
277	tuple reference. in which case they silently fail to match.	304	tuple reference, in which case they silently fail to match.
278		305
279	=over	306	=over
280		307
281	=item $bool = ber_is $tuple, $class, $tag, $constructed, $data	308	=item $bool = ber_is $tuple, $class, $tag, $flags, $data
282		309
283	This takes a BER C<$tuple> and matches its elements agains the privded	310	This takes a BER C<$tuple> and matches its elements against the provided
284	values, all of which are optional - values that are either missing or	311	values, all of which are optional - values that are either missing or
285	C<undef> will be ignored, the others will be matched exactly (e.g. as if	312	C<undef> will be ignored, the others will be matched exactly (e.g. as if
286	you used C<==> or C<eq> (for C<$data>)).	313	you used C<==> or C<eq> (for C<$data>)).
287		314
288	Some examples:	315	Some examples:
…		…
291	orf die "tuple is not an ASN SEQUENCE";	318	orf die "tuple is not an ASN SEQUENCE";
292		319
293	ber_is $tuple, ASN_UNIVERSAL, ASN_NULL	320	ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
294	or die "tuple is not an ASN NULL value";	321	or die "tuple is not an ASN NULL value";
295		322
296	ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50	323	ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER, 0, 50
297	or die "BER integer must be 50";	324	or die "BER integer must be 50";
298		325
299	=item $seq = ber_is_seq $tuple	326	=item $seq = ber_is_seq $tuple
300		327
301	Returns the sequence members (the array of subvalues) if the C<$tuple> is	328	Returns the sequence members (the array of subvalues) if the C<$tuple> is
…		…
308	my $snmp = ber_is_seq $ber	335	my $snmp = ber_is_seq $ber
309	or die "SNMP packet invalid: does not start with SEQUENCE";	336	or die "SNMP packet invalid: does not start with SEQUENCE";
310		337
311	# now we know $snmp is a sequence, so decode the SNMP version	338	# now we know $snmp is a sequence, so decode the SNMP version
312		339
313	my $version = ber_is_i32 $snmp->[0]	340	my $version = ber_is_int $snmp->[0]
314	or die "SNMP packet invalid: does not start with version number";	341	or die "SNMP packet invalid: does not start with version number";
315		342
316	=item $bool = ber_is_i32 $tuple, $i32	343	=item $bool = ber_is_int $tuple, $int
317		344
318	Returns a true value if the C<$tuple> represents an ASN INTEGER32 with	345	Returns a true value if the C<$tuple> represents an ASN INTEGER with
319	the value C<$i32>.	346	the value C<$int>.
320		347
321	=item $i32 = ber_is_i32 $tuple	348	=item $int = ber_is_int $tuple
322		349
323	Returns true (and extracts the integer value) if the C<$tuple> is an ASN	350	Returns true (and extracts the integer value) if the C<$tuple> is an
324	INTEGER32. For C<0>, this function returns a special value that is 0 but	351	C<ASN_INTEGER>. For C<0>, this function returns a special value that is 0
325	true.	352	but true.
326		353
327	=item $bool = ber_is_oid $tuple, $oid_string	354	=item $bool = ber_is_oid $tuple, $oid_string
328		355
329	Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER	356	Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
330	that exactly matches C<$oid_string>. Example:	357	that exactly matches C<$oid_string>. Example:
…		…
341		368
342	=head3 CONSTRUCTION HELPERS	369	=head3 CONSTRUCTION HELPERS
343		370
344	=over	371	=over
345		372
346	=item $tuple = ber_i32 $value	373	=item $tuple = ber_int $value
347		374
348	Constructs a new C<ASN_INTEGER32> tuple.	375	Constructs a new C<ASN_INTEGER> tuple.
349		376
350	=back	377	=back
351		378
352	=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>	379	=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
353		380
…		…
366	use Exporter qw(import);	393	use Exporter qw(import);
367		394
368	our $VERSION;	395	our $VERSION;
369		396
370	BEGIN {	397	BEGIN {
371	$VERSION = 0.8;	398	$VERSION = 0.9;
372	XSLoader::load __PACKAGE__, $VERSION;	399	XSLoader::load __PACKAGE__, $VERSION;
373	}	400	}
374		401
375	our %EXPORT_TAGS = (	402	our %EXPORT_TAGS = (
376	const_index => [qw(	403	const_index => [qw(
377	BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA	404	BER_CLASS BER_TAG BER_FLAGS BER_DATA
378	)],	405	)],
379	const_asn => [qw(	406	const_asn => [qw(
380	ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER	407	ASN_BOOLEAN ASN_INTEGER ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
381	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED	408	ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
382	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING	409	ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
383	ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING	410	ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
384	ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING	411	ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
385	ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING	412	ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
…		…
394	const_snmp => [qw(	421	const_snmp => [qw(
395	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64	422	SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
396	)],	423	)],
397	decode => [qw(	424	decode => [qw(
398	ber_decode	425	ber_decode
399	ber_is ber_is_seq ber_is_i32 ber_is_oid	426	ber_is ber_is_seq ber_is_int ber_is_oid
400	)],	427	)],
401	encode => [qw(	428	encode => [qw(
402	ber_encode	429	ber_encode
403	ber_i32	430	ber_int
404	)],	431	)],
405	);	432	);
406		433
407	our @EXPORT_OK = map @$_, values %EXPORT_TAGS;	434	our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
408		435
409	$EXPORT_TAGS{all} = \@EXPORT_OK;	436	$EXPORT_TAGS{all} = \@EXPORT_OK;
410	$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];	437	$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
411	use Data::Dump; ddx \%EXPORT_TAGS;
412		438
413	=head1 PROFILES	439	=head1 PROFILES
414		440
415	While any BER data can be correctly encoded and decoded out of the box, it	441	While any BER data can be correctly encoded and decoded out of the box, it
416	can be inconvenient to have to manually decode some values into a "better"	442	can be inconvenient to have to manually decode some values into a "better"
…		…
556	C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard	582	C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard
557	error for some types, then C<BER_TYPE_CROAK> is for you.	583	error for some types, then C<BER_TYPE_CROAK> is for you.
558		584
559	=back	585	=back
560		586
		587	=head2 Example Profile
		588
		589	The following creates a profile suitable for SNMP - it's exactly identical
		590	to the C<$Convert::BER::XS::SNMP_PROFILE> profile.
		591
		592	our $SNMP_PROFILE = new Convert::BER::XS::Profile;
		593
		594	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
		595	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
		596	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
		597	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
		598	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
		599	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
		600
561	=cut	601	=cut
562		602
563	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;	603	our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
564	our $SNMP_PROFILE = new Convert::BER::XS::Profile;	604
		605	$DEFAULT_PROFILE->_set_default;
565		606
566	# additional SNMP application types	607	# additional SNMP application types
		608	our $SNMP_PROFILE = new Convert::BER::XS::Profile;
		609
567	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);	610	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
568	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);	611	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
569	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);	612	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
570	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);	613	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
571	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);	614	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
572	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);	615	$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
573		616
574	$DEFAULT_PROFILE->_set_default;
575
576	1;	617	1;
577		618
578	=head2 LIMITATIONS/NOTES	619	=head2 LIMITATIONS/NOTES
579		620
580	This module can only en-/decode 64 bit signed and unsigned integers, and	621	This module can only en-/decode 64 bit signed and unsigned integers, and
581	only when your perl supports those.	622	only when your perl supports those.
582		623
583	This module does not generally care about ranges, i.e. it will happily	624	This module does not generally care about ranges, i.e. it will happily
584	de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative	625	de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
585	number into an C<SNMP_COUNTER64>.	626	number into an C<SNMP_COUNTER64>.
586		627
587	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is	628	OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
588	much larger than e.g. the one imposed by SNMP or other protocols,a nd is	629	much larger than e.g. the one imposed by SNMP or other protocols,a nd is
589	about 4kB.	630	about 4kB.
590		631
		632	Indefinite length encoding is not supported.
		633
		634	Constructed strings are decoded just fine, but there should be a way to
		635	join them for convenience.
		636
591	REAL values are not supported and will currently croak.	637	REAL values are not supported and will currently croak.
592		638
593	This module has undergone little to no testing so far.	639	This module has undergone little to no testing so far.
594		640
595	=head2 ITHREADS SUPPORT	641	=head2 ITHREADS SUPPORT

Diff Legend

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

Comparing Convert-BER-XS/XS.pm (file contents): Revision 1.20 by root, Sat Apr 20 14:47:23 2019 UTC vs. Revision 1.31 by root, Sat Apr 20 15:49:04 2019 UTC

Diff Legend

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.20 by root, Sat Apr 20 14:47:23 2019 UTC vs.
Revision 1.31 by root, Sat Apr 20 15:49:04 2019 UTC