Convert::BER(3pm)

1BER(3)                User Contributed Perl Documentation               BER(3)
2
3
4

NAME

6       Convert::BER - ASN.1 Basic Encoding Rules
7

SYNOPSIS

9           use Convert::BER;
10
11           $ber = new Convert::BER;
12
13           $ber->encode(
14               INTEGER => 1,
15               SEQUENCE => [
16                   BOOLEAN => 0,
17                   STRING => "Hello",
18               ],
19               REAL => 3.7,
20           );
21
22           $ber->decode(
23               INTEGER => \$i,
24               SEQUENCE => [
25                   BOOLEAN => \$b,
26                   STRING => \$s,
27               ],
28               REAL => \$r,
29           );
30

DESCRIPTION

32       WARNING this module is no longer supported, See Convert::ASN1
33
34       "Convert::BER" provides an OO interface to encoding and decoding data
35       using the ASN.1 Basic Encoding Rules (BER), a platform independent way
36       of encoding structured binary data together with the structure.
37

METHODS

39       new
40       new ( BUFFER )
41       new ( opList )
42           "new" creates a new "Convert::BER" object.
43
44       encode ( opList )
45           Encode data in opList appending to the data in the buffer.
46
47       decode ( opList )
48           Decode the data in the buffer as described by opList, starting
49           where the last decode finished or position set by "pos".
50
51       buffer ( [ BUFFER ] )
52           Return the buffer contents. If BUFFER is specified set the buffer
53           contents and reset pos to zero.
54
55       pos ( [ POS ] )
56           Without any arguments "pos" returns the offset where the last
57           decode finished, or the last offset set by "pos". If POS is
58           specified then POS will be where the next decode starts.
59
60       tag ( )
61           Returns the tag at the current position in the buffer.
62
63       length ( )
64           Returns the length of the buffer.
65
66       error ( )
67           Returns the error message associated with the last method, if any.
68           This value is not automatically reset. If "encode" or "decode"
69           returns undef, check this.
70
71       dump ( [ FH ] )
72           Dump the buffer to the filehandle "FH", or STDERR if not specified.
73           The output contains the hex dump of each element, and an ASN.1-like
74           text representation of that element.
75
76       hexdump  ( [ FH ] )
77           Dump the buffer to the filehandle "FH", or STDERR if not specified.
78           The output is hex with the possibly-printable text alongside.
79

IO METHODS

81       read ( IO )
82       write ( IO )
83       recv ( SOCK )
84       send ( SOCK [, ADDR ] )
85

OPLIST

87       An opList is a list of operator-value pairs. An operator can be any of
88       those defined below, or any defined by sub-classing "Convert::BER",
89       which will probably be derived from the primitives given here.
90
91       The values depend on whether BER is being encoded or decoded:
92
93       Encoding
94           If the value is a scalar, just encode it. If the value is a
95           reference to a list, then encode each item in the list in turn. If
96           the value is a code reference, then execute the code. If the
97           returned value is a scalar, encode that value. If the returned
98           value is a reference to a list, encode each item in the list in
99           turn.
100
101       Decoding
102           If the value is a reference to a scalar, decode the value into the
103           scalar. If the value is a reference to a list, then decode all the
104           items of this type into the list. Note that there must be at least
105           one item to decode, otherwise the decode will fail. If the value is
106           a code reference, then execute the code and decode the value into
107           the reference returned from the evaluated code.
108

PRIMITIVE OPERATORS

