Convert::BER man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

BER(3)		      User Contributed Perl Documentation		BER(3)

NAME
       Convert::BER - ASN.1 Basic Encoding Rules

SYNOPSIS
	   use Convert::BER;

	   $ber = new Convert::BER;

	   $ber->encode(
	       INTEGER => 1,
	       SEQUENCE => [
		   BOOLEAN => 0,
		   STRING => "Hello",
	       ],
	       REAL => 3.7,
	   );

	   $ber->decode(
	       INTEGER => \$i,
	       SEQUENCE => [
		   BOOLEAN => \$b,
		   STRING => \$s,
	       ],
	       REAL => \$r,
	   );

DESCRIPTION
       "Convert::BER" provides an OO interface to encoding and decoding data
       using the ASN.1 Basic Encoding Rules (BER), a platform independent way
       of encoding structured binary data together with the structure.

METHODS
       new
       new ( BUFFER )
       new ( opList )
	   "new" creates a new "Convert::BER" object.

       encode ( opList )
	   Encode data in opList appending to the data in the buffer.

       decode ( opList )
	   Decode the data in the buffer as described by opList, starting
	   where the last decode finished or position set by "pos".

       buffer ( [ BUFFER ] )
	   Return the buffer contents. If BUFFER is specified set the buffer
	   contents and reset pos to zero.

       pos ( [ POS ] )
	   Without any arguments "pos" returns the offset where the last
	   decode finished, or the last offset set by "pos". If POS is
	   specified then POS will be where the next decode starts.

       tag ( )
	   Returns the tag at the current position in the buffer.

       length ( )
	   Returns the length of the buffer.

       error ( )
	   Returns the error message associated with the last method, if any.
	   This value is not automatically reset. If "encode" or "decode"
	   returns undef, check this.

       dump ( [ FH ] )
	   Dump the buffer to the filehandle "FH", or STDERR if not specified.
	   The output contains the hex dump of each element, and an ASN.1-like
	   text representation of that element.

       hexdump	( [ FH ] )
	   Dump the buffer to the filehandle "FH", or STDERR if not specified.
	   The output is hex with the possibly-printable text alongside.

IO METHODS
       read ( IO )
       write ( IO )
       recv ( SOCK )
       send ( SOCK [, ADDR ] )

OPLIST
       An opList is a list of operator-value pairs. An operator can be any of
       those defined below, or any defined by sub-classing "Convert::BER",
       which will probably be derived from the primitives given here.

       The values depend on whether BER is being encoded or decoded:

       Encoding
	   If the value is a scalar, just encode it. If the value is a
	   reference to a list, then encode each item in the list in turn. If
	   the value is a code reference, then execute the code. If the
	   returned value is a scalar, encode that value. If the returned
	   value is a reference to a list, encode each item in the list in
	   turn.

       Decoding
	   If the value is a reference to a scalar, decode the value into the
	   scalar. If the value is a reference to a list, then decode all the
	   items of this type into the list. Note that there must be at least
	   one item to decode, otherwise the decode will fail. If the value is
	   a code reference, then execute the code and decode the value into
	   the reference returned from the evaluated code.

