ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-BER-XS/XS.pm
(Generate patch)

Comparing Convert-BER-XS/XS.pm (file contents):
Revision 1.24 by root, Sat Apr 20 14:59:26 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?
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
… …
100 100
101=item C<:const_index> 101=item C<:const_index>
102 102
103The BER tuple array index constants: 103The 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
109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively - 109ASN class values (these are C<0>, C<1>, C<2> and C<3>, respectively -
110exactly thw two topmost bits from the identifier octet shifted 6 bits to 110exactly thw two topmost bits from the identifier octet shifted 6 bits to
… …
113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE 113 ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
114 114
115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their 115ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
116numerical value corresponds exactly to the numbers used in BER/X.690. 116numerical 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
… …
134 134
135Constants only relevant to SNMP. These are the tag values used by SNMP in 135Constants only relevant to SNMP. These are the tag values used by SNMP in
136the C<ASN_APPLICATION> namespace and have the exact numerical value as in 136the C<ASN_APPLICATION> namespace and have the exact numerical value as in
137BER/RFC 2578. 137BER/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
143C<ber_decode> and the match helper functions: 144C<ber_decode> and the match helper functions:
144 145
145 ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid 146 ber_decode ber_is ber_is_seq ber_is_int ber_is_oid
146 147
147=item C<:encode> 148=item C<:encode>
148 149
149C<ber_encode> and the construction helper functions: 150C<ber_encode> and the construction helper functions:
150 151
151 ber_encode ber_i32 152 ber_encode ber_int
152 153
153=back 154=back
154 155
155=head2 ASN.1/BER/DER/... BASICS 156=head2 ASN.1/BER/DER/... BASICS
156 157
157ASN.1 is a strange language that can be used to describe protocols and 158ASN.1 is a strange language that can be used to describe protocols and
158data structures. It supports various mappings to JSON, XML, but most 159data structures. It supports various mappings to JSON, XML, but most
159importantly, to a various binary encodings such as BER, that is the topic 160importantly, to a various binary encodings such as BER, that is the topic
160of this module, and is used in SNMP or LDAP for example. 161of this module, and is used in SNMP, LDAP or X.509 for example.
161 162
162While ASN.1 defines a schema that is useful to interpret encoded data, 163While ASN.1 defines a schema that is useful to interpret encoded data,
163the BER encoding is actually somewhat self-describing: you might not know 164the BER encoding is actually somewhat self-describing: you might not know
164whether something is a string or a number or a sequence or something else, 165whether something is a string or a number or a sequence or something else,
165but you can nevertheless decode the overall structure, even if you end up 166but you can nevertheless decode the overall structure, even if you end up
… …
167 168
168This works because BER values are tagged with a type and a namespace, 169This works because BER values are tagged with a type and a namespace,
169and also have a flag that says whether a value consists of subvalues (is 170and also have a flag that says whether a value consists of subvalues (is
170"constructed") or not (is "primitive"). 171"constructed") or not (is "primitive").
171 172
172Tags are simple integers, and ASN.1 defines a somewhat weird assortment of 173Tags are simple integers, and ASN.1 defines a somewhat weird assortment
173those - for example, you have 32 bit signed integers and 16(!) different 174of those - for example, you have one integers and 16(!) different
174string types, but there is no Unsigned32 type for example. Different 175string types, but there is no Unsigned32 type for example. Different
175applications work around this in different ways, for example, SNMP defines 176applications work around this in different ways, for example, SNMP defines
176application-specific Gauge32, Counter32 and Unsigned32, which are mapped 177application-specific Gauge32, Counter32 and Unsigned32, which are mapped
177to two different tags: you can distinguish between Counter32 and the 178to two different tags: you can distinguish between Counter32 and the
178others, but not between Gause32 and Unsigned32, without the ASN.1 schema. 179others, but not between Gause32 and Unsigned32, without the ASN.1 schema.
… …
182=head2 DECODED BER REPRESENTATION 183=head2 DECODED BER REPRESENTATION
183 184
184This module represents every BER value as a 4-element tuple (actually an 185This module represents every BER value as a 4-element tuple (actually an
185array-reference): 186array-reference):
186 187
187 [CLASS, TAG, CONSTRUCTED, DATA] 188 [CLASS, TAG, FLAGS, DATA]
188 189
189For example: 190For example:
190 191
191 [ASN_UNIVERSAL, ASN_INTEGER32, 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
196To avoid non-descriptive hardcoded array index numbers, this module 197To avoid non-descriptive hardcoded array index numbers, this module
197defines symbolic constants to access these members: C<BER_CLASS>, 198defines symbolic constants to access these members: C<BER_CLASS>,
198C<BER_TAG>, C<BER_CONSTRUCTED> and C<BER_DATA>. 199C<BER_TAG>, C<BER_FLAGS> and C<BER_DATA>.
199 200
200Also, the first three members are integers with a little caveat: for 201Also, the first three members are integers with a little caveat: for
201performance reasons, these are readonly and shared, so you must not modify 202performance reasons, these are readonly and shared, so you must not modify
202them (increment, assign to them etc.) in any way. You may modify the 203them (increment, assign to them etc.) in any way. You may modify the
203I<DATA> member, and you may re-assign the array itself, e.g.: 204I<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_INTEGER32, 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);
214 215
215I<CLASS> is something like a namespace for I<TAG>s - there is the 216I<CLASS> is something like a namespace for I<TAG>s - there is the
216C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1 217C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
217implementations, the C<ASN_APPLICATION> namespace which defines tags for 218implementations, the C<ASN_APPLICATION> namespace which defines tags for
… …
223(partial) interpretation of the data value. For example, SNMP defines 224(partial) interpretation of the data value. For example, SNMP defines
224extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage 225extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage
225of these, you need to tell this module how to handle those via profiles. 226of these, you need to tell this module how to handle those via profiles.
226 227
227The most common tags in the C<ASN_UNIVERSAL> namespace are 228The most common tags in the C<ASN_UNIVERSAL> namespace are
228C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>, 229C<ASN_INTEGER>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
229C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and 230C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
230C<ASN_IA5_STRING>. 231C<ASN_IA5_STRING>.
231 232
232The most common tags in SNMP's C<ASN_APPLICATION> namespace are 233The most common tags in SNMP's C<ASN_APPLICATION> namespace are
233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and 234C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
234C<SNMP_COUNTER64>. 235C<SNMP_COUNTER64>.
235 236
236The I<CONSTRUCTED> flag is really just a boolean - if it is false, 237The I<FLAGS> value is really just a boolean at this time (but might
237the value is "primitive" and contains no subvalues, kind of like a 238get extended) - if it is C<0>, the value is "primitive" and contains
238non-reference perl scalar. If it is true, then the value is "constructed" 239no subvalues, kind of like a non-reference perl scalar. If it is C<1>,
239which just means it contains a list of subvalues which this module will 240then the value is "constructed" which just means it contains a list of
240en-/decode as BER tuples themselves. 241subvalues which this module will en-/decode as BER tuples themselves.
241 242
242The I<DATA> value is either a reference to an array of further tuples (if 243The I<DATA> value is either a reference to an array of further tuples
243the value is I<CONSTRUCTED>), some decoded representation of the value, 244(if the value is I<FLAGS>), some decoded representation of the value, if
244if this module knows how to decode it (e.g. for the integer types above) 245this module knows how to decode it (e.g. for the integer types above) or
245or a binary string with the raw octets if this module doesn't know how to 246a binary string with the raw octets if this module doesn't know how to
246interpret the namespace/tag. 247interpret the namespace/tag.
247 248
248Thus, you can always decode a BER data structure and at worst you get a 249Thus, you can always decode a BER data structure and at worst you get a
249string in place of some nice decoded value. 250string in place of some nice decoded value.
250 251
… …
266 267
267In addition to rolling your own, this module provides a 268In addition to rolling your own, this module provides a
268C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP 269C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP
269types. 270types.
270 271
272Example: decode a BER blob using the default profile - SNMP values will be
273decided as raw strings.
274
275 $tuple = ber_decode $data;
276
277Example: as above, but use the provided SNMP profile.
278
279 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
280
271=item $bindata = ber_encode $tuple[, $profile] 281=item $bindata = ber_encode $tuple[, $profile]
272 282
273Encodes the BER tuple into a BER/DER data structure. AS with 283Encodes the BER tuple into a BER/DER data structure. AS with
274Cyber_decode>, an optional profile can be given. 284Cyber_decode>, an optional profile can be given.
285
286The encoded data should be both BER and DER ("shortest form") compliant
287unless the input says otherwise (e.g. it uses constructed strings).
275 288
276=back 289=back
277 290
278=head2 HELPER FUNCTIONS 291=head2 HELPER FUNCTIONS
279 292
… …
291a ease-of-use exception, they usually also accept C<undef> instead of a 304a ease-of-use exception, they usually also accept C<undef> instead of a
292tuple reference, in which case they silently fail to match. 305tuple reference, in which case they silently fail to match.
293 306
294=over 307=over
295 308
296=item $bool = ber_is $tuple, $class, $tag, $constructed, $data 309=item $bool = ber_is $tuple, $class, $tag, $flags, $data
297 310
298This takes a BER C<$tuple> and matches its elements against the provided 311This takes a BER C<$tuple> and matches its elements against the provided
299values, all of which are optional - values that are either missing or 312values, all of which are optional - values that are either missing or
300C<undef> will be ignored, the others will be matched exactly (e.g. as if 313C<undef> will be ignored, the others will be matched exactly (e.g. as if
301you used C<==> or C<eq> (for C<$data>)). 314you used C<==> or C<eq> (for C<$data>)).
… …
306 orf die "tuple is not an ASN SEQUENCE"; 319 orf die "tuple is not an ASN SEQUENCE";
307 320
308 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL 321 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
309 or die "tuple is not an ASN NULL value"; 322 or die "tuple is not an ASN NULL value";
310 323
311 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50 324 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER, 0, 50
312 or die "BER integer must be 50"; 325 or die "BER integer must be 50";
313 326
314=item $seq = ber_is_seq $tuple 327=item $seq = ber_is_seq $tuple
315 328
316Returns the sequence members (the array of subvalues) if the C<$tuple> is 329Returns the sequence members (the array of subvalues) if the C<$tuple> is
… …
323 my $snmp = ber_is_seq $ber 336 my $snmp = ber_is_seq $ber
324 or die "SNMP packet invalid: does not start with SEQUENCE"; 337 or die "SNMP packet invalid: does not start with SEQUENCE";
325 338
326 # now we know $snmp is a sequence, so decode the SNMP version 339 # now we know $snmp is a sequence, so decode the SNMP version
327 340
328 my $version = ber_is_i32 $snmp->[0] 341 my $version = ber_is_int $snmp->[0]
329 or die "SNMP packet invalid: does not start with version number"; 342 or die "SNMP packet invalid: does not start with version number";
330 343
331=item $bool = ber_is_i32 $tuple, $i32 344=item $bool = ber_is_int $tuple, $int
332 345
333Returns a true value if the C<$tuple> represents an ASN INTEGER32 with 346Returns a true value if the C<$tuple> represents an ASN INTEGER with
334the value C<$i32>. 347the value C<$int>.
335 348
336=item $i32 = ber_is_i32 $tuple 349=item $int = ber_is_int $tuple
337 350
338Returns true (and extracts the integer value) if the C<$tuple> is an ASN 351Returns true (and extracts the integer value) if the C<$tuple> is an
339INTEGER32. For C<0>, this function returns a special value that is 0 but 352C<ASN_INTEGER>. For C<0>, this function returns a special value that is 0
340true. 353but true.
341 354
342=item $bool = ber_is_oid $tuple, $oid_string 355=item $bool = ber_is_oid $tuple, $oid_string
343 356
344Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER 357Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
345that exactly matches C<$oid_string>. Example: 358that exactly matches C<$oid_string>. Example:
… …
356 369
357=head3 CONSTRUCTION HELPERS 370=head3 CONSTRUCTION HELPERS
358 371
359=over 372=over
360 373
361=item $tuple = ber_i32 $value 374=item $tuple = ber_int $value
362 375
363Constructs a new C<ASN_INTEGER32> tuple. 376Constructs a new C<ASN_INTEGER> tuple.
364 377
365=back 378=back
366 379
367=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1> 380=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
368 381
… …
381use Exporter qw(import); 394use Exporter qw(import);
382 395
383our $VERSION; 396our $VERSION;
384 397
385BEGIN { 398BEGIN {
386 $VERSION = 0.8; 399 $VERSION = 0.9;
387 XSLoader::load __PACKAGE__, $VERSION; 400 XSLoader::load __PACKAGE__, $VERSION;
388} 401}
389 402
390our %EXPORT_TAGS = ( 403our %EXPORT_TAGS = (
391 const_index => [qw( 404 const_index => [qw(
392 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 405 BER_CLASS BER_TAG BER_FLAGS BER_DATA
393 )], 406 )],
394 const_asn => [qw( 407 const_asn => [qw(
395 ASN_BOOLEAN ASN_INTEGER32 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
396 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
397 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
398 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING 411 ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
399 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING 412 ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
400 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING 413 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
… …
405 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
406 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
407 BER_TYPE_IPADDRESS BER_TYPE_CROAK 420 BER_TYPE_IPADDRESS BER_TYPE_CROAK
408 )], 421 )],
409 const_snmp => [qw( 422 const_snmp => [qw(
410 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
411 )], 425 )],
412 decode => [qw( 426 decode => [qw(
413 ber_decode 427 ber_decode
414 ber_is ber_is_seq ber_is_i32 ber_is_oid 428 ber_is ber_is_seq ber_is_int ber_is_oid
415 )], 429 )],
416 encode => [qw( 430 encode => [qw(
417 ber_encode 431 ber_encode
418 ber_i32 432 ber_int
419 )], 433 )],
420); 434);
421 435
422our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 436our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
423 437
424$EXPORT_TAGS{all} = \@EXPORT_OK; 438$EXPORT_TAGS{all} = \@EXPORT_OK;
425$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)]; 439$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
426use Data::Dump; ddx \%EXPORT_TAGS;
427 440
428=head1 PROFILES 441=head1 PROFILES
429 442
430While any BER data can be correctly encoded and decoded out of the box, it 443While any BER data can be correctly encoded and decoded out of the box, it
431can be inconvenient to have to manually decode some values into a "better" 444can be inconvenient to have to manually decode some values into a "better"
… …
571C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard 584C<BER_TYPE_BYTES>. When you don't want that but instead prefer a hard
572error for some types, then C<BER_TYPE_CROAK> is for you. 585error for some types, then C<BER_TYPE_CROAK> is for you.
573 586
574=back 587=back
575 588
589=head2 Example Profile
590
591The following creates a profile suitable for SNMP - it's exactly identical
592to 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
576=cut 603=cut
577 604
578our $DEFAULT_PROFILE = new Convert::BER::XS::Profile; 605our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
579our $SNMP_PROFILE = new Convert::BER::XS::Profile; 606
607$DEFAULT_PROFILE->_set_default;
580 608
581# additional SNMP application types 609# additional SNMP application types
610our $SNMP_PROFILE = new Convert::BER::XS::Profile;
611
582$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS); 612$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
583$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT); 613$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
584$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT); 614$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
585$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT); 615$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_TIMETICKS , BER_TYPE_INT);
586$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS); 616$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_OPAQUE , BER_TYPE_IPADDRESS);
587$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT); 617$SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER64 , BER_TYPE_INT);
588 618
589$DEFAULT_PROFILE->_set_default;
590
5911; 6191;
592 620
593=head2 LIMITATIONS/NOTES 621=head2 LIMITATIONS/NOTES
594 622
595This module can only en-/decode 64 bit signed and unsigned integers, and 623This module can only en-/decode 64 bit signed and unsigned integers, and
596only when your perl supports those. 624only when your perl supports those.
597 625
598This module does not generally care about ranges, i.e. it will happily 626This module does not generally care about ranges, i.e. it will happily
599de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative 627de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
600number into an C<SNMP_COUNTER64>. 628number into an C<SNMP_COUNTER64>.
601 629
602OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 630OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
603much larger than e.g. the one imposed by SNMP or other protocols,a nd is 631much larger than e.g. the one imposed by SNMP or other protocols,a nd is
604about 4kB. 632about 4kB.
605 633
634Indefinite length encoding is not supported.
635
636Constructed strings are decoded just fine, but there should be a way to
637join them for convenience.
638
606REAL values are not supported and will currently croak. 639REAL values are not supported and will currently croak.
640
641The encoder and decoder tend to accept more formats than should be
642strictly supported.
607 643
608This module has undergone little to no testing so far. 644This module has undergone little to no testing so far.
609 645
610=head2 ITHREADS SUPPORT 646=head2 ITHREADS SUPPORT
611 647

Diff Legend

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