110       These operators encode and decode the basic primitive types defined by
111       BER.
112
113   BOOLEAN
114       A BOOLEAN value is either true or false.
115
116       Encoding
117           The value is tested for boolean truth, and encoded appropriately.
118
119               # Encode a TRUE value
120               $ber->encode(
121                   BOOLEAN => 1,
122               ) or die;
123
124       Decoding
125           The decoded values will be either 1 or 0.
126
127               # Decode a boolean value into $bval
128               $ber->decode(
129                   BOOLEAN => \$bval,
130               ) or die;
131
132   INTEGER
133       An INTEGER value is either a positive whole number, or a negative whole
134       number, or zero. Numbers can either be native perl integers, or values
135       of the "Math::BigInt" class.
136
137       Encoding
138           The value is the integer value to be encoded.
139
140               $ber->encode(
141                   INTEGER => -123456,
142               ) or die;
143
144       Decoding
145           The value will be the decoded integer value.
146
147               $ber->decode(
148                   INTEGER => \$ival,
149               ) or die;
150
151   STRING
152       This is an OCTET STRING, which is an arbitrarily long binary value.
153
154       Encoding
155           The value contains the binary value to be encoded.
156
157               $ber->encode(
158                   STRING => "\xC0First character is hex C0",
159               ) or die;
160
161       Decoding
162           The value will be the binary bytes.
163
164               $ber->decode(
165                   STRING => \$sval,
166               ) or die;
167
168   NULL
169       There is no value for NULL. You often use NULL in ASN.1 when you want
170       to denote that something else is absent rather than just not encoding
171       the 'something else'.
172
173       Encoding
174           The values are ignored, but must be present.
175
176               $ber->encode(
177                   NULL => undef,
178               ) or die;
179
180       Decoding
181           Dummy values are stored in the returned values, as though they were
182           present in the encoding.
183
184               $ber->decode(
185                   NULL => \$nval,
186               ) or die;
187
188   OBJECT_ID
189       An OBJECT_ID value is an OBJECT IDENTIFIER (also called an OID). This
190       is a hierarchically structured value that is used in protocols to
191       uniquely identify something. For example, SNMP (the Simple Network
192       Management Protocol) uses OIDs to denote the information being
193       requested, and LDAP (the Lightweight Directory Access Protocol, RFC
194       2251) uses OIDs to denote each attribute in a directory entry.
195
196       Each level of the OID hierarchy is either zero or a positive integer.
197
198       Encoding
199           The value should be a dotted-decimal representation of the OID.
200
201               $ber->encode(
202                   OBJECT_ID => '2.5.4.0', # LDAP objectClass
203               ) or die;
204
205       Decoding
206           The value will be the dotted-decimal representation of the OID.
207
208               $ber->decode(
209                   OBJECT_ID => \$oval,
210               ) or die;
211
212   ENUM
213       The ENUMERATED type is effectively the same as the INTEGER type. It
214       exists so that friendly names can be assigned to certain integer
215       values. To be useful, you should sub-class this operator.
216
217   BIT_STRING
218       The BIT STRING type is an arbitrarily long string of bits - 0's and
219       1's.
220
221       Encoding
222           The value is a string of arbitrary 0 and 1 characters. As these are
223           packed into 8-bit octets when encoding and there may not be a
224           multiple of 8 bits to be encoded, trailing padding bits are added
225           in the encoding.
226
227               $ber->encode(
228                   BIT_STRING => '0011',
229               ) or die;
230
231       Decoding
232           The value will be a string of 0 and 1 characters. The string will
233           have the same number of bits as were encoded (the padding bits are
234           ignored.)
235
236               $ber->decode(
237                   BIT_STRING => \$bval,
238               ) or die;
239
240   BIT_STRING8
241       This is a variation of the BIT_STRING operator, which is optimized for
242       writing bit strings which are multiples of 8-bits in length. You can
243       use the BIT_STRING operator to decode BER encoded with the BIT_STRING8
244       operator (and vice-versa.)
245
246       Encoding
247           The value should be the packed bits to encode, not a string of 0
248           and 1 characters.
249
250               $ber->encode(
251                   BIT_STRING8 => pack('B8', '10110101'),
252               ) or die;
253
254       Decoding
255           The value will be the decoded packed bits.
256
257               $ber->decode(
258                   BIT_STRING8 => \$bval,
259               ) or die;
260
261   REAL
262       The REAL type encodes an floating-point number. It requires the POSIX
263       module.
264
265       Encoding
266           The value should be the number to encode.
267
268               $ber->encode(
269                   REAL => 3.14159265358979,
270               ) or die;
271
272       Decoding
273           The value will be the decoded floating-point value.
274
275               $ber->decode(
276                   REAL => \$rval,
277               );
278
279   ObjectDescriptor
280       The ObjectDescriptor type encodes an ObjectDescriptor string. It is a
281       sub-class of "STRING".
282
283   UTF8String
284       The UTF8String type encodes a string encoded in UTF-8. It is a sub-
285       class of "STRING".
286
287   NumericString
288       The NumericString type encodes a NumericString, which is defined to
289       only contain the characters 0-9 and space. It is a sub-class of
290       "STRING".
291
292   PrintableString
293       The PrintableString type encodes a PrintableString, which is defined to
294       only contain the characters A-Z, a-z, 0-9, space, and the punctuation
295       characters ()-+=:',./?. It is a sub-class of "STRING".
296
297   TeletexString/T61String
298       The TeletexString type encodes a TeletexString, which is a string
299       containing characters according to the T.61 character set. Each T.61
300       character may be one or more bytes wide. It is a sub-class of "STRING".
301
302       T61String is an alternative name for TeletexString.
303
304   VideotexString
305       The VideotexString type encodes a VideotexString, which is a string. It
306       is a sub-class of "STRING".
307
308   IA5String
309       The IA5String type encodes an IA5String. IA5 (International Alphabet 5)
310       is equivalent to US-ASCII. It is a sub-class of "STRING".
311
312   UTCTime
313       The UTCTime type encodes a UTCTime value. Note this value only
314       represents years using two digits, so it is not recommended in
315       Y2K-compliant applications. It is a sub-class of "STRING".
316
317       UTCTime values must be strings like:
318
319           yymmddHHMM[SS]Z
320       or:
321           yymmddHHMM[SS]sHHMM
322
323       Where yy is the year, mm is the month (01-12), dd is the day (01-31),
324       HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
325       seconds (00-61).
326
327       The time is either terminated by the literal character Z, or a timezone
328       offset. The "Z" character indicates Zulu time or UTC. The timezone
329       offset specifies the sign s, which is + or -, and the difference in
330       hours and minutes.
331
332   GeneralizedTime
333       The GeneralizedTime type encodes a GeneralizedTime value. Unlike
334       "UTCTime" it represents years using 4 digits, so is Y2K-compliant. It
335       is a sub-class of "STRING".
336
337       GeneralizedTime values must be strings like:
338
339           yyyymmddHHMM[SS][.U][Z]
340       or:
341           yyyymmddHHMM[SS][.U]sHHMM
342
343       Where yyyy is the year, mm is the month (01-12), dd is the day (01-31),
344       HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
345       seconds (00-61). U is the optional fractional seconds value; a comma is
346       permitted instead of a dot before this value.
347
348       The time may be terminated by the literal character Z, or a timezone
349       offset. The "Z" character indicates Zulu time or UTC. The timezone
350       offset specifies the sign s, which is + or -, and the difference in
351       hours and minutes. If there is timezone specified UTC is assumed.
352
353   GraphicString
354       The GraphicString type encodes a GraphicString value. It is a sub-class
355       of "STRING".
356
357   VisibleString/ISO646String
358       The VisibleString type encodes a VisibleString value, which is a value
359       using the ISO646 character set. It is a sub-class of "STRING".
360
361       ISO646String is an alternative name for VisibleString.
362
363   GeneralString
364       The GeneralString type encodes a GeneralString value. It is a sub-class
365       of "STRING".
366
367   UniversalString/CharacterString
368       The UniveralString type encodes a UniveralString value, which is a
369       value using the ISO10646 character set. Each character in ISO10646 is
370       4-bytes wide. It is a sub-class of "STRING".
371
372       CharacterString is an alternative name for UniversalString.
373
374   BMPString
375       The BMPString type encodes a BMPString value, which is a value using
376       the Unicode character set. Each character in the Unicode character set
377       is 2-bytes wide. It is a sub-class of "STRING".
378

