1BER(3) User Contributed Perl Documentation BER(3)
2
6 Convert::BER - ASN.1 Basic Encoding Rules
7
9 use Convert::BER;
10 $ber = new Convert::BER;
12 $ber->encode(
14 INTEGER => 1,
15 SEQUENCE => [
16 BOOLEAN => 0,
17 STRING => "Hello",
18 ],
19 REAL => 3.7,
20 );
21 $ber->decode(
23 INTEGER => \$i,
24 SEQUENCE => [
25 BOOLEAN => \$b,
26 STRING => \$s,
27 ],
28 REAL => \$r,
29 );
30
32 "Convert::BER" provides an OO interface to encoding and decoding data
33 using the ASN.1 Basic Encoding Rules (BER), a platform independent way
34 of encoding structured binary data together with the structure.
35
37 new
38 new ( BUFFER )
39 new ( opList )
40 "new" creates a new "Convert::BER" object.
41 encode ( opList )
43 Encode data in opList appending to the data in the buffer.
44 decode ( opList )
46 Decode the data in the buffer as described by opList, starting
47 where the last decode finished or position set by "pos".
48 buffer ( [ BUFFER ] )
50 Return the buffer contents. If BUFFER is specified set the buffer
51 contents and reset pos to zero.
52 pos ( [ POS ] )
54 Without any arguments "pos" returns the offset where the last
55 decode finished, or the last offset set by "pos". If POS is
56 specified then POS will be where the next decode starts.
57 tag ( )
59 Returns the tag at the current position in the buffer.
60 length ( )
62 Returns the length of the buffer.
63 error ( )
65 Returns the error message associated with the last method, if any.
66 This value is not automatically reset. If "encode" or "decode"
67 returns undef, check this.
68 dump ( [ FH ] )
70 Dump the buffer to the filehandle "FH", or STDERR if not specified.
71 The output contains the hex dump of each element, and an ASN.1-like
72 text representation of that element.
73 hexdump ( [ FH ] )
75 Dump the buffer to the filehandle "FH", or STDERR if not specified.
76 The output is hex with the possibly-printable text alongside.
77
79 read ( IO )
80 write ( IO )
81 recv ( SOCK )
82 send ( SOCK [, ADDR ] )
83
85 An opList is a list of operator-value pairs. An operator can be any of
86 those defined below, or any defined by sub-classing "Convert::BER",
87 which will probably be derived from the primitives given here.
88 The values depend on whether BER is being encoded or decoded:
90 Encoding
92 If the value is a scalar, just encode it. If the value is a
93 reference to a list, then encode each item in the list in turn. If
94 the value is a code reference, then execute the code. If the
95 returned value is a scalar, encode that value. If the returned
96 value is a reference to a list, encode each item in the list in
97 turn.
98 Decoding
100 If the value is a reference to a scalar, decode the value into the
101 scalar. If the value is a reference to a list, then decode all the
102 items of this type into the list. Note that there must be at least
103 one item to decode, otherwise the decode will fail. If the value is
104 a code reference, then execute the code and decode the value into
105 the reference returned from the evaluated code.
106
108 These operators encode and decode the basic primitive types defined by
109 BER.
110 BOOLEAN
112 A BOOLEAN value is either true or false.
113 Encoding
115 The value is tested for boolean truth, and encoded appropriately.
116 # Encode a TRUE value
118 $ber->encode(
119 BOOLEAN => 1,
120 ) or die;
121 Decoding
123 The decoded values will be either 1 or 0.
124 # Decode a boolean value into $bval
126 $ber->decode(
127 BOOLEAN => \$bval,
128 ) or die;
129 INTEGER
131 An INTEGER value is either a positive whole number, or a negative whole
132 number, or zero. Numbers can either be native perl integers, or values
133 of the "Math::BigInt" class.
134 Encoding
136 The value is the integer value to be encoded.
137 $ber->encode(
139 INTEGER => -123456,
140 ) or die;
141 Decoding
143 The value will be the decoded integer value.
144 $ber->decode(
146 INTEGER => \$ival,
147 ) or die;
148 STRING
150 This is an OCTET STRING, which is an arbitrarily long binary value.
151 Encoding
153 The value contains the binary value to be encoded.
154 $ber->encode(
156 STRING => "\xC0First character is hex C0",
157 ) or die;
158 Decoding
160 The value will be the binary bytes.
161 $ber->decode(
163 STRING => \$sval,
164 ) or die;
165 NULL
167 There is no value for NULL. You often use NULL in ASN.1 when you want
168 to denote that something else is absent rather than just not encoding
169 the 'something else'.
170 Encoding
172 The values are ignored, but must be present.
173 $ber->encode(
175 NULL => undef,
176 ) or die;
177 Decoding
179 Dummy values are stored in the returned values, as though they were
180 present in the encoding.
181 $ber->decode(
183 NULL => \$nval,
184 ) or die;
185 OBJECT_ID
187 An OBJECT_ID value is an OBJECT IDENTIFIER (also called an OID). This
188 is a hierarchically structured value that is used in protocols to
189 uniquely identify something. For example, SNMP (the Simple Network
190 Management Protocol) uses OIDs to denote the information being
191 requested, and LDAP (the Lightweight Directory Access Protocol, RFC
192 2251) uses OIDs to denote each attribute in a directory entry.
193 Each level of the OID hierarchy is either zero or a positive integer.
195 Encoding
197 The value should be a dotted-decimal representation of the OID.
198 $ber->encode(
200 OBJECT_ID => '2.5.4.0', # LDAP objectClass
201 ) or die;
202 Decoding
204 The value will be the dotted-decimal representation of the OID.
205 $ber->decode(
207 OBJECT_ID => \$oval,
208 ) or die;
209 ENUM
211 The ENUMERATED type is effectively the same as the INTEGER type. It
212 exists so that friendly names can be assigned to certain integer
213 values. To be useful, you should sub-class this operator.
214 BIT_STRING
216 The BIT STRING type is an arbitrarily long string of bits - 0's and
217 1's.
218 Encoding
220 The value is a string of arbitrary 0 and 1 characters. As these are
221 packed into 8-bit octets when encoding and there may not be a
222 multiple of 8 bits to be encoded, trailing padding bits are added
223 in the encoding.
224 $ber->encode(
226 BIT_STRING => '0011',
227 ) or die;
228 Decoding
230 The value will be a string of 0 and 1 characters. The string will
231 have the same number of bits as were encoded (the padding bits are
232 ignored.)
233 $ber->decode(
235 BIT_STRING => \$bval,
236 ) or die;
237 BIT_STRING8
239 This is a variation of the BIT_STRING operator, which is optimized for
240 writing bit strings which are multiples of 8-bits in length. You can
241 use the BIT_STRING operator to decode BER encoded with the BIT_STRING8
242 operator (and vice-versa.)
243 Encoding
245 The value should be the packed bits to encode, not a string of 0
246 and 1 characters.
247 $ber->encode(
249 BIT_STRING8 => pack('B8', '10110101'),
250 ) or die;
251 Decoding
253 The value will be the decoded packed bits.
254 $ber->decode(
256 BIT_STRING8 => \$bval,
257 ) or die;
258 REAL
260 The REAL type encodes an floating-point number. It requires the POSIX
261 module.
262 Encoding
264 The value should be the number to encode.
265 $ber->encode(
267 REAL => 3.14159265358979,
268 ) or die;
269 Decoding
271 The value will be the decoded floating-point value.
272 $ber->decode(
274 REAL => \$rval,
275 );
276 ObjectDescriptor
278 The ObjectDescriptor type encodes an ObjectDescriptor string. It is a
279 sub-class of "STRING".
280 UTF8String
282 The UTF8String type encodes a string encoded in UTF-8. It is a sub-
283 class of "STRING".
284 NumericString
286 The NumericString type encodes a NumericString, which is defined to
287 only contain the characters 0-9 and space. It is a sub-class of
288 "STRING".
289 PrintableString
291 The PrintableString type encodes a PrintableString, which is defined to
292 only contain the characters A-Z, a-z, 0-9, space, and the punctuation
293 characters ()-+=:',./?. It is a sub-class of "STRING".
294 TeletexString/T61String
296 The TeletexString type encodes a TeletexString, which is a string
297 containing characters according to the T.61 character set. Each T.61
298 character may be one or more bytes wide. It is a sub-class of "STRING".
299 T61String is an alternative name for TeletexString.
301 VideotexString
303 The VideotexString type encodes a VideotexString, which is a string. It
304 is a sub-class of "STRING".
305 IA5String
307 The IA5String type encodes an IA5String. IA5 (International Alphabet 5)
308 is equivalent to US-ASCII. It is a sub-class of "STRING".
309 UTCTime
311 The UTCTime type encodes a UTCTime value. Note this value only
312 represents years using two digits, so it is not recommended in
313 Y2K-compliant applications. It is a sub-class of "STRING".
314 UTCTime values must be strings like:
316 yymmddHHMM[SS]Z
318 or:
319 yymmddHHMM[SS]sHHMM
320 Where yy is the year, mm is the month (01-12), dd is the day (01-31),
322 HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
323 seconds (00-61).
324 The time is either terminated by the literal character Z, or a timezone
326 offset. The "Z" character indicates Zulu time or UTC. The timezone
327 offset specifies the sign s, which is + or -, and the difference in
328 hours and minutes.
329 GeneralizedTime
331 The GeneralizedTime type encodes a GeneralizedTime value. Unlike
332 "UTCTime" it represents years using 4 digits, so is Y2K-compliant. It
333 is a sub-class of "STRING".
334 GeneralizedTime values must be strings like:
336 yyyymmddHHMM[SS][.U][Z]
338 or:
339 yyyymmddHHMM[SS][.U]sHHMM
340 Where yyyy is the year, mm is the month (01-12), dd is the day (01-31),
342 HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
343 seconds (00-61). U is the optional fractional seconds value; a comma is
344 permitted instead of a dot before this value.
345 The time may be terminated by the literal character Z, or a timezone
347 offset. The "Z" character indicates Zulu time or UTC. The timezone
348 offset specifies the sign s, which is + or -, and the difference in
349 hours and minutes. If there is timezone specified UTC is assumed.
350 GraphicString
352 The GraphicString type encodes a GraphicString value. It is a sub-class
353 of "STRING".
354 VisibleString/ISO646String
356 The VisibleString type encodes a VisibleString value, which is a value
357 using the ISO646 character set. It is a sub-class of "STRING".
358 ISO646String is an alternative name for VisibleString.
360 GeneralString
362 The GeneralString type encodes a GeneralString value. It is a sub-class
363 of "STRING".
364 UniversalString/CharacterString
366 The UniveralString type encodes a UniveralString value, which is a
367 value using the ISO10646 character set. Each character in ISO10646 is
368 4-bytes wide. It is a sub-class of "STRING".
369 CharacterString is an alternative name for UniversalString.
371 BMPString
373 The BMPString type encodes a BMPString value, which is a value using
374 the Unicode character set. Each character in the Unicode character set
375 is 2-bytes wide. It is a sub-class of "STRING".
376
378 These operators are used to build constructed types, which contain
379 values in different types, like a C structure.
380 SEQUENCE
382 A SEQUENCE is a complex type that contains other types, a bit like a C
383 structure. Elements inside a SEQUENCE are encoded and decoded in the
384 order given.
385 Encoding
387 The value should be a reference to an array containing another
388 opList which defines the elements inside the SEQUENCE.
389 $ber->encode(
391 SEQUENCE => [
392 INTEGER => 123,
393 BOOLEAN => [ 1, 0 ],
394 ]
395 ) or die;
396 Decoding
398 The value should a reference to an array that contains the opList
399 which decodes the contents of the SEQUENCE.
400 $ber->decode(
402 SEQUENCE => [
403 INTEGER => \$ival,
404 BOOLEAN => \@bvals,
405 ]
406 ) or die;
407 SET
409 A SET is an complex type that contains other types, rather like a
410 SEQUENCE. Elements inside a SET may be present in any order.
411 Encoding
413 The value is the same as for the SEQUENCE operator.
414 $ber->encode(
416 SET => [
417 INTEGER => 13,
418 STRING => 'Hello',
419 ]
420 ) or die;
421 Decoding
423 The value should be a reference to an equivalent opList to that
424 used to encode the SET. The ordering of the opList should not
425 matter.
426 $ber->decode(
428 SET => [
429 STRING => \$sval,
430 INTEGER => \$ival,
431 ]
432 ) or die;
433 SEQUENCE_OF
435 A SEQUENCE_OF is an ordered list of other types.
436 Encoding
438 The value is a ref followed by an opList. The ref must be a
439 reference to a list or a hash: if it is to a list, then the opList
440 will be repeated once for every element in the list. If it is to a
441 hash, then the opList will be repeated once for every key in the
442 hash (note that ordering of keys in a hash is not guaranteed by
443 perl.)
444 The remaining opList will then usually contain values which are
446 code references. If the ref is to a list, then the contents of that
447 item in the list are passed as the only argument to the code
448 reference. If the ref is to a hash, then only the key is passed to
449 the code.
450 @vals = ( [ 10, 'Foo' ], [ 20, 'Bar' ] ); # List of refs to lists
452 $ber->encode(
453 SEQUENCE_OF => [ \@vals,
454 SEQUENCE => [
455 INTEGER => sub { $_[0][0] }, # Passed a ref to the inner list
456 STRING => sub { $_[0][1] }, # Passed a ref to the inner list
457 ]
458 ]
459 ) or die;
460 %hash = ( 40 => 'Baz', 30 => 'Bletch' ); # Just a hash
461 $ber->decode(
462 SEQUENCE_OF => [ \%hash,
463 SEQUENCE => [
464 INTEGER => sub { $_[0] }, # Passed the key
465 STRING => sub { $hash{$_[0]} }, # Passed the key
466 ]
467 ]
468 );
469 Decoding
471 The value must be a reference to a list containing a ref and an
472 opList. The ref must always be a reference to a scalar. Each value
473 in the <opList> is usually a code reference. The code referenced is
474 called with the value of the ref (dereferenced); the value of the
475 ref is incremented for each item in the SEQUENCE_OF.
476 $ber->decode(
478 SEQUENCE_OF => [ \$count,
479 # In the following subs, make space at the end of an array, and
480 # return a reference to that newly created space.
481 SEQUENCE => [
482 INTEGER => sub { $ival[$_[0]] = undef; \$ival[-1] },
483 STRING => sub { $sval[$_[0]] = undef; \$sval[-1] },
484 ]
485 ]
486 ) or die;
487 SET_OF
489 A SET_OF is an unordered list. This is treated in an identical way to a
490 SEQUENCE_OF, except that no ordering should be inferred from the list
491 passed or returned.
492
494 BER
495 It is sometimes useful to construct or deconstruct BER encodings in
496 several pieces. The BER operator lets you do this.
497 Encoding
499 The value should be another "Convert::BER" object, which will be
500 inserted into the buffer. If value is undefined then nothing is
501 added.
502 $tmp->encode(
504 SEQUENCE => [
505 INTEGER => 20,
506 STRING => 'Foo',
507 ]
508 );
509 $ber->encode(
510 BER => $tmp,
511 BOOLEAN => 1
512 );
513 Decoding
515 value should be a reference to a scalar, which will contain a
516 "Convert::BER" object. This object will contain the remainder of
517 the current sequence or set being decoded.
518 # After this, ber2 will contain the encoded INTEGER B<and> STRING.
520 # sval will be ignored and left undefined, but bval will be decoded. The
521 # decode of ber2 will return the integer and string values.
522 $ber->decode(
523 SEQUENCE => [
524 BER => \$ber2,
525 STRING => \$sval,
526 ],
527 BOOLEAN => \$bval,
528 );
529 $ber2->decode(
530 INTEGER => \$ival,
531 STRING => \$sval2,
532 );
533 ANY
535 This is like the "BER" operator except that when decoding only the next
536 item is decoded and placed into the "Convert::BER" object returned.
537 There is no difference when encoding.
538 Decoding
540 value should be a reference to a scalar, which will contain a
541 "Convert::BER" object. This object will only contain the next
542 single item in the current sequence being decoded.
543 # After this, ber2 will decode further, and ival and sval
545 # will be decoded.
546 $ber->decode(
547 INTEGER = \$ival,
548 ANY => \$ber2,
549 STRING => \$sval,
550 );
551 OPTIONAL
553 This operator allows you to specify that an element is absent from the
554 encoding.
555 Encoding
557 The value should be a reference to another list with another
558 opList. If all of the values of the inner opList are defined, the
559 entire OPTIONAL value will be encoded, otherwise it will be
560 omitted.
561 $ber->encode(
563 SEQUENCE => [
564 INTEGER => 16, # Will be encoded
565 OPTIONAL => [
566 INTEGER => undef, # Will not be encoded
567 ],
568 STRING => 'Foo', # Will be encoded
569 ]
570 );
571 Decoding
573 The contents of value are decoded if possible, if not then decode
574 continues at the next operator-value pair.
575 $ber->decode(
577 SEQUENCE => [
578 INTEGER => \$ival1,
579 OPTIONAL => [
580 INTEGER => \$ival2,
581 ],
582 STRING => \$sval,
583 ]
584 );
585 CHOICE
587 The opList is a list of alternate operator-value pairs. Only one will
588 be encoded, and only one will be decoded.
589 Encoding
591 A scalar at the start of the opList identifies which opList
592 alternative to use for encoding the value. A value of 0 means the
593 first one is used, 1 means the second one, etc.
594 # Encode the BMPString alternate of the CHOICE
596 $ber->encode(
597 CHOICE => [ 2,
598 PrintableString => 'Printable',
599 TeletexString => 'Teletex/T61',
600 BMPString => 'BMP/Unicode',
601 UniversalString => 'Universal/ISO10646',
602 ]
603 ) or die;
604 Decoding
606 A reference to a scalar at the start of the opList is used to store
607 which alternative is decoded (0 for the first one, 1 for the second
608 one, etc.) Pass undef instead of the ref if you don't care about
609 this, or you store all the alternate values in different variables.
610 # Decode the above.
612 # Afterwards, $alt will be set to 2, $str will be set to 'BMP/Unicode'.
613 $ber->decode(
614 CHOICE => [ \$alt,
615 PrintableString => \$str,
616 TeletexString => \$str,
617 BMPString => \$str,
618 UniversalString => \$str,
619 ]
620 ) or die;
621
623 In BER everything being encoded has a tag, a length, and a value.
624 Normally the tag is derived from the operator - so INTEGER has a
625 different tag from a BOOLEAN, for instance.
626 In some applications it is necessary to change the tags used. For
628 example, a SET may need to contain two different INTEGER values. Tags
629 may be changed in two ways, either IMPLICITly or EXPLICITly. With
630 IMPLICIT tagging, the new tag completely replaces the old tag. With
631 EXPLICIT tagging, the new tag is used as well as the old tag.
632 "Convert::BER" supports two ways of using IMPLICIT tagging. One method
634 is to sub-class "Convert::BER", which is described in the next section.
635 For small applications or those that think sub-classing is just too
636 much then the operator may be passed an arrayref. The array must
637 contain two elements, the first is the usual operator name and the
638 second is the tag value to use, as shown below.
639 $ber->encode(
641 [ SEQUENCE => 0x34 ] => [
642 INTEGER => 10,
643 STRING => "A"
644 ]
645 ) or die;
646 This will encode a sequence, with a tag value of 0x34, which will
648 contain and integer and a string which will have their default tag
649 values.
650 You may wish to construct your tags using some pre-defined functions
652 such as &Convert::BER::BER_APPLICATION, &Convert::BER::BER_CONTEXT,
653 etc, instead of calculating the tag values yourself.
654 To use EXPLICIT tagging, enclose the original element in a SEQUENCE,
656 and just override the SEQUENCE's tag as above. Don't forget to set the
657 constructed bit using &Convert::BER::BER_CONSTRUCTOR. For example, the
658 ASN.1 definition:
659 Foo ::= SEQUENCE {
661 [0] EXPLICIT INTEGER,
662 INTEGER
663 }
664 might be encoded using this:
666 $ber->encode(
668 SEQUENCE => [
669 [ SEQUENCE => &Convert::BER::BER_CONTEXT |
670 &Convert::BER::BER_CONSTRUCTOR | 0 ] => [
671 INTEGER => 10,
672 ],
673 INTEGER => 11,
674 ],
675 ) or die;
676
678 For large applications where operators with non default tags are used a
679 lot the above mechanism can be very error-prone. For this reason,
680 "Convert::BER" may be sub-classed.
681 To do this the sub-class must call a static method "define". The
683 arguments to "define" is a list of arrayrefs. Each arrayref will define
684 one new operator. Each arrayref contains three values, the first is the
685 name of the operator, the second is how the data is encoded and the
686 third is the tag value. To aid with the creation of these arguments
687 "Convert::BER" exports some variables and constant subroutines.
688 For each operator defined by "Convert::BER", or a "Convert::BER" sub-
690 class, a scalar variable with the same name is available for import,
691 for example $INTEGER is available from "Convert::BER". And any
692 operators defined by a new sub-class will be available for import from
693 that class. One of these variables may be used as the second element
694 of each arrayref.
695 "Convert::BER" also exports some constant subroutines that can be used
697 to create the tag value. The subroutines exported are:
698 BER_BOOLEAN
700 BER_INTEGER
701 BER_BIT_STR
702 BER_OCTET_STR
703 BER_NULL
704 BER_OBJECT_ID
705 BER_SEQUENCE
706 BER_SET
707 BER_UNIVERSAL
709 BER_APPLICATION
710 BER_CONTEXT
711 BER_PRIVATE
712 BER_PRIMITIVE
713 BER_CONSTRUCTOR
714 "Convert::BER" also provides a subroutine called "ber_tag" to calculate
716 an integer value that will be used to represent a tag. For tags with
717 values less than 30 this is not needed, but for tags >= 30 then tag
718 value passed for an operator definition must be the result of "ber_tag"
719 "ber_tag" takes two arguments, the first is the tag class and the
721 second is the tag value.
722 Using this information a sub-class of Convert::BER can be created as
724 shown below.
725 package Net::LDAP::BER;
727 use Convert::BER qw(/^(\$|BER_)/);
729 use strict;
731 use vars qw($VERSION @ISA);
732 @ISA = qw(Convert::BER);
734 $VERSION = "1.00";
735 Net::LDAP::BER->define(
737 # Name Type Tag
739 ########################################
740 [ REQ_UNBIND => $NULL,
742 BER_APPLICATION | 0x02 ],
743 [ REQ_COMPARE => $SEQUENCE,
745 BER_APPLICATION | BER_CONSTRUCTOR | 0x0E ],
746 [ REQ_ABANDON => $INTEGER,
748 ber_tag(BER_APPLICATION, 0x10) ],
749 );
750 This will create a new class "Net::LDAP::BER" which has three new
752 operators available. This class then may be used as follows
753 $ber = new Net::LDAP::BER;
755 $ber->encode(
757 REQ_UNBIND => 0,
758 REQ_COMPARE => [
759 REQ_ABANDON => 123,
760 ]
761 );
762 $ber->decode(
764 REQ_UNBIND => \$var,
765 REQ_COMPARE => [
766 REQ_ABANDON => \$num,
767 ]
768 );
769 Which will encode or decode the data using the formats and tags defined
771 in the "Net::LDAP::BER" sub-class. It also helps to make the code more
772 readable.
773 DEFINING NEW PACKING OPERATORS
775 As well as defining new operators which inherit from existing operators
776 it is also possible to define a new operator and how data is encoded
777 and decoded. The interface for doing this is still changing but will be
778 documented here when it is done. To be continued ...
779
781 Convert::BER cannot support tags that contain more bits than can be
782 stored in a scalar variable, typically this is 32 bits.
783 Convert::BER cannot support items that have a packed length which
785 cannot be stored in 32 bits.
786
788 The "SET" decode method fails if the encoded order is different to the
789 opList order.
790
792 Graham Barr <gbarr@pobox.com>
793 Significant POD updates from Chris Ridd
795 <Chris.Ridd@messagingdirect.com>
796
798 Copyright (c) 1995-2000 Graham Barr. All rights reserved. This program
799 is free software; you can redistribute it and/or modify it under the
800 same terms as Perl itself.
801
803 Hey! The above document had some coding errors, which are explained
804 below:
805 Around line 364:
807 You forgot a '=back' before '=head2'
808perl v5.12.0 2001-03-21 BER(3)