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.25 by root, Sat Apr 20 15:23:26 2019 UTC

… …
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
… …
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
… …
140 140
141=item C<:decode> 141=item C<:decode>
142 142
143C<ber_decode> and the match helper functions: 143C<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
149C<ber_encode> and the construction helper functions: 149C<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
… …
167 167
168This works because BER values are tagged with a type and a namespace, 168This 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 169and 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
172Tags are simple integers, and ASN.1 defines a somewhat weird assortment of 172Tags are simple integers, and ASN.1 defines a somewhat weird assortment
173those - for example, you have 32 bit signed integers and 16(!) different 173of those - for example, you have one integers and 16(!) different
174string types, but there is no Unsigned32 type for example. Different 174string types, but there is no Unsigned32 type for example. Different
175applications work around this in different ways, for example, SNMP defines 175applications work around this in different ways, for example, SNMP defines
176application-specific Gauge32, Counter32 and Unsigned32, which are mapped 176application-specific Gauge32, Counter32 and Unsigned32, which are mapped
177to two different tags: you can distinguish between Counter32 and the 177to two different tags: you can distinguish between Counter32 and the
178others, but not between Gause32 and Unsigned32, without the ASN.1 schema. 178others, but not between Gause32 and Unsigned32, without the ASN.1 schema.
… …
186 186
187 [CLASS, TAG, CONSTRUCTED, DATA] 187 [CLASS, TAG, CONSTRUCTED, DATA]
188 188
189For example: 189For example:
190 190
191 [ASN_UNIVERSAL, ASN_INTEGER32, 0, 177] # the integer 177 191 [ASN_UNIVERSAL, ASN_INTEGER, 0, 177] # the integer 177
192 [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john" 192 [ASN_UNIVERSAL, ASN_OCTET_STRING, 0, "john"] # the string "john"
193 [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID 193 [ASN_UNIVERSAL, ASN_OID, 0, "1.3.6.133"] # some OID
194 [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence 194 [ASN_UNIVERSAL, ASN_SEQUENCE, 1, [ [ASN_UNIVERSAL... # a sequence
195 195
196To avoid non-descriptive hardcoded array index numbers, this module 196To avoid non-descriptive hardcoded array index numbers, this module
… …
207 # the following is NOT legal: 207 # the following is NOT legal:
208 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!) 208 $ber->[BER_CLASS] = ASN_PRIVATE; # ERROR, CLASS/TAG/CONSTRUCTED are READ ONLY(!)
209 209
210 # but all of the following are fine: 210 # but all of the following are fine:
211 $ber->[BER_DATA] = "string"; 211 $ber->[BER_DATA] = "string";
212 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER32, 0, 123]; 212 $ber->[BER_DATA] = [ASN_UNIVERSAL, ASN_INTEGER, 0, 123];
213 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000); 213 @$ber = (ASN_APPLICATION, SNMP_TIMETICKS, 0, 1000);
214 214
215I<CLASS> is something like a namespace for I<TAG>s - there is the 215I<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 216C<ASN_UNIVERSAL> namespace which defines tags common to all ASN.1
217implementations, the C<ASN_APPLICATION> namespace which defines tags for 217implementations, the C<ASN_APPLICATION> namespace which defines tags for
… …
223(partial) interpretation of the data value. For example, SNMP defines 223(partial) interpretation of the data value. For example, SNMP defines
224extra tags in the C<ASN_APPLICATION> namespace, and to take full advantage 224extra 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. 225of these, you need to tell this module how to handle those via profiles.
226 226
227The most common tags in the C<ASN_UNIVERSAL> namespace are 227The most common tags in the C<ASN_UNIVERSAL> namespace are
228C<ASN_INTEGER32>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>, 228C<ASN_INTEGER>, C<ASN_BIT_STRING>, C<ASN_NULL>, C<ASN_OCTET_STRING>,
229C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and 229C<ASN_OBJECT_IDENTIFIER>, C<ASN_SEQUENCE>, C<ASN_SET> and
230C<ASN_IA5_STRING>. 230C<ASN_IA5_STRING>.
231 231
232The most common tags in SNMP's C<ASN_APPLICATION> namespace are 232The most common tags in SNMP's C<ASN_APPLICATION> namespace are
233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and 233C<SNMP_COUNTER32>, C<SNMP_UNSIGNED32>, C<SNMP_TIMETICKS> and
… …
266 266
267In addition to rolling your own, this module provides a 267In addition to rolling your own, this module provides a
268C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP 268C<$Convert::BER::XS::SNMP_PROFILE> that knows about the additional SNMP
269types. 269types.
270 270
271Example: decode a BER blob using the default profile - SNMP values will be
272decided as raw strings.
273
274 $tuple = ber_decode $data;
275
276Example: as above, but use the provided SNMP profile.
277
278 $tuple = ber_encode $data, $Convert::BER::XS::SNMP_PROFILE;
279
271=item $bindata = ber_encode $tuple[, $profile] 280=item $bindata = ber_encode $tuple[, $profile]
272 281
273Encodes the BER tuple into a BER/DER data structure. AS with 282Encodes the BER tuple into a BER/DER data structure. AS with
274Cyber_decode>, an optional profile can be given. 283Cyber_decode>, an optional profile can be given.
275 284
… …
306 orf die "tuple is not an ASN SEQUENCE"; 315 orf die "tuple is not an ASN SEQUENCE";
307 316
308 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL 317 ber_is $tuple, ASN_UNIVERSAL, ASN_NULL
309 or die "tuple is not an ASN NULL value"; 318 or die "tuple is not an ASN NULL value";
310 319
311 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER32, 0, 50 320 ber_is $tuple, ASN_UNIVERSAL, ASN_INTEGER, 0, 50
312 or die "BER integer must be 50"; 321 or die "BER integer must be 50";
313 322
314=item $seq = ber_is_seq $tuple 323=item $seq = ber_is_seq $tuple
315 324
316Returns the sequence members (the array of subvalues) if the C<$tuple> is 325Returns the sequence members (the array of subvalues) if the C<$tuple> is
… …
323 my $snmp = ber_is_seq $ber 332 my $snmp = ber_is_seq $ber
324 or die "SNMP packet invalid: does not start with SEQUENCE"; 333 or die "SNMP packet invalid: does not start with SEQUENCE";
325 334
326 # now we know $snmp is a sequence, so decode the SNMP version 335 # now we know $snmp is a sequence, so decode the SNMP version
327 336
328 my $version = ber_is_i32 $snmp->[0] 337 my $version = ber_is_int $snmp->[0]
329 or die "SNMP packet invalid: does not start with version number"; 338 or die "SNMP packet invalid: does not start with version number";
330 339
331=item $bool = ber_is_i32 $tuple, $i32 340=item $bool = ber_is_int $tuple, $int
332 341
333Returns a true value if the C<$tuple> represents an ASN INTEGER32 with 342Returns a true value if the C<$tuple> represents an ASN INTEGER with
334the value C<$i32>. 343the value C<$int>.
335 344
336=item $i32 = ber_is_i32 $tuple 345=item $int = ber_is_int $tuple
337 346
338Returns true (and extracts the integer value) if the C<$tuple> is an ASN 347Returns 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 348C<ASN_INTEGER>. For C<0>, this function returns a special value that is 0
340true. 349but true.
341 350
342=item $bool = ber_is_oid $tuple, $oid_string 351=item $bool = ber_is_oid $tuple, $oid_string
343 352
344Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER 353Returns true if the C<$tuple> represents an ASN_OBJECT_IDENTIFIER
345that exactly matches C<$oid_string>. Example: 354that exactly matches C<$oid_string>. Example:
… …
356 365
357=head3 CONSTRUCTION HELPERS 366=head3 CONSTRUCTION HELPERS
358 367
359=over 368=over
360 369
361=item $tuple = ber_i32 $value 370=item $tuple = ber_int $value
362 371
363Constructs a new C<ASN_INTEGER32> tuple. 372Constructs a new C<ASN_INTEGER> tuple.
364 373
365=back 374=back
366 375
367=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1> 376=head2 RELATIONSHIP TO L<Convert::BER> and L<Convert::ASN1>
368 377
… …
390our %EXPORT_TAGS = ( 399our %EXPORT_TAGS = (
391 const_index => [qw( 400 const_index => [qw(
392 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA 401 BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
393 )], 402 )],
394 const_asn => [qw( 403 const_asn => [qw(
395 ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER 404 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 405 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 406 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 407 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 408 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 409 ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
… …
409 const_snmp => [qw( 418 const_snmp => [qw(
410 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64 419 SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
411 )], 420 )],
412 decode => [qw( 421 decode => [qw(
413 ber_decode 422 ber_decode
414 ber_is ber_is_seq ber_is_i32 ber_is_oid 423 ber_is ber_is_seq ber_is_int ber_is_oid
415 )], 424 )],
416 encode => [qw( 425 encode => [qw(
417 ber_encode 426 ber_encode
418 ber_i32 427 ber_int
419 )], 428 )],
420); 429);
421 430
422our @EXPORT_OK = map @$_, values %EXPORT_TAGS; 431our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
423 432
… …
594 603
595This module can only en-/decode 64 bit signed and unsigned integers, and 604This module can only en-/decode 64 bit signed and unsigned integers, and
596only when your perl supports those. 605only when your perl supports those.
597 606
598This module does not generally care about ranges, i.e. it will happily 607This 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 608de-/encode 64 bit integers into an C<ASN_INTEGER> value, or a negative
600number into an C<SNMP_COUNTER64>. 609number into an C<SNMP_COUNTER64>.
601 610
602OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is 611OBJECT 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 612much larger than e.g. the one imposed by SNMP or other protocols,a nd is
604about 4kB. 613about 4kB.

Diff Legend

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