CONSTRUCTED OPERATORS

380       These operators are used to build constructed types, which contain
381       values in different types, like a C structure.
382
383   SEQUENCE
384       A SEQUENCE is a complex type that contains other types, a bit like a C
385       structure. Elements inside a SEQUENCE are encoded and decoded in the
386       order given.
387
388       Encoding
389           The value should be a reference to an array containing another
390           opList which defines the elements inside the SEQUENCE.
391
392               $ber->encode(
393                   SEQUENCE => [
394                       INTEGER => 123,
395                       BOOLEAN => [ 1, 0 ],
396                   ]
397               ) or die;
398
399       Decoding
400           The value should a reference to an array that contains the opList
401           which decodes the contents of the SEQUENCE.
402
403               $ber->decode(
404                   SEQUENCE => [
405                       INTEGER => \$ival,
406                       BOOLEAN => \@bvals,
407                   ]
408               ) or die;
409
410   SET
411       A SET is an complex type that contains other types, rather like a
412       SEQUENCE. Elements inside a SET may be present in any order.
413
414       Encoding
415           The value is the same as for the SEQUENCE operator.
416
417               $ber->encode(
418                   SET => [
419                       INTEGER => 13,
420                       STRING => 'Hello',
421                   ]
422               ) or die;
423
424       Decoding
425           The value should be a reference to an equivalent opList to that
426           used to encode the SET. The ordering of the opList should not
427           matter.
428
429               $ber->decode(
430                   SET => [
431                       STRING => \$sval,
432                       INTEGER => \$ival,
433                   ]
434               ) or die;
435
436   SEQUENCE_OF
437       A SEQUENCE_OF is an ordered list of other types.
438
439       Encoding
440           The value is a ref followed by an opList. The ref must be a
441           reference to a list or a hash: if it is to a list, then the opList
442           will be repeated once for every element in the list. If it is to a
443           hash, then the opList will be repeated once for every key in the
444           hash (note that ordering of keys in a hash is not guaranteed by
445           perl.)
446
447           The remaining opList will then usually contain values which are
448           code references. If the ref is to a list, then the contents of that
449           item in the list are passed as the only argument to the code
450           reference. If the ref is to a hash, then only the key is passed to
451           the code.
452
453               @vals = ( [ 10, 'Foo' ], [ 20, 'Bar' ] ); # List of refs to lists
454               $ber->encode(
455                   SEQUENCE_OF => [ \@vals,
456                       SEQUENCE => [
457                           INTEGER => sub { $_[0][0] }, # Passed a ref to the inner list
458                           STRING => sub { $_[0][1] }, # Passed a ref to the inner list
459                       ]
460                   ]
461               ) or die;
462               %hash = ( 40 => 'Baz', 30 => 'Bletch' ); # Just a hash
463               $ber->decode(
464                   SEQUENCE_OF => [ \%hash,
465                       SEQUENCE => [
466                           INTEGER => sub { $_[0] }, # Passed the key
467                           STRING => sub { $hash{$_[0]} }, # Passed the key
468                       ]
469                   ]
470               );
471
472       Decoding
473           The value must be a reference to a list containing a ref and an
474           opList. The ref must always be a reference to a scalar. Each value
475           in the <opList> is usually a code reference. The code referenced is
476           called with the value of the ref (dereferenced); the value of the
477           ref is incremented for each item in the SEQUENCE_OF.
478
479               $ber->decode(
480                   SEQUENCE_OF => [ \$count,
481                       # In the following subs, make space at the end of an array, and
482                       # return a reference to that newly created space.
483                       SEQUENCE => [
484                           INTEGER => sub { $ival[$_[0]] = undef; \$ival[-1] },
485                           STRING => sub { $sval[$_[0]] = undef; \$sval[-1] },
486                       ]
487                   ]
488               ) or die;
489
490   SET_OF
491       A SET_OF is an unordered list. This is treated in an identical way to a
492       SEQUENCE_OF, except that no ordering should be inferred from the list
493       passed or returned.
494

