.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "BER 3pm"
.TH BER 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Convert::BER \- ASN.1 Basic Encoding Rules
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Convert::BER;
\&    
\&    $ber = new Convert::BER;
\&    
\&    $ber\->encode(
\&        INTEGER => 1,
\&        SEQUENCE => [
\&            BOOLEAN => 0,
\&            STRING => "Hello",
\&        ],
\&        REAL => 3.7,
\&    );
\&    
\&    $ber\->decode(
\&        INTEGER => \e$i,
\&        SEQUENCE => [
\&            BOOLEAN => \e$b,
\&            STRING => \e$s,
\&        ],
\&        REAL => \e$r,
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1WARNING\s0\fR this module is no longer supported, See Convert::ASN1
.PP
\&\f(CW\*(C`Convert::BER\*(C'\fR provides an \s-1OO\s0 interface to encoding and decoding data
using the \s-1ASN.1\s0 Basic Encoding Rules (\s-1BER\s0), a platform independent way
of encoding structured binary data together with the structure.
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
.PD 0
.IP "new ( \s-1BUFFER\s0 )" 4
.IX Item "new ( BUFFER )"
.IP "new ( opList )" 4
.IX Item "new ( opList )"
.PD
\&\f(CW\*(C`new\*(C'\fR creates a new \f(CW\*(C`Convert::BER\*(C'\fR object.
.IP "encode ( opList )" 4
.IX Item "encode ( opList )"
Encode data in \fIopList\fR appending to the data in the buffer.
.IP "decode ( opList )" 4
.IX Item "decode ( opList )"
Decode the data in the buffer as described by \fIopList\fR, starting
where the last decode finished or position set by \f(CW\*(C`pos\*(C'\fR.
.IP "buffer ( [ \s-1BUFFER\s0 ] )" 4
.IX Item "buffer ( [ BUFFER ] )"
Return the buffer contents. If \fI\s-1BUFFER\s0\fR is specified set the buffer
contents and reset pos to zero.
.IP "pos ( [ \s-1POS\s0 ] )" 4
.IX Item "pos ( [ POS ] )"
Without any arguments \f(CW\*(C`pos\*(C'\fR returns the offset where the last decode
finished, or the last offset set by \f(CW\*(C`pos\*(C'\fR. If \fI\s-1POS\s0\fR is specified
then \fI\s-1POS\s0\fR will be where the next decode starts.
.IP "tag ( )" 4
.IX Item "tag ( )"
Returns the tag at the current position in the buffer.
.IP "length ( )" 4
.IX Item "length ( )"
Returns the length of the buffer.
.IP "error ( )" 4
.IX Item "error ( )"
Returns the error message associated with the last method, if
any. This value is not automatically reset. If \f(CW\*(C`encode\*(C'\fR or
\&\f(CW\*(C`decode\*(C'\fR returns undef, check this.
.IP "dump ( [ \s-1FH\s0 ] )" 4
.IX Item "dump ( [ FH ] )"
Dump the buffer to the filehandle \f(CW\*(C`FH\*(C'\fR, or \s-1STDERR\s0 if not specified. The
output contains the hex dump of each element, and an \s-1ASN\s0.1\-like text
representation of that element.
.IP "hexdump  ( [ \s-1FH\s0 ] )" 4
.IX Item "hexdump ( [ FH ] )"
Dump the buffer to the filehandle \f(CW\*(C`FH\*(C'\fR, or \s-1STDERR\s0 if not specified. The
output is hex with the possibly-printable text alongside.
.SH "IO METHODS"
.IX Header "IO METHODS"
.IP "read ( \s-1IO\s0 )" 4
.IX Item "read ( IO )"
.PD 0
.IP "write ( \s-1IO\s0 )" 4
.IX Item "write ( IO )"
.IP "recv ( \s-1SOCK\s0 )" 4
.IX Item "recv ( SOCK )"
.IP "send ( \s-1SOCK\s0 [, \s-1ADDR\s0 ] )" 4
.IX Item "send ( SOCK [, ADDR ] )"
.PD
.SH "OPLIST"
.IX Header "OPLIST"
An \fIopList\fR is a list of \fIoperator\fR\-\fIvalue\fR pairs. An operator can
be any of those defined below, or any defined by sub-classing
\&\f(CW\*(C`Convert::BER\*(C'\fR, which will probably be derived from the primitives
given here.
.PP
The \fIvalue\fRs depend on whether \s-1BER\s0 is being encoded or decoded:
.IP "Encoding" 4
.IX Item "Encoding"
If the \fIvalue\fR is a scalar, just encode it. If the \fIvalue\fR is a
reference to a list, then encode each item in the list in turn. If the
\&\fIvalue\fR 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.
.IP "Decoding" 4
.IX Item "Decoding"
If the \fIvalue\fR is a reference to a scalar, decode the value into the
scalar. If the \fIvalue\fR 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 \fIvalue\fR is a
code reference, then execute the code and decode the value into the
reference returned from the evaluated code.
.SH "PRIMITIVE OPERATORS"
.IX Header "PRIMITIVE OPERATORS"
These operators encode and decode the basic primitive types defined by
\&\s-1BER.\s0
.SS "\s-1BOOLEAN\s0"
.IX Subsection "BOOLEAN"
A \s-1BOOLEAN\s0 value is either true or false.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR is tested for boolean truth, and encoded appropriately.
.Sp
.Vb 4
\&    # Encode a TRUE value
\&    $ber\->encode(
\&        BOOLEAN => 1,
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The decoded \fIvalue\fRs will be either 1 or 0.
.Sp
.Vb 4
\&    # Decode a boolean value into $bval
\&    $ber\->decode(
\&        BOOLEAN => \e$bval,
\&    ) or die;
.Ve
.SS "\s-1INTEGER\s0"
.IX Subsection "INTEGER"
An \s-1INTEGER\s0 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 \f(CW\*(C`Math::BigInt\*(C'\fR class.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR is the integer value to be encoded.
.Sp
.Vb 3
\&    $ber\->encode(
\&        INTEGER => \-123456,
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be the decoded integer value.
.Sp
.Vb 3
\&    $ber\->decode(
\&        INTEGER => \e$ival,
\&    ) or die;
.Ve
.SS "\s-1STRING\s0"
.IX Subsection "STRING"
This is an \s-1OCTET STRING,\s0 which is an arbitrarily long binary value.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR contains the binary value to be encoded.
.Sp
.Vb 3
\&    $ber\->encode(
\&        STRING => "\exC0First character is hex C0",
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be the binary bytes.
.Sp
.Vb 3
\&    $ber\->decode(
\&        STRING => \e$sval,
\&    ) or die;
.Ve
.SS "\s-1NULL\s0"
.IX Subsection "NULL"
There is no value for \s-1NULL.\s0 You often use \s-1NULL\s0 in \s-1ASN.1\s0 when you want
to denote that something else is absent rather than just not encoding
the 'something else'.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fRs are ignored, but must be present.
.Sp
.Vb 3
\&    $ber\->encode(
\&        NULL => undef,
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
Dummy values are stored in the returned \fIvalue\fRs, as though they were
present in the encoding.
.Sp
.Vb 3
\&    $ber\->decode(
\&        NULL => \e$nval,
\&    ) or die;
.Ve
.SS "\s-1OBJECT_ID\s0"
.IX Subsection "OBJECT_ID"
An \s-1OBJECT_ID\s0 value is an \s-1OBJECT IDENTIFIER\s0 (also called an \s-1OID\s0). This
is a hierarchically structured value that is used in protocols to
uniquely identify something. For example, \s-1SNMP\s0 (the Simple Network
Management Protocol) uses OIDs to denote the information being
requested, and \s-1LDAP\s0 (the Lightweight Directory Access Protocol, \s-1RFC
2251\s0) uses OIDs to denote each attribute in a directory entry.
.PP
Each level of the \s-1OID\s0 hierarchy is either zero or a positive integer.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be a dotted-decimal representation of the \s-1OID.\s0
.Sp
.Vb 3
\&    $ber\->encode(
\&        OBJECT_ID => \*(Aq2.5.4.0\*(Aq, # LDAP objectClass
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be the dotted-decimal representation of the \s-1OID.\s0
.Sp
.Vb 3
\&    $ber\->decode(
\&        OBJECT_ID => \e$oval,
\&    ) or die;
.Ve
.SS "\s-1ENUM\s0"
.IX Subsection "ENUM"
The \s-1ENUMERATED\s0 type is effectively the same as the \s-1INTEGER\s0 type. It
exists so that friendly names can be assigned to certain integer
values. To be useful, you should sub-class this operator.
.SS "\s-1BIT_STRING\s0"
.IX Subsection "BIT_STRING"
The \s-1BIT STRING\s0 type is an arbitrarily long string of bits \- \f(CW0\fR's and
\&\f(CW1\fR's.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR is a string of arbitrary \f(CW0\fR and \f(CW1\fR 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.
.Sp
.Vb 3
\&    $ber\->encode(
\&        BIT_STRING => \*(Aq0011\*(Aq,
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be a string of \f(CW0\fR and \f(CW1\fR characters. The string
will have the same number of bits as were encoded (the padding bits
are ignored.)
.Sp
.Vb 3
\&    $ber\->decode(
\&        BIT_STRING => \e$bval,
\&    ) or die;
.Ve
.SS "\s-1BIT_STRING8\s0"
.IX Subsection "BIT_STRING8"
This is a variation of the \s-1BIT_STRING\s0 operator, which is optimized for
writing bit strings which are multiples of 8\-bits in length. You can
use the \s-1BIT_STRING\s0 operator to decode \s-1BER\s0 encoded with the \s-1BIT_STRING8\s0
operator (and vice-versa.)
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be the packed bits to encode, \fBnot\fR a string of
\&\f(CW0\fR and \f(CW1\fR characters.
.Sp
.Vb 3
\&    $ber\->encode(
\&        BIT_STRING8 => pack(\*(AqB8\*(Aq, \*(Aq10110101\*(Aq),
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be the decoded packed bits.
.Sp
.Vb 3
\&    $ber\->decode(
\&        BIT_STRING8 => \e$bval,
\&    ) or die;
.Ve
.SS "\s-1REAL\s0"
.IX Subsection "REAL"
The \s-1REAL\s0 type encodes an floating-point number. It requires the \s-1POSIX\s0
module.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be the number to encode.
.Sp
.Vb 3
\&    $ber\->encode(
\&        REAL => 3.14159265358979,
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR will be the decoded floating-point value.
.Sp
.Vb 3
\&    $ber\->decode(
\&        REAL => \e$rval,
\&    );
.Ve
.SS "ObjectDescriptor"
.IX Subsection "ObjectDescriptor"
The ObjectDescriptor type encodes an ObjectDescriptor string. It is a
sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "UTF8String"
.IX Subsection "UTF8String"
The UTF8String type encodes a string encoded in \s-1UTF\-8.\s0 It is a
sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "NumericString"
.IX Subsection "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
\&\f(CW\*(C`STRING\*(C'\fR.
.SS "PrintableString"
.IX Subsection "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 \f(CW\*(C`STRING\*(C'\fR.
.SS "TeletexString/T61String"
.IX Subsection "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
\&\f(CW\*(C`STRING\*(C'\fR.
.PP
T61String is an alternative name for TeletexString.
.SS "VideotexString"
.IX Subsection "VideotexString"
The VideotexString type encodes a VideotexString, which is a
string. It is a sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "IA5String"
.IX Subsection "IA5String"
The IA5String type encodes an IA5String. \s-1IA5\s0 (International Alphabet
5) is equivalent to US-ASCII. It is a sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "UTCTime"
.IX Subsection "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 \f(CW\*(C`STRING\*(C'\fR.
.PP
UTCTime values must be strings like:
.PP
.Vb 3
\&    yymmddHHMM[SS]Z
\&or:
\&    yymmddHHMM[SS]sHHMM
.Ve
.PP
Where yy is the year, mm is the month (01\-12), dd is the day (01\-31),
\&\s-1HH\s0 is the hour (00\-23), \s-1MM\s0 is the minutes (00\-60). \s-1SS\s0 is the optional
seconds (00\-61).
.PP
The time is either terminated by the literal character Z, or a
timezone offset. The \*(L"Z\*(R" character indicates Zulu time or \s-1UTC.\s0 The
timezone offset specifies the sign s, which is + or \-, and the
difference in hours and minutes.
.SS "GeneralizedTime"
.IX Subsection "GeneralizedTime"
The GeneralizedTime type encodes a GeneralizedTime value. Unlike
\&\f(CW\*(C`UTCTime\*(C'\fR it represents years using 4 digits, so is Y2K\-compliant. It
is a sub-class of \f(CW\*(C`STRING\*(C'\fR.
.PP
GeneralizedTime values must be strings like:
.PP
.Vb 3
\&    yyyymmddHHMM[SS][.U][Z]
\&or:
\&    yyyymmddHHMM[SS][.U]sHHMM
.Ve
.PP
Where yyyy is the year, mm is the month (01\-12), dd is the day
(01\-31), \s-1HH\s0 is the hour (00\-23), \s-1MM\s0 is the minutes (00\-60). \s-1SS\s0 is the
optional seconds (00\-61). U is the optional fractional seconds value;
a comma is permitted instead of a dot before this value.
.PP
The time may be terminated by the literal character Z, or a timezone
offset. The \*(L"Z\*(R" character indicates Zulu time or \s-1UTC.\s0 The timezone
offset specifies the sign s, which is + or \-, and the difference in
hours and minutes. If there is timezone specified \s-1UTC\s0 is assumed.
.SS "GraphicString"
.IX Subsection "GraphicString"
The GraphicString type encodes a GraphicString value. It is a
sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "VisibleString/ISO646String"
.IX Subsection "VisibleString/ISO646String"
The VisibleString type encodes a VisibleString value, which is a value
using the \s-1ISO646\s0 character set. It is a sub-class of \f(CW\*(C`STRING\*(C'\fR.
.PP
ISO646String is an alternative name for VisibleString.
.SS "GeneralString"
.IX Subsection "GeneralString"
The GeneralString type encodes a GeneralString value. It is a
sub-class of \f(CW\*(C`STRING\*(C'\fR.
.SS "UniversalString/CharacterString"
.IX Subsection "UniversalString/CharacterString"
The UniveralString type encodes a UniveralString value, which is a
value using the \s-1ISO10646\s0 character set. Each character in \s-1ISO10646\s0 is
4\-bytes wide. It is a sub-class of \f(CW\*(C`STRING\*(C'\fR.
.PP
CharacterString is an alternative name for UniversalString.
.SS "BMPString"
.IX Subsection "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 \f(CW\*(C`STRING\*(C'\fR.
.SH "CONSTRUCTED OPERATORS"
.IX Header "CONSTRUCTED OPERATORS"
These operators are used to build constructed types, which contain
values in different types, like a C structure.
.SS "\s-1SEQUENCE\s0"
.IX Subsection "SEQUENCE"
A \s-1SEQUENCE\s0 is a complex type that contains other types, a bit like a C
structure. Elements inside a \s-1SEQUENCE\s0 are encoded and decoded in the
order given.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be a reference to an array containing another
\&\fIopList\fR which defines the elements inside the \s-1SEQUENCE.\s0
.Sp
.Vb 6
\&    $ber\->encode(
\&        SEQUENCE => [
\&            INTEGER => 123,
\&            BOOLEAN => [ 1, 0 ],
\&        ]
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR should a reference to an array that contains the
\&\fIopList\fR which decodes the contents of the \s-1SEQUENCE.\s0
.Sp
.Vb 6
\&    $ber\->decode(
\&        SEQUENCE => [
\&            INTEGER => \e$ival,
\&            BOOLEAN => \e@bvals,
\&        ]
\&    ) or die;
.Ve
.SS "\s-1SET\s0"
.IX Subsection "SET"
A \s-1SET\s0 is an complex type that contains other types, rather like a
\&\s-1SEQUENCE.\s0 Elements inside a \s-1SET\s0 may be present in any order.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR is the same as for the \s-1SEQUENCE\s0 operator.
.Sp
.Vb 6
\&    $ber\->encode(
\&        SET => [
\&            INTEGER => 13,
\&            STRING => \*(AqHello\*(Aq,
\&        ]
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR should be a reference to an \fBequivalent\fR \fIopList\fR to
that used to encode the \s-1SET.\s0 The ordering of the \fIopList\fR should not
matter.
.Sp
.Vb 6
\&    $ber\->decode(
\&        SET => [
\&            STRING => \e$sval,
\&            INTEGER => \e$ival,
\&        ]
\&    ) or die;
.Ve
.SS "\s-1SEQUENCE_OF\s0"
.IX Subsection "SEQUENCE_OF"
A \s-1SEQUENCE_OF\s0 is an ordered list of other types.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR is a \fIref\fR followed by an \fIopList\fR. The \fIref\fR must be
a reference to a list or a hash: if it is to a list, then the
\&\fIopList\fR will be repeated once for every element in the list. If it
is to a hash, then the \fIopList\fR will be repeated once for every key
in the hash (note that ordering of keys in a hash is not guaranteed by
perl.)
.Sp
The remaining \fIopList\fR will then usually contain \fIvalue\fRs which are
code references. If the \fIref\fR 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 \fIref\fR is to a hash, then only the key is passed to
the code.
.Sp
.Vb 10
\&    @vals = ( [ 10, \*(AqFoo\*(Aq ], [ 20, \*(AqBar\*(Aq ] ); # List of refs to lists
\&    $ber\->encode(
\&        SEQUENCE_OF => [ \e@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 => \*(AqBaz\*(Aq, 30 => \*(AqBletch\*(Aq ); # Just a hash
\&    $ber\->decode(
\&        SEQUENCE_OF => [ \e%hash,
\&            SEQUENCE => [
\&                INTEGER => sub { $_[0] }, # Passed the key
\&                STRING => sub { $hash{$_[0]} }, # Passed the key
\&            ]
\&        ]
\&    );
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The \fIvalue\fR must be a reference to a list containing a \fIref\fR and an
\&\fIopList\fR. The \fIref\fR 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 \fIref\fR (dereferenced); the value of
the \fIref\fR is incremented for each item in the \s-1SEQUENCE_OF.\s0
.Sp
.Vb 10
\&    $ber\->decode(
\&        SEQUENCE_OF => [ \e$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; \e$ival[\-1] },
\&                STRING => sub { $sval[$_[0]] = undef; \e$sval[\-1] },
\&            ]
\&        ]
\&    ) or die;
.Ve
.SS "\s-1SET_OF\s0"
.IX Subsection "SET_OF"
A \s-1SET_OF\s0 is an unordered list. This is treated in an identical way to
a \s-1SEQUENCE_OF,\s0 except that no ordering should be inferred from the
list passed or returned.
.SH "SPECIAL OPERATORS"
.IX Header "SPECIAL OPERATORS"
.SS "\s-1BER\s0"
.IX Subsection "BER"
It is sometimes useful to construct or deconstruct \s-1BER\s0 encodings in
several pieces. The \s-1BER\s0 operator lets you do this.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be another \f(CW\*(C`Convert::BER\*(C'\fR object, which will be
inserted into the buffer. If \fIvalue\fR is undefined then nothing is
added.
.Sp
.Vb 10
\&    $tmp\->encode(
\&        SEQUENCE => [
\&            INTEGER => 20,
\&            STRING => \*(AqFoo\*(Aq,
\&        ]
\&    );
\&    $ber\->encode(
\&        BER => $tmp,
\&        BOOLEAN => 1
\&    );
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
\&\fIvalue\fR should be a reference to a scalar, which will contain a
\&\f(CW\*(C`Convert::BER\*(C'\fR object. This object will contain the remainder of the
current sequence or set being decoded.
.Sp
.Vb 10
\&    # 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 => \e$ber2,
\&            STRING => \e$sval,
\&        ],
\&        BOOLEAN => \e$bval,
\&    );
\&    $ber2\->decode(
\&        INTEGER => \e$ival,
\&        STRING => \e$sval2,
\&    );
.Ve
.SS "\s-1ANY\s0"
.IX Subsection "ANY"
This is like the \f(CW\*(C`BER\*(C'\fR operator except that when decoding only the
next item is decoded and placed into the \f(CW\*(C`Convert::BER\*(C'\fR object
returned. There is no difference when encoding.
.IP "Decoding" 4
.IX Item "Decoding"
\&\fIvalue\fR should be a reference to a scalar, which will contain a
\&\f(CW\*(C`Convert::BER\*(C'\fR object. This object will only contain the next single
item in the current sequence being decoded.
.Sp
.Vb 7
\&    # After this, ber2 will decode further, and ival and sval
\&    # will be decoded.
\&    $ber\->decode(
\&        INTEGER = \e$ival,
\&        ANY => \e$ber2,
\&        STRING => \e$sval,
\&    );
.Ve
.SS "\s-1OPTIONAL\s0"
.IX Subsection "OPTIONAL"
This operator allows you to specify that an element is absent from the
encoding.
.IP "Encoding" 4
.IX Item "Encoding"
The \fIvalue\fR should be a reference to another list with another
\&\fIopList\fR. If all of the values of the inner \fIopList\fR are defined,
the entire \s-1OPTIONAL\s0 \fIvalue\fR will be encoded, otherwise it will be
omitted.
.Sp
.Vb 9
\&    $ber\->encode(
\&        SEQUENCE => [
\&            INTEGER => 16, # Will be encoded
\&            OPTIONAL => [
\&                INTEGER => undef, # Will not be encoded
\&            ],
\&            STRING => \*(AqFoo\*(Aq, # Will be encoded
\&        ]
\&    );
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
The contents of \fIvalue\fR are decoded if possible, if not then decode
continues at the next \fIoperator\fR\-\fIvalue\fR pair.
.Sp
.Vb 9
\&    $ber\->decode(
\&        SEQUENCE => [
\&            INTEGER => \e$ival1,
\&            OPTIONAL => [
\&                INTEGER => \e$ival2,
\&            ],
\&            STRING => \e$sval,
\&        ]
\&    );
.Ve
.SS "\s-1CHOICE\s0"
.IX Subsection "CHOICE"
The \fIopList\fR is a list of alternate \fIoperator\fR\-\fIvalue\fR pairs. Only
one will be encoded, and only one will be decoded.
.IP "Encoding" 4
.IX Item "Encoding"
A scalar at the start of the \fIopList\fR identifies which \fIopList\fR
alternative to use for encoding the value. A value of 0 means the
first one is used, 1 means the second one, etc.
.Sp
.Vb 9
\&    # Encode the BMPString alternate of the CHOICE
\&    $ber\->encode(
\&        CHOICE => [ 2,
\&            PrintableString => \*(AqPrintable\*(Aq,
\&            TeletexString   => \*(AqTeletex/T61\*(Aq,
\&            BMPString       => \*(AqBMP/Unicode\*(Aq,
\&            UniversalString => \*(AqUniversal/ISO10646\*(Aq,
\&        ]
\&    ) or die;
.Ve
.IP "Decoding" 4
.IX Item "Decoding"
A reference to a scalar at the start of the \fIopList\fR 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.
.Sp
.Vb 10
\&    # Decode the above.
\&    # Afterwards, $alt will be set to 2, $str will be set to \*(AqBMP/Unicode\*(Aq.
\&    $ber\->decode(
\&        CHOICE => [ \e$alt,
\&            PrintableString => \e$str,
\&            TeletexString   => \e$str,
\&            BMPString       => \e$str,
\&            UniversalString => \e$str,
\&        ]
\&    ) or die;
.Ve
.SH "TAGS"
.IX Header "TAGS"
In \s-1BER\s0 everything being encoded has a tag, a length, and a
value. Normally the tag is derived from the operator \- so \s-1INTEGER\s0 has
a different tag from a \s-1BOOLEAN,\s0 for instance.
.PP
In some applications it is necessary to change the tags used. For
example, a \s-1SET\s0 may need to contain two different \s-1INTEGER\s0 values. Tags
may be changed in two ways, either IMPLICITly or EXPLICITly. With
\&\s-1IMPLICIT\s0 tagging, the new tag completely replaces the old tag. With
\&\s-1EXPLICIT\s0 tagging, the new tag is used \fBas well as\fR the old tag.
.PP
\&\f(CW\*(C`Convert::BER\*(C'\fR supports two ways of using \s-1IMPLICIT\s0 tagging. One
method is to sub-class \f(CW\*(C`Convert::BER\*(C'\fR, 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.
.PP
.Vb 6
\&    $ber\->encode(
\&        [ SEQUENCE => 0x34 ] => [
\&            INTEGER => 10,
\&            STRING  => "A"
\&        ]
\&    ) or die;
.Ve
.PP
This will encode a sequence, with a tag value of \f(CW0x34\fR, which will
contain and integer and a string which will have their default tag
values.
.PP
You may wish to construct your tags using some pre-defined functions
such as \f(CW&Convert::BER::BER_APPLICATION\fR,
\&\f(CW&Convert::BER::BER_CONTEXT\fR, etc, instead of calculating the tag
values yourself.
.PP
To use \s-1EXPLICIT\s0 tagging, enclose the original element in a \s-1SEQUENCE,\s0
and just override the \s-1SEQUENCE\s0's tag as above. Don't forget to set the
constructed bit using \f(CW&Convert::BER::BER_CONSTRUCTOR\fR. For example,
the \s-1ASN.1\s0 definition:
.PP
.Vb 4
\&    Foo ::= SEQUENCE {
\&        [0] EXPLICIT INTEGER,
\&        INTEGER
\&    }
.Ve
.PP
might be encoded using this:
.PP
.Vb 9
\&    $ber\->encode(
\&        SEQUENCE => [
\&            [ SEQUENCE => &Convert::BER::BER_CONTEXT |
\&                          &Convert::BER::BER_CONSTRUCTOR | 0 ] => [
\&                INTEGER => 10,
\&            ],
\&            INTEGER => 11,
\&        ],
\&    ) or die;
.Ve
.SH "SUB-CLASSING"
.IX Header "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,
\&\f(CW\*(C`Convert::BER\*(C'\fR may be sub-classed.
.PP
To do this the sub-class must call a static method \f(CW\*(C`define\*(C'\fR. The
arguments to \f(CW\*(C`define\*(C'\fR 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 \f(CW\*(C`Convert::BER\*(C'\fR exports some variables and constant
subroutines.
.PP
For each operator defined by \f(CW\*(C`Convert::BER\*(C'\fR, or a \f(CW\*(C`Convert::BER\*(C'\fR
sub-class, a scalar variable with the same name is available for
import, for example \f(CW$INTEGER\fR is available from \f(CW\*(C`Convert::BER\*(C'\fR. 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.
.PP
\&\f(CW\*(C`Convert::BER\*(C'\fR also exports some constant subroutines that can be
used to create the tag value. The subroutines exported are:
.PP
.Vb 8
\&        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
.Ve
.PP
\&\f(CW\*(C`Convert::BER\*(C'\fR also provides a subroutine called \f(CW\*(C`ber_tag\*(C'\fR 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 \f(CW\*(C`ber_tag\*(C'\fR
.PP
\&\f(CW\*(C`ber_tag\*(C'\fR takes two arguments, the first is the tag class and the second
is the tag value.
.PP
Using this information a sub-class of Convert::BER can be created as
shown below.
.PP
.Vb 1
\&    package Net::LDAP::BER;
\&
\&    use Convert::BER qw(/^(\e$|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) ],
\&    );
.Ve
.PP
This will create a new class \f(CW\*(C`Net::LDAP::BER\*(C'\fR which has three new operators
available. This class then may be used as follows
.PP
.Vb 1
\&    $ber = new Net::LDAP::BER;
\&    
\&    $ber\->encode(
\&        REQ_UNBIND => 0,
\&        REQ_COMPARE => [
\&            REQ_ABANDON => 123,
\&        ]
\&    );
\&
\&    $ber\->decode(
\&        REQ_UNBIND => \e$var,
\&        REQ_COMPARE => [
\&            REQ_ABANDON => \e$num,
\&        ]
\&    );
.Ve
.PP
Which will encode or decode the data using the formats and tags
defined in the \f(CW\*(C`Net::LDAP::BER\*(C'\fR sub-class. It also helps to make the
code more readable.
.SS "\s-1DEFINING NEW PACKING OPERATORS\s0"
.IX Subsection "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 ...
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Convert::BER cannot support tags that contain more bits than can be
stored in a scalar variable, typically this is 32 bits.
.PP
Convert::BER cannot support items that have a packed length which
cannot be stored in 32 bits.
.SH "BUGS"
.IX Header "BUGS"
The \f(CW\*(C`SET\*(C'\fR decode method fails if the encoded order is different to
the \fIopList\fR order.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com>
.PP
Significant \s-1POD\s0 updates from
Chris Ridd <Chris.Ridd@messagingdirect.com>
.SH "COPYRIGHT"
.IX Header "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.