PRIMITIVE OPERATORS
       These operators encode and decode the basic primitive types defined by
       BER.

   BOOLEAN
       A BOOLEAN value is either true or false.

       Encoding
	   The value is tested for boolean truth, and encoded appropriately.

	       # Encode a TRUE value
	       $ber->encode(
		   BOOLEAN => 1,
	       ) or die;

       Decoding
	   The decoded values will be either 1 or 0.

	       # Decode a boolean value into $bval
	       $ber->decode(
		   BOOLEAN => \$bval,
	       ) or die;

   INTEGER
       An INTEGER value is either a positive whole number, or a negative whole
       number, or zero. Numbers can either be native perl integers, or values
       of the "Math::BigInt" class.

       Encoding
	   The value is the integer value to be encoded.

	       $ber->encode(
		   INTEGER => -123456,
	       ) or die;

       Decoding
	   The value will be the decoded integer value.

	       $ber->decode(
		   INTEGER => \$ival,
	       ) or die;

   STRING
       This is an OCTET STRING, which is an arbitrarily long binary value.

       Encoding
	   The value contains the binary value to be encoded.

	       $ber->encode(
		   STRING => "\xC0First character is hex C0",
	       ) or die;

       Decoding
	   The value will be the binary bytes.

	       $ber->decode(
		   STRING => \$sval,
	       ) or die;

   NULL
       There is no value for NULL. You often use NULL in ASN.1 when you want
       to denote that something else is absent rather than just not encoding
       the 'something else'.

       Encoding
	   The values are ignored, but must be present.

	       $ber->encode(
		   NULL => undef,
	       ) or die;

       Decoding
	   Dummy values are stored in the returned values, as though they were
	   present in the encoding.

	       $ber->decode(
		   NULL => \$nval,
	       ) or die;

   OBJECT_ID
       An OBJECT_ID value is an OBJECT IDENTIFIER (also called an OID). This
       is a hierarchically structured value that is used in protocols to
       uniquely identify something. For example, SNMP (the Simple Network
       Management Protocol) uses OIDs to denote the information being
       requested, and LDAP (the Lightweight Directory Access Protocol, RFC
       2251) uses OIDs to denote each attribute in a directory entry.

       Each level of the OID hierarchy is either zero or a positive integer.

       Encoding
	   The value should be a dotted-decimal representation of the OID.

	       $ber->encode(
		   OBJECT_ID => '2.5.4.0', # LDAP objectClass
	       ) or die;

       Decoding
	   The value will be the dotted-decimal representation of the OID.

	       $ber->decode(
		   OBJECT_ID => \$oval,
	       ) or die;

   ENUM
       The ENUMERATED type is effectively the same as the INTEGER type. It
       exists so that friendly names can be assigned to certain integer
       values. To be useful, you should sub-class this operator.

   BIT_STRING
       The BIT STRING type is an arbitrarily long string of bits - 0's and
       1's.

       Encoding
	   The value is a string of arbitrary 0 and 1 characters. As these are
	   packed into 8-bit octets when encoding and there may not be a
	   multiple of 8 bits to be encoded, trailing padding bits are added
	   in the encoding.

	       $ber->encode(
		   BIT_STRING => '0011',
	       ) or die;

       Decoding
	   The value will be a string of 0 and 1 characters. The string will
	   have the same number of bits as were encoded (the padding bits are
	   ignored.)

	       $ber->decode(
		   BIT_STRING => \$bval,
	       ) or die;

   BIT_STRING8
       This is a variation of the BIT_STRING operator, which is optimized for
       writing bit strings which are multiples of 8-bits in length. You can
       use the BIT_STRING operator to decode BER encoded with the BIT_STRING8
       operator (and vice-versa.)

       Encoding
	   The value should be the packed bits to encode, not a string of 0
	   and 1 characters.

	       $ber->encode(
		   BIT_STRING8 => pack('B8', '10110101'),
	       ) or die;

       Decoding
	   The value will be the decoded packed bits.

	       $ber->decode(
		   BIT_STRING8 => \$bval,
	       ) or die;

   REAL
       The REAL type encodes an floating-point number. It requires the POSIX
       module.

       Encoding
	   The value should be the number to encode.

	       $ber->encode(
		   REAL => 3.14159265358979,
	       ) or die;

       Decoding
	   The value will be the decoded floating-point value.

	       $ber->decode(
		   REAL => \$rval,
	       );

   ObjectDescriptor
       The ObjectDescriptor type encodes an ObjectDescriptor string. It is a
       sub-class of "STRING".

   UTF8String
       The UTF8String type encodes a string encoded in UTF-8. It is a sub-
       class of "STRING".

   NumericString
       The NumericString type encodes a NumericString, which is defined to
       only contain the characters 0-9 and space. It is a sub-class of
       "STRING".

   PrintableString
       The PrintableString type encodes a PrintableString, which is defined to
       only contain the characters A-Z, a-z, 0-9, space, and the punctuation
       characters ()-+=:',./?. It is a sub-class of "STRING".

   TeletexString/T61String
       The TeletexString type encodes a TeletexString, which is a string
       containing characters according to the T.61 character set. Each T.61
       character may be one or more bytes wide. It is a sub-class of "STRING".

       T61String is an alternative name for TeletexString.

   VideotexString
       The VideotexString type encodes a VideotexString, which is a string. It
       is a sub-class of "STRING".

   IA5String
       The IA5String type encodes an IA5String. IA5 (International Alphabet 5)
       is equivalent to US-ASCII. It is a sub-class of "STRING".

   UTCTime
       The UTCTime type encodes a UTCTime value. Note this value only
       represents years using two digits, so it is not recommended in
       Y2K-compliant applications. It is a sub-class of "STRING".

       UTCTime values must be strings like:

	   yymmddHHMM[SS]Z
       or:
	   yymmddHHMM[SS]sHHMM

       Where yy is the year, mm is the month (01-12), dd is the day (01-31),
       HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
       seconds (00-61).

       The time is either terminated by the literal character Z, or a timezone
       offset. The "Z" character indicates Zulu time or UTC. The timezone
       offset specifies the sign s, which is + or -, and the difference in
       hours and minutes.

   GeneralizedTime
       The GeneralizedTime type encodes a GeneralizedTime value. Unlike
       "UTCTime" it represents years using 4 digits, so is Y2K-compliant. It
       is a sub-class of "STRING".

       GeneralizedTime values must be strings like:

	   yyyymmddHHMM[SS][.U][Z]
       or:
	   yyyymmddHHMM[SS][.U]sHHMM

       Where yyyy is the year, mm is the month (01-12), dd is the day (01-31),
       HH is the hour (00-23), MM is the minutes (00-60). SS is the optional
       seconds (00-61). U is the optional fractional seconds value; a comma is
       permitted instead of a dot before this value.

       The time may be terminated by the literal character Z, or a timezone
       offset. The "Z" character indicates Zulu time or UTC. The timezone
       offset specifies the sign s, which is + or -, and the difference in
       hours and minutes. If there is timezone specified UTC is assumed.

   GraphicString
       The GraphicString type encodes a GraphicString value. It is a sub-class
       of "STRING".

   VisibleString/ISO646String
       The VisibleString type encodes a VisibleString value, which is a value
       using the ISO646 character set. It is a sub-class of "STRING".

       ISO646String is an alternative name for VisibleString.

   GeneralString
       The GeneralString type encodes a GeneralString value. It is a sub-class
       of "STRING".

   UniversalString/CharacterString
       The UniveralString type encodes a UniveralString value, which is a
       value using the ISO10646 character set. Each character in ISO10646 is
       4-bytes wide. It is a sub-class of "STRING".

       CharacterString is an alternative name for UniversalString.

   BMPString
       The BMPString type encodes a BMPString value, which is a value using
       the Unicode character set. Each character in the Unicode character set
       is 2-bytes wide. It is a sub-class of "STRING".