SPECIAL OPERATORS

496   BER
497       It is sometimes useful to construct or deconstruct BER encodings in
498       several pieces. The BER operator lets you do this.
499
500       Encoding
501           The value should be another "Convert::BER" object, which will be
502           inserted into the buffer. If value is undefined then nothing is
503           added.
504
505               $tmp->encode(
506                   SEQUENCE => [
507                       INTEGER => 20,
508                       STRING => 'Foo',
509                   ]
510               );
511               $ber->encode(
512                   BER => $tmp,
513                   BOOLEAN => 1
514               );
515
516       Decoding
517           value should be a reference to a scalar, which will contain a
518           "Convert::BER" object. This object will contain the remainder of
519           the current sequence or set being decoded.
520
521               # After this, ber2 will contain the encoded INTEGER B<and> STRING.
522               # sval will be ignored and left undefined, but bval will be decoded. The
523               # decode of ber2 will return the integer and string values.
524               $ber->decode(
525                   SEQUENCE => [
526                       BER => \$ber2,
527                       STRING => \$sval,
528                   ],
529                   BOOLEAN => \$bval,
530               );
531               $ber2->decode(
532                   INTEGER => \$ival,
533                   STRING => \$sval2,
534               );
535
536   ANY
537       This is like the "BER" operator except that when decoding only the next
538       item is decoded and placed into the "Convert::BER" object returned.
539       There is no difference when encoding.
540
541       Decoding
542           value should be a reference to a scalar, which will contain a
543           "Convert::BER" object. This object will only contain the next
544           single item in the current sequence being decoded.
545
546               # After this, ber2 will decode further, and ival and sval
547               # will be decoded.
548               $ber->decode(
549                   INTEGER = \$ival,
550                   ANY => \$ber2,
551                   STRING => \$sval,
552               );
553
554   OPTIONAL
555       This operator allows you to specify that an element is absent from the
556       encoding.
557
558       Encoding
559           The value should be a reference to another list with another
560           opList. If all of the values of the inner opList are defined, the
561           entire OPTIONAL value will be encoded, otherwise it will be
562           omitted.
563
564               $ber->encode(
565                   SEQUENCE => [
566                       INTEGER => 16, # Will be encoded
567                       OPTIONAL => [
568                           INTEGER => undef, # Will not be encoded
569                       ],
570                       STRING => 'Foo', # Will be encoded
571                   ]
572               );
573
574       Decoding
575           The contents of value are decoded if possible, if not then decode
576           continues at the next operator-value pair.
577
578               $ber->decode(
579                   SEQUENCE => [
580                       INTEGER => \$ival1,
581                       OPTIONAL => [
582                           INTEGER => \$ival2,
583                       ],
584                       STRING => \$sval,
585                   ]
586               );
587
588   CHOICE
589       The opList is a list of alternate operator-value pairs. Only one will
590       be encoded, and only one will be decoded.
591
592       Encoding
593           A scalar at the start of the opList identifies which opList
594           alternative to use for encoding the value. A value of 0 means the
595           first one is used, 1 means the second one, etc.
596
597               # Encode the BMPString alternate of the CHOICE
598               $ber->encode(
599                   CHOICE => [ 2,
600                       PrintableString => 'Printable',
601                       TeletexString   => 'Teletex/T61',
602                       BMPString       => 'BMP/Unicode',
603                       UniversalString => 'Universal/ISO10646',
604                   ]
605               ) or die;
606
607       Decoding
608           A reference to a scalar at the start of the opList is used to store
609           which alternative is decoded (0 for the first one, 1 for the second
610           one, etc.) Pass undef instead of the ref if you don't care about
611           this, or you store all the alternate values in different variables.
612
613               # Decode the above.
614               # Afterwards, $alt will be set to 2, $str will be set to 'BMP/Unicode'.
615               $ber->decode(
616                   CHOICE => [ \$alt,
617                       PrintableString => \$str,
618                       TeletexString   => \$str,
619                       BMPString       => \$str,
620                       UniversalString => \$str,
621                   ]
622               ) or die;
623

