summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl0/lib/Convert/ASN1.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/Convert/ASN1.pod')
-rwxr-xr-xMaster/tlpkg/tlperl0/lib/Convert/ASN1.pod480
1 files changed, 480 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/Convert/ASN1.pod b/Master/tlpkg/tlperl0/lib/Convert/ASN1.pod
new file mode 100755
index 00000000000..b31395b334e
--- /dev/null
+++ b/Master/tlpkg/tlperl0/lib/Convert/ASN1.pod
@@ -0,0 +1,480 @@
+=head1 NAME
+
+Convert::ASN1 - ASN.1 Encode/Decode library
+
+=head1 SYNOPSYS
+
+ use Convert::ASN1;
+
+ $asn = Convert::ASN1->new;
+ $asn->prepare(q<
+
+ [APPLICATION 7] SEQUENCE {
+ int INTEGER,
+ str OCTET STRING
+ }
+
+ >);
+
+ $pdu = $asn->encode( int => 7, str => "string");
+
+ $out = $asn->decode($pdu);
+ print $out->{int}," ",$out->{str},"\n";
+
+ use Convert::ASN1 qw(:io);
+
+ $peer = asn_recv($sock,$buffer,0);
+ $nbytes = asn_read($fh, $buffer);
+ $nbytes = asn_send($sock, $buffer, $peer);
+ $nbytes = asn_send($sock, $buffer);
+ $nbytes = asn_write($fh, $buffer);
+ $buffer = asn_get($fh);
+ $yes = asn_ready($fh)
+
+=head1 DESCRIPTION
+
+Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER
+rules.
+
+=head1 METHODS
+
+=head2 new ( [OPTIONS] )
+
+Contructor, creates a new object.
+
+If given, B<OPTIONS> are the same ones as for L</"configure ( OPTIONS )"> below.
+
+=head2 error ()
+
+Returns the last error.
+
+=head2 configure ( OPTIONS )
+
+Configure options to control how Convert::ASN1 will perform various tasks.
+Options are passed as name-value pairs.
+
+=over 4
+
+=item encode
+
+Reference to a hash which contains various encode options.
+
+=item decode
+
+Reference to a hash which contains various decode options.
+
+=item encoding
+
+One of 'BER' or 'DER'. The default is 'BER'
+
+=back
+
+Encode options
+
+=over 4
+
+=item real
+
+Which encoding to use for real's. One of 'binary', 'nr1', 'nr2', 'nr3'
+
+=item time
+
+This controls how UTCTime and GeneralizedTime elements are encoded. The default
+is C<withzone>.
+
+=over 4
+
+=item utctime
+
+The value passed will be encoded without a zone, ie a UTC value.
+
+=item withzone
+
+The value will be encoded with a zone. By default it will be encoded
+using the local time offset. The offset may be set using the C<timezone>
+configure option.
+
+=item raw
+
+The value passed should already be in the correct format and will be copied
+into the PDU as-is.
+
+=back
+
+=item timezone
+
+By default UTCTime and GeneralizedTime will be encoded using the local
+time offset from UTC. This will over-ride that. It is an offset from UTC
+in seconds. This option can be overriden by passing a reference to a
+list of two values as the time value. The list should contain the time
+value and the offset from UTC in seconds.
+
+=item bigint
+
+If during encoding an value greater than 32 bits is discovered and
+is not already a big integer object, then the value will first be
+converted into a big integer object. This option controls the big
+integer class into which the objects will be blessed. The default
+is to use Math::BigInt
+
+=back
+
+Decode options
+
+=over 4
+
+=item time
+
+This controls how a UTCTime or a GeneralizedTime element will be decoded. The default
+is C<utctime>.
+
+=over 4
+
+=item utctime
+
+The value returned will be a time value as returned by the C<time> function.
+
+=item withzone
+
+The value returned will be a reference to an array of two values. The first is the
+same as with C<utctime>, the second is the timezone offset, in seconds, that was
+used in the encoding.
+
+=item raw
+
+The value returned will be the raw encoding as extracted from the PDU.
+
+=back
+
+=item bigint
+
+If during decoding any big integers are discovered (integers greater
+than 32 bits), they will be decoded into big integer objects. This option
+controls the big integer class into which the objects will be blessed.
+The default is to use Math::BigInt.
+
+=item null
+
+The value to decode ASN.1 NULL types into.
+If not set, it defaults to C<1>.
+
+=back
+
+=head2 prepare ( ASN )
+
+Compile the given ASN.1 descripton which can be passed as a string
+or as a filehandle. The syntax used is very close to ASN.1, but has
+a few differences. If the ASN decribes only one macro then encode/decode can be
+called on this object. If ASN describes more than one ASN.1 macro then C<find>
+must be called. The method returns undef on error.
+
+=head2 prepare_file ( ASNPATH )
+
+Compile the ASN.1 description to be read from the specified pathname.
+
+=head2 find ( MACRO )
+
+Find a macro from a prepared ASN.1 description. Returns an object which can
+be used for encode/decode.
+
+=head2 encode ( VARIABLES )
+
+Encode a PDU. Top-level variable are passed as name-value pairs, or as a reference
+to a hash containing them. Returns the encoded PDU, or undef on error.
+
+=head2 decode ( PDU )
+
+Decode the PDU, returns a reference to a hash containg the values for the PDU. Returns
+undef if there was an error.
+
+=head2 registeroid ( OID, HANDLER )
+
+Register a handler for all ASN.1 elements
+that are C<DEFINED BY> the given OID.
+
+B<HANDLER> must be a Convert::ASN1 object, e.g. as returned by L</"find ( MACRO )">.
+
+=head2 registertype ( NAME, OID, HANDLER )
+
+Register a handler for all ASN.1 elements named C<NAME>,
+that are C<DEFINED BY> the given OID.
+
+B<HANDLER> must be a Convert::ASN1 object, e.g. as returned by L</"find ( MACRO )">.
+
+=head1 EXPORTS
+
+As well as providing an object interface for encoding/decoding PDUs Convert::ASN1
+also provides the following functions.
+
+=head2 IO Functions
+
+=over 4
+
+=item asn_recv ( SOCK, BUFFER, FLAGS )
+
+Will read a single element from the socket SOCK into BUFFER. FLAGS may
+be MSG_PEEK as exported by C<Socket>. Returns the address of the sender,
+or undef if there was an error. Some systems do not support the return
+of the peer address when the socket is a connected socket, in these
+cases the empty string will be returned. This is the same behaviour
+as the C<recv> function in perl itself.
+
+It is recommended that if the socket is of type SOCK_DGRAM then C<recv>
+be called directly instead of calling C<asn_recv>.
+
+=item asn_read ( FH, BUFFER, OFFSET )
+
+=item asn_read ( FH, BUFFER )
+
+Will read a single element from the filehandle FH into BUFFER. Returns the
+number of bytes read if a complete element was read, -1 if an incomplete
+element was read or undef if there was an error. If OFFSET is specified
+then it is assumed that BUFFER already contains an incomplete element
+and new data will be appended starting at OFFSET.
+
+If FH is a socket the asn_recv is used to read the element, so the same
+restiction applies if FH is a socket of type SOCK_DGRAM.
+
+=item asn_send ( SOCK, BUFFER, FLAGS, TO )
+
+=item asn_send ( SOCK, BUFFER, FLAGS )
+
+Identical to calling C<send>, see L<perlfunc>
+
+=item asn_write ( FH, BUFFER )
+
+Identical to calling C<syswrite> with 2 arguments, see L<perlfunc>
+
+=item asn_get ( FH )
+
+C<asn_get> provides buffered IO. Because it needs a buffer FH must be a GLOB
+or a reference to a GLOB. C<asn_get> will use two entries in the hash element
+of the GLOB to use as its buffer:
+
+ asn_buffer - input buffer
+ asn_need - number of bytes needed for the next element, if known
+
+Returns an element or undef if there was an error.
+
+=item asn_ready ( FH )
+
+C<asn_ready> works with C<asn_get>. It will return true if C<asn_get> has already
+read enough data into the buffer to return a complete element.
+
+=back
+
+=head2 Encode/Decode Functions
+
+=over 4
+
+=item asn_tag ( CLASS, VALUE )
+
+Given B<CLASS> and a B<VALUE>, calculate an integer which when encoded
+will become the tag.
+
+=item asn_decode_tag ( TAG )
+
+Decode the given ASN.1 encoded C<TAG>.
+
+=item asn_encode_tag ( TAG )
+
+Encode B<TAG> value for encoding.
+We assume that the tag has been correctly generated with L</"asn_tag ( CLASS, VALUE )">.
+
+=item asn_decode_length ( LEN )
+
+Decode the given ASN.1 decoded C<LEN>.
+
+=item asn_encode_length ( LEN )
+
+Encode the given C<LEN> to its ASN.1 encoding.
+
+=back
+
+=head2 Constants
+
+=over 4
+
+=item ASN_BIT_STR
+
+=item ASN_BOOLEAN
+
+=item ASN_ENUMERATED
+
+=item ASN_GENERAL_TIME
+
+=item ASN_IA5_STR
+
+=item ASN_INTEGER
+
+=item ASN_NULL
+
+=item ASN_OBJECT_ID
+
+=item ASN_OCTET_STR
+
+=item ASN_PRINT_STR
+
+=item ASN_REAL
+
+=item ASN_SEQUENCE
+
+=item ASN_SET
+
+=item ASN_UTC_TIME
+
+=item ASN_APPLICATION
+
+=item ASN_CONTEXT
+
+=item ASN_PRIVATE
+
+=item ASN_UNIVERSAL
+
+=item ASN_PRIMITIVE
+
+=item ASN_CONSTRUCTOR
+
+=item ASN_LONG_LEN
+
+=item ASN_EXTENSION_ID
+
+=item ASN_BIT
+
+=back
+
+=head2 Debug Functions
+
+=over 4
+
+=item asn_dump ( [FH,] BUFFER )
+
+Try to decode the given buffer as ASN.1 structure and dump it to the
+given file handle, or C<STDERR> if the handle is not given.
+
+=item asn_hexdump ( FH, BUFFER )
+
+=back
+
+=head1 EXPORT TAGS
+
+=over 4
+
+=item :all
+
+All exported functions
+
+=item :const
+
+ASN_BOOLEAN, ASN_INTEGER, ASN_BIT_STR, ASN_OCTET_STR,
+ASN_NULL, ASN_OBJECT_ID, ASN_REAL, ASN_ENUMERATED,
+ASN_SEQUENCE, ASN_SET, ASN_PRINT_STR, ASN_IA5_STR,
+ASN_UTC_TIME, ASN_GENERAL_TIME,
+ASN_UNIVERSAL, ASN_APPLICATION, ASN_CONTEXT, ASN_PRIVATE,
+ASN_PRIMITIVE, ASN_CONSTRUCTOR, ASN_LONG_LEN, ASN_EXTENSION_ID, ASN_BIT
+
+=item :debug
+
+asn_dump, asn_hexdump
+
+=item :io
+
+asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
+
+=item :tag
+
+asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length, asn_encode_length
+
+=back
+
+=head1 MAPPING ASN.1 TO PERL
+
+Every element in the ASN.1 definition has a name, in perl a hash is used
+with these names as an index and the element value as the hash value.
+
+ # ASN.1
+ int INTEGER,
+ str OCTET STRING
+
+ # Perl
+ { int => 5, str => "text" }
+
+
+In the case of a SEQUENCE, SET or CHOICE then the value in the namespace will
+be a hash reference which will be the namespce for the elements with
+that element.
+
+ # ASN.1
+ int INTEGER,
+ seq SEQUENCE {
+ str OCTET STRING,
+ bool BOOLEAN
+ }
+
+ # Perl
+ { int => 5, seq => { str => "text", bool => 1}}
+
+If the element is a SEQUENCE OF, or SET OF, then the value in the namespace
+will be an array reference. The elements in the array will be of
+the type expected by the type following the OF. For example
+with "SEQUENCE OF STRING" the array would contain strings. With
+"SEQUENCE OF SEQUENCE { ... }" the array will contain hash references
+which will be used as namespaces
+
+ # ASN.1
+ int INTEGER,
+ str SEQUENCE OF OCTET STRING
+
+ # Perl
+ { int => 5, str => [ "text1", "text2"]}
+
+ # ASN.1
+ int INTEGER,
+ str SEQUENCE OF SEQUENCE {
+ type OCTET STRING,
+ value INTEGER
+ }
+
+ # Perl
+ { int => 5, str => [
+ { type => "abc", value => 4 },
+ { type => "def", value => -1 },
+ ]}
+
+=head2 Exceptions
+
+There are some exceptions where Convert::ASN1 does not require an element to be named.
+These are SEQUENCE {...}, SET {...} and CHOICE. In each case if the element is not
+given a name then the elements inside the {...} will share the same namespace as
+the elements outside of the {...}.
+
+=head1 TODO
+
+=over 4
+
+=item *
+
+XS implementation.
+
+=item *
+
+More documentation.
+
+=item *
+
+More tests.
+
+=back
+
+=head1 AUTHOR
+
+Graham Barr <gbarr@pobox.com>, Report bugs via <bug-Convert-ASN1@rt.cpan.org>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2000-2005 Graham Barr <gbarr@pobox.com>. All rights reserved.
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut
+