CONSTRUCTED OPERATORS
       These operators are used to build constructed types, which contain
       values in different types, like a C structure.

   SEQUENCE
       A SEQUENCE is a complex type that contains other types, a bit like a C
       structure. Elements inside a SEQUENCE are encoded and decoded in the
       order given.

       Encoding
	   The value should be a reference to an array containing another
	   opList which defines the elements inside the SEQUENCE.

	       $ber->encode(
		   SEQUENCE => [
		       INTEGER => 123,
		       BOOLEAN => [ 1, 0 ],
		   ]
	       ) or die;

       Decoding
	   The value should a reference to an array that contains the opList
	   which decodes the contents of the SEQUENCE.

	       $ber->decode(
		   SEQUENCE => [
		       INTEGER => \$ival,
		       BOOLEAN => \@bvals,
		   ]
	       ) or die;

   SET
       A SET is an complex type that contains other types, rather like a
       SEQUENCE. Elements inside a SET may be present in any order.

       Encoding
	   The value is the same as for the SEQUENCE operator.

	       $ber->encode(
		   SET => [
		       INTEGER => 13,
		       STRING => 'Hello',
		   ]
	       ) or die;

       Decoding
	   The value should be a reference to an equivalent opList to that
	   used to encode the SET. The ordering of the opList should not
	   matter.

	       $ber->decode(
		   SET => [
		       STRING => \$sval,
		       INTEGER => \$ival,
		   ]
	       ) or die;

   SEQUENCE_OF
       A SEQUENCE_OF is an ordered list of other types.

       Encoding
	   The value is a ref followed by an opList. The ref must be a
	   reference to a list or a hash: if it is to a list, then the opList
	   will be repeated once for every element in the list. If it is to a
	   hash, then the opList will be repeated once for every key in the
	   hash (note that ordering of keys in a hash is not guaranteed by
	   perl.)

	   The remaining opList will then usually contain values which are
	   code references. If the ref is to a list, then the contents of that
	   item in the list are passed as the only argument to the code
	   reference. If the ref is to a hash, then only the key is passed to
	   the code.

	       @vals = ( [ 10, 'Foo' ], [ 20, 'Bar' ] ); # List of refs to lists
	       $ber->encode(
		   SEQUENCE_OF => [ \@vals,
		       SEQUENCE => [
			   INTEGER => sub { $_[0][0] }, # Passed a ref to the inner list
			   STRING => sub { $_[0][1] }, # Passed a ref to the inner list
		       ]
		   ]
	       ) or die;
	       %hash = ( 40 => 'Baz', 30 => 'Bletch' ); # Just a hash
	       $ber->decode(
		   SEQUENCE_OF => [ \%hash,
		       SEQUENCE => [
			   INTEGER => sub { $_[0] }, # Passed the key
			   STRING => sub { $hash{$_[0]} }, # Passed the key
		       ]
		   ]
	       );

       Decoding
	   The value must be a reference to a list containing a ref and an
	   opList. The ref must always be a reference to a scalar. Each value
	   in the <opList> is usually a code reference. The code referenced is
	   called with the value of the ref (dereferenced); the value of the
	   ref is incremented for each item in the SEQUENCE_OF.

	       $ber->decode(
		   SEQUENCE_OF => [ \$count,
		       # In the following subs, make space at the end of an array, and
		       # return a reference to that newly created space.
		       SEQUENCE => [
			   INTEGER => sub { $ival[$_[0]] = undef; \$ival[-1] },
			   STRING => sub { $sval[$_[0]] = undef; \$sval[-1] },
		       ]
		   ]
	       ) or die;

   SET_OF
       A SET_OF is an unordered list. This is treated in an identical way to a
       SEQUENCE_OF, except that no ordering should be inferred from the list
       passed or returned.