SUB-CLASSING

680       For large applications where operators with non default tags are used a
681       lot the above mechanism can be very error-prone. For this reason,
682       "Convert::BER" may be sub-classed.
683
684       To do this the sub-class must call a static method "define". The
685       arguments to "define" is a list of arrayrefs. Each arrayref will define
686       one new operator. Each arrayref contains three values, the first is the
687       name of the operator, the second is how the data is encoded and the
688       third is the tag value. To aid with the creation of these arguments
689       "Convert::BER" exports some variables and constant subroutines.
690
691       For each operator defined by "Convert::BER", or a "Convert::BER" sub-
692       class, a scalar variable with the same name is available for import,
693       for example $INTEGER is available from "Convert::BER". And any
694       operators defined by a new sub-class will be available for import from
695       that class.  One of these variables may be used as the second element
696       of each arrayref.
697
698       "Convert::BER" also exports some constant subroutines that can be used
699       to create the tag value. The subroutines exported are:
700
701               BER_BOOLEAN
702               BER_INTEGER
703               BER_BIT_STR
704               BER_OCTET_STR
705               BER_NULL
706               BER_OBJECT_ID
707               BER_SEQUENCE
708               BER_SET
709
710               BER_UNIVERSAL
711               BER_APPLICATION
712               BER_CONTEXT
713               BER_PRIVATE
714               BER_PRIMITIVE
715               BER_CONSTRUCTOR
716
717       "Convert::BER" also provides a subroutine called "ber_tag" to calculate
718       an integer value that will be used to represent a tag. For tags with
719       values less than 30 this is not needed, but for tags >= 30 then tag
720       value passed for an operator definition must be the result of "ber_tag"
721
722       "ber_tag" takes two arguments, the first is the tag class and the
723       second is the tag value.
724
725       Using this information a sub-class of Convert::BER can be created as
726       shown below.
727
728           package Net::LDAP::BER;
729
730           use Convert::BER qw(/^(\$|BER_)/);
731
732           use strict;
733           use vars qw($VERSION @ISA);
734
735           @ISA = qw(Convert::BER);
736           $VERSION = "1.00";
737
738           Net::LDAP::BER->define(
739
740             # Name            Type      Tag
741             ########################################
742
743             [ REQ_UNBIND     => $NULL,
744                                 BER_APPLICATION                   | 0x02 ],
745
746             [ REQ_COMPARE    => $SEQUENCE,
747                                 BER_APPLICATION | BER_CONSTRUCTOR | 0x0E ],
748
749             [ REQ_ABANDON    => $INTEGER,
750                                 ber_tag(BER_APPLICATION, 0x10) ],
751           );
752
753       This will create a new class "Net::LDAP::BER" which has three new
754       operators available. This class then may be used as follows
755
756           $ber = new Net::LDAP::BER;
757
758           $ber->encode(
759               REQ_UNBIND => 0,
760               REQ_COMPARE => [
761                   REQ_ABANDON => 123,
762               ]
763           );
764
765           $ber->decode(
766               REQ_UNBIND => \$var,
767               REQ_COMPARE => [
768                   REQ_ABANDON => \$num,
769               ]
770           );
771
772       Which will encode or decode the data using the formats and tags defined
773       in the "Net::LDAP::BER" sub-class. It also helps to make the code more
774       readable.
775
776   DEFINING NEW PACKING OPERATORS
777       As well as defining new operators which inherit from existing operators
778       it is also possible to define a new operator and how data is encoded
779       and decoded. The interface for doing this is still changing but will be
780       documented here when it is done. To be continued ...
781

LIMITATIONS

783       Convert::BER cannot support tags that contain more bits than can be
784       stored in a scalar variable, typically this is 32 bits.
785
786       Convert::BER cannot support items that have a packed length which
787       cannot be stored in 32 bits.
788

BUGS

790       The "SET" decode method fails if the encoded order is different to the
791       opList order.
792

AUTHOR

794       Graham Barr <gbarr@pobox.com>
795
796       Significant POD updates from Chris Ridd
797       <Chris.Ridd@messagingdirect.com>
798

COPYRIGHT

800       Copyright (c) 1995-2000 Graham Barr. All rights reserved.  This program
801       is free software; you can redistribute it and/or modify it under the
802       same terms as Perl itself.
803

POD ERRORS

805       Hey! The above document had some coding errors, which are explained
806       below:
807
808       Around line 366:
809           You forgot a '=back' before '=head2'
810
811
812
813perl v5.36.0                      2023-01-20                            BER(3)