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".

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.

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;
    

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 ...