SPECIAL OPERATORS
   BER
       It is sometimes useful to construct or deconstruct BER encodings in
       several pieces. The BER operator lets you do this.

       Encoding
	   The value should be another "Convert::BER" object, which will be
	   inserted into the buffer. If value is undefined then nothing is
	   added.

	       $tmp->encode(
		   SEQUENCE => [
		       INTEGER => 20,
		       STRING => 'Foo',
		   ]
	       );
	       $ber->encode(
		   BER => $tmp,
		   BOOLEAN => 1
	       );

       Decoding
	   value should be a reference to a scalar, which will contain a
	   "Convert::BER" object. This object will contain the remainder of
	   the current sequence or set being decoded.

	       # After this, ber2 will contain the encoded INTEGER B<and> STRING.
	       # sval will be ignored and left undefined, but bval will be decoded. The
	       # decode of ber2 will return the integer and string values.
	       $ber->decode(
		   SEQUENCE => [
		       BER => \$ber2,
		       STRING => \$sval,
		   ],
		   BOOLEAN => \$bval,
	       );
	       $ber2->decode(
		   INTEGER => \$ival,
		   STRING => \$sval2,
	       );

   ANY
       This is like the "BER" operator except that when decoding only the next
       item is decoded and placed into the "Convert::BER" object returned.
       There is no difference when encoding.

       Decoding
	   value should be a reference to a scalar, which will contain a
	   "Convert::BER" object. This object will only contain the next
	   single item in the current sequence being decoded.

	       # After this, ber2 will decode further, and ival and sval
	       # will be decoded.
	       $ber->decode(
		   INTEGER = \$ival,
		   ANY => \$ber2,
		   STRING => \$sval,
	       );

   OPTIONAL
       This operator allows you to specify that an element is absent from the
       encoding.

       Encoding
	   The value should be a reference to another list with another
	   opList. If all of the values of the inner opList are defined, the
	   entire OPTIONAL value will be encoded, otherwise it will be
	   omitted.

	       $ber->encode(
		   SEQUENCE => [
		       INTEGER => 16, # Will be encoded
		       OPTIONAL => [
			   INTEGER => undef, # Will not be encoded
		       ],
		       STRING => 'Foo', # Will be encoded
		   ]
	       );

       Decoding
	   The contents of value are decoded if possible, if not then decode
	   continues at the next operator-value pair.

	       $ber->decode(
		   SEQUENCE => [
		       INTEGER => \$ival1,
		       OPTIONAL => [
			   INTEGER => \$ival2,
		       ],
		       STRING => \$sval,
		   ]
	       );

   CHOICE
       The opList is a list of alternate operator-value pairs. Only one will
       be encoded, and only one will be decoded.

       Encoding
	   A scalar at the start of the opList identifies which opList
	   alternative to use for encoding the value. A value of 0 means the
	   first one is used, 1 means the second one, etc.

	       # Encode the BMPString alternate of the CHOICE
	       $ber->encode(
		   CHOICE => [ 2,
		       PrintableString => 'Printable',
		       TeletexString   => 'Teletex/T61',
		       BMPString       => 'BMP/Unicode',
		       UniversalString => 'Universal/ISO10646',
		   ]
	       ) or die;

       Decoding
	   A reference to a scalar at the start of the opList is used to store
	   which alternative is decoded (0 for the first one, 1 for the second
	   one, etc.) Pass undef instead of the ref if you don't care about
	   this, or you store all the alternate values in different variables.

	       # Decode the above.
	       # Afterwards, $alt will be set to 2, $str will be set to 'BMP/Unicode'.
	       $ber->decode(
		   CHOICE => [ \$alt,
		       PrintableString => \$str,
		       TeletexString   => \$str,
		       BMPString       => \$str,
		       UniversalString => \$str,
		   ]
	       ) or die;

TAGS
       In BER everything being encoded has a tag, a length, and a value.
       Normally the tag is derived from the operator - so INTEGER has a
       different tag from a BOOLEAN, for instance.

       In some applications it is necessary to change the tags used. For
       example, a SET may need to contain two different INTEGER values. Tags
       may be changed in two ways, either IMPLICITly or EXPLICITly. With
       IMPLICIT tagging, the new tag completely replaces the old tag. With
       EXPLICIT tagging, the new tag is used as well as the old tag.

       "Convert::BER" supports two ways of using IMPLICIT tagging. One method
       is to sub-class "Convert::BER", which is described in the next section.
       For small applications or those that think sub-classing is just too
       much then the operator may be passed an arrayref. The array must
       contain two elements, the first is the usual operator name and the
       second is the tag value to use, as shown below.

	   $ber->encode(
	       [ SEQUENCE => 0x34 ] => [
		   INTEGER => 10,
		   STRING  => "A"
	       ]
	   ) or die;

       This will encode a sequence, with a tag value of 0x34, which will
       contain and integer and a string which will have their default tag
       values.

       You may wish to construct your tags using some pre-defined functions
       such as &Convert::BER::BER_APPLICATION, &Convert::BER::BER_CONTEXT,
       etc, instead of calculating the tag values yourself.

       To use EXPLICIT tagging, enclose the original element in a SEQUENCE,
       and just override the SEQUENCE's tag as above. Don't forget to set the
       constructed bit using &Convert::BER::BER_CONSTRUCTOR. For example, the
       ASN.1 definition:

	   Foo ::= SEQUENCE {
	       [0] EXPLICIT INTEGER,
	       INTEGER
	   }

       might be encoded using this:

	   $ber->encode(
	       SEQUENCE => [
		   [ SEQUENCE => &Convert::BER::BER_CONTEXT |
				 &Convert::BER::BER_CONSTRUCTOR | 0 ] => [
		       INTEGER => 10,
		   ],
		   INTEGER => 11,
	       ],
	   ) or die;

SUB-CLASSING
       For large applications where operators with non default tags are used a
       lot the above mechanism can be very error-prone. For this reason,
       "Convert::BER" may be sub-classed.

       To do this the sub-class must call a static method "define". The
       arguments to "define" is a list of arrayrefs. Each arrayref will define
       one new operator. Each arrayref contains three values, the first is the
       name of the operator, the second is how the data is encoded and the
       third is the tag value. To aid with the creation of these arguments
       "Convert::BER" exports some variables and constant subroutines.

       For each operator defined by "Convert::BER", or a "Convert::BER" sub-
       class, a scalar variable with the same name is available for import,
       for example $INTEGER is available from "Convert::BER". And any
       operators defined by a new sub-class will be available for import from
       that class.  One of these variables may be used as the second element
       of each arrayref.

       "Convert::BER" also exports some constant subroutines that can be used
       to create the tag value. The subroutines exported are:

	       BER_BOOLEAN
	       BER_INTEGER
	       BER_BIT_STR
	       BER_OCTET_STR
	       BER_NULL
	       BER_OBJECT_ID
	       BER_SEQUENCE
	       BER_SET

	       BER_UNIVERSAL
	       BER_APPLICATION
	       BER_CONTEXT
	       BER_PRIVATE
	       BER_PRIMITIVE
	       BER_CONSTRUCTOR

       "Convert::BER" also provides a subroutine called "ber_tag" to calculate
       an integer value that will be used to represent a tag. For tags with
       values less than 30 this is not needed, but for tags >= 30 then tag
       value passed for an operator definition must be the result of "ber_tag"

       "ber_tag" takes two arguments, the first is the tag class and the
       second is the tag value.

       Using this information a sub-class of Convert::BER can be created as
       shown below.

	   package Net::LDAP::BER;

	   use Convert::BER qw(/^(\$|BER_)/);

	   use strict;
	   use vars qw($VERSION @ISA);

	   @ISA = qw(Convert::BER);
	   $VERSION = "1.00";

	   Net::LDAP::BER->define(

	     # Name	       Type	 Tag
	     ########################################

	     [ REQ_UNBIND     => $NULL,
				 BER_APPLICATION		   | 0x02 ],

	     [ REQ_COMPARE    => $SEQUENCE,
				 BER_APPLICATION | BER_CONSTRUCTOR | 0x0E ],

	     [ REQ_ABANDON    => $INTEGER,
				 ber_tag(BER_APPLICATION, 0x10) ],
	   );

       This will create a new class "Net::LDAP::BER" which has three new
       operators available. This class then may be used as follows

	   $ber = new Net::LDAP::BER;

	   $ber->encode(
	       REQ_UNBIND => 0,
	       REQ_COMPARE => [
		   REQ_ABANDON => 123,
	       ]
	   );

	   $ber->decode(
	       REQ_UNBIND => \$var,
	       REQ_COMPARE => [
		   REQ_ABANDON => \$num,
	       ]
	   );

       Which will encode or decode the data using the formats and tags defined
       in the "Net::LDAP::BER" sub-class. It also helps to make the code more
       readable.

   DEFINING NEW PACKING OPERATORS
       As well as defining new operators which inherit from existing operators
       it is also possible to define a new operator and how data is encoded
       and decoded. The interface for doing this is still changing but will be
       documented here when it is done. To be continued ...

LIMITATIONS
       Convert::BER cannot support tags that contain more bits than can be
       stored in a scalar variable, typically this is 32 bits.

       Convert::BER cannot support items that have a packed length which
       cannot be stored in 32 bits.

BUGS
       The "SET" decode method fails if the encoded order is different to the
       opList order.

AUTHOR
       Graham Barr <gbarr@pobox.com>

       Significant POD updates from Chris Ridd
       <Chris.Ridd@messagingdirect.com>

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

POD ERRORS
       Hey! The above document had some coding errors, which are explained
       below:

       Around line 364:
	   You forgot a '=back' before '=head2'

perl v5.14.0			  2001-03-21				BER(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net