1Convert::ASN1(3)      User Contributed Perl Documentation     Convert::ASN1(3)
2
3
4

NAME

6       Convert::ASN1 - ASN.1 Encode/Decode library
7

SYNOPSYS

9         use Convert::ASN1;
10
11         $asn = Convert::ASN1->new;
12         $asn->prepare(q<
13
14           [APPLICATION 7] SEQUENCE {
15             int INTEGER,
16             str OCTET STRING
17           }
18
19         >);
20
21         $pdu = $asn->encode( int => 7, str => "string");
22
23         $out = $asn->decode($pdu);
24         print $out->{int}," ",$out->{str},"\n";
25
26         use Convert::ASN1 qw(:io);
27
28         $peer   = asn_recv($sock,$buffer,0);
29         $nbytes = asn_read($fh, $buffer);
30         $nbytes = asn_send($sock, $buffer, $peer);
31         $nbytes = asn_send($sock, $buffer);
32         $nbytes = asn_write($fh, $buffer);
33         $buffer = asn_get($fh);
34         $yes    = asn_ready($fh)
35

DESCRIPTION

37       Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER
38       rules.
39

METHODS

41   new ( [OPTIONS] )
42       Contructor, creates a new object.
43
44       If given, OPTIONS are the same ones as for "configure ( OPTIONS )"
45       below.
46
47   error ()
48       Returns the last error.
49
50   configure ( OPTIONS )
51       Configure options to control how Convert::ASN1 will perform various
52       tasks.  Options are passed as name-value pairs.
53
54       encode
55           Reference to a hash which contains various encode options.
56
57       decode
58           Reference to a hash which contains various decode options.
59
60       encoding
61           One of 'BER' or 'DER'. The default is 'BER'
62
63       Encode options
64
65       real
66           Which encoding to use for real's. One of 'binary', 'nr1', 'nr2',
67           'nr3'
68
69       time
70           This controls how UTCTime and GeneralizedTime elements are encoded.
71           The default is "withzone".
72
73           utctime
74               The value passed will be encoded without a zone, ie a UTC
75               value.
76
77           withzone
78               The value will be encoded with a zone. By default it will be
79               encoded using the local time offset. The offset may be set
80               using the "timezone" configure option.
81
82           raw The value passed should already be in the correct format and
83               will be copied into the PDU as-is.
84
85       timezone
86           By default UTCTime and GeneralizedTime will be encoded using the
87           local time offset from UTC. This will over-ride that. It is an
88           offset from UTC in seconds.  This option can be overriden by
89           passing a reference to a list of two values as the time value. The
90           list should contain the time value and the offset from UTC in
91           seconds.
92
93       bigint
94           If during encoding an value greater than 32 bits is discovered and
95           is not already a big integer object, then the value will first be
96           converted into a big integer object. This option controls the big
97           integer class into which the objects will be blessed. The default
98           is to use Math::BigInt
99
100       Decode options
101
102       time
103           This controls how a UTCTime or a GeneralizedTime element will be
104           decoded. The default is "utctime".
105
106           utctime
107               The value returned will be a time value as returned by the
108               "time" function.
109
110           withzone
111               The value returned will be a reference to an array of two
112               values. The first is the same as with "utctime", the second is
113               the timezone offset, in seconds, that was used in the encoding.
114
115           raw The value returned will be the raw encoding as extracted from
116               the PDU.
117
118       bigint
119           If during decoding any big integers are discovered (integers
120           greater than 32 bits), they will be decoded into big integer
121           objects. This option controls the big integer class into which the
122           objects will be blessed.  The default is to use Math::BigInt.
123
124       null
125           The value to decode ASN.1 NULL types into.  If not set, it defaults
126           to 1.
127
128   prepare ( ASN )
129       Compile the given ASN.1 descripton which can be passed as a string or
130       as a filehandle. The syntax used is very close to ASN.1, but has a few
131       differences. If the ASN decribes only one macro then encode/decode can
132       be called on this object. If ASN describes more than one ASN.1 macro
133       then "find" must be called. The method returns undef on error.
134
135   prepare_file ( ASNPATH )
136       Compile the ASN.1 description to be read from the specified pathname.
137
138   find ( MACRO )
139       Find a macro from a prepared ASN.1 description. Returns an object which
140       can be used for encode/decode.
141
142   encode ( VARIABLES )
143       Encode a PDU. Top-level variable are passed as name-value pairs, or as
144       a reference to a hash containing them. Returns the encoded PDU, or
145       undef on error.
146
147   decode ( PDU )
148       Decode the PDU, returns a reference to a hash containg the values for
149       the PDU. Returns undef if there was an error.
150
151   registeroid ( OID, HANDLER )
152       Register a handler for all ASN.1 elements that are "DEFINED BY" the
153       given OID.
154
155       HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
156       MACRO )".
157
158   registertype ( NAME, OID, HANDLER )
159       Register a handler for all ASN.1 elements named "NAME", that are
160       "DEFINED BY" the given OID.
161
162       HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
163       MACRO )".
164

EXPORTS

166       As well as providing an object interface for encoding/decoding PDUs
167       Convert::ASN1 also provides the following functions.
168
169   IO Functions
170       asn_recv ( SOCK, BUFFER, FLAGS )
171           Will read a single element from the socket SOCK into BUFFER.  FLAGS
172           may be MSG_PEEK as exported by "Socket". Returns the address of the
173           sender, or undef if there was an error. Some systems do not support
174           the return of the peer address when the socket is a connected
175           socket, in these cases the empty string will be returned. This is
176           the same behaviour as the "recv" function in perl itself.
177
178           It is recommended that if the socket is of type SOCK_DGRAM then
179           "recv" be called directly instead of calling "asn_recv".
180
181       asn_read ( FH, BUFFER, OFFSET )
182       asn_read ( FH, BUFFER )
183           Will read a single element from the filehandle FH into BUFFER.
184           Returns the number of bytes read if a complete element was read, -1
185           if an incomplete element was read or undef if there was an error.
186           If OFFSET is specified then it is assumed that BUFFER already
187           contains an incomplete element and new data will be appended
188           starting at OFFSET.
189
190           If FH is a socket the asn_recv is used to read the element, so the
191           same restiction applies if FH is a socket of type SOCK_DGRAM.
192
193       asn_send ( SOCK, BUFFER, FLAGS, TO )
194       asn_send ( SOCK, BUFFER, FLAGS )
195           Identical to calling "send", see perlfunc
196
197       asn_write ( FH, BUFFER )
198           Identical to calling "syswrite" with 2 arguments, see perlfunc
199
200       asn_get ( FH )
201           "asn_get" provides buffered IO. Because it needs a buffer FH must
202           be a GLOB or a reference to a GLOB. "asn_get" will use two entries
203           in the hash element of the GLOB to use as its buffer:
204
205             asn_buffer - input buffer
206             asn_need   - number of bytes needed for the next element, if known
207
208           Returns an element or undef if there was an error.
209
210       asn_ready ( FH )
211           "asn_ready" works with "asn_get". It will return true if "asn_get"
212           has already read enough data into the buffer to return a complete
213           element.
214
215   Encode/Decode Functions
216       asn_tag ( CLASS, VALUE )
217           Given CLASS and a VALUE, calculate an integer which when encoded
218           will become the tag.
219
220       asn_decode_tag ( TAG )
221           Decode the given ASN.1 encoded "TAG".
222
223       asn_encode_tag ( TAG )
224           Encode TAG value for encoding.  We assume that the tag has been
225           correctly generated with "asn_tag ( CLASS, VALUE )".
226
227       asn_decode_length ( LEN )
228           Decode the given ASN.1 decoded "LEN".
229
230       asn_encode_length ( LEN )
231           Encode the given "LEN" to its ASN.1 encoding.
232
233   Constants
234       ASN_BIT_STR
235       ASN_BOOLEAN
236       ASN_ENUMERATED
237       ASN_GENERAL_TIME
238       ASN_IA5_STR
239       ASN_INTEGER
240       ASN_NULL
241       ASN_OBJECT_ID
242       ASN_OCTET_STR
243       ASN_PRINT_STR
244       ASN_REAL
245       ASN_SEQUENCE
246       ASN_SET
247       ASN_UTC_TIME
248       ASN_APPLICATION
249       ASN_CONTEXT
250       ASN_PRIVATE
251       ASN_UNIVERSAL
252       ASN_PRIMITIVE
253       ASN_CONSTRUCTOR
254       ASN_LONG_LEN
255       ASN_EXTENSION_ID
256       ASN_BIT
257
258   Debug Functions
259       asn_dump ( [FH,] BUFFER )
260           Try to decode the given buffer as ASN.1 structure and dump it to
261           the given file handle, or "STDERR" if the handle is not given.
262
263       asn_hexdump ( FH, BUFFER )
264

EXPORT TAGS

266       :all
267           All exported functions
268
269       :const
270           ASN_BOOLEAN,     ASN_INTEGER,      ASN_BIT_STR,      ASN_OCTET_STR,
271           ASN_NULL,        ASN_OBJECT_ID,    ASN_REAL,
272           ASN_ENUMERATED, ASN_SEQUENCE,    ASN_SET,          ASN_PRINT_STR,
273           ASN_IA5_STR, ASN_UTC_TIME,    ASN_GENERAL_TIME, ASN_UNIVERSAL,
274           ASN_APPLICATION,  ASN_CONTEXT,      ASN_PRIVATE, ASN_PRIMITIVE,
275           ASN_CONSTRUCTOR,  ASN_LONG_LEN,     ASN_EXTENSION_ID, ASN_BIT
276
277       :debug
278           asn_dump, asn_hexdump
279
280       :io asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
281
282       :tag
283           asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length,
284           asn_encode_length
285

MAPPING ASN.1 TO PERL

287       Every element in the ASN.1 definition has a name, in perl a hash is
288       used with these names as an index and the element value as the hash
289       value.
290
291         # ASN.1
292         int INTEGER,
293         str OCTET STRING
294
295         # Perl
296         { int => 5, str => "text" }
297
298       In the case of a SEQUENCE, SET or CHOICE then the value in the
299       namespace will be a hash reference which will be the namespce for the
300       elements with that element.
301
302         # ASN.1
303         int INTEGER,
304         seq SEQUENCE {
305           str OCTET STRING,
306           bool BOOLEAN
307         }
308
309         # Perl
310         { int => 5, seq => { str => "text", bool => 1}}
311
312       If the element is a SEQUENCE OF, or SET OF, then the value in the
313       namespace will be an array reference. The elements in the array will be
314       of the type expected by the type following the OF. For example with
315       "SEQUENCE OF STRING" the array would contain strings. With "SEQUENCE OF
316       SEQUENCE { ... }" the array will contain hash references which will be
317       used as namespaces
318
319         # ASN.1
320         int INTEGER,
321         str SEQUENCE OF OCTET STRING
322
323         # Perl
324         { int => 5, str => [ "text1", "text2"]}
325
326         # ASN.1
327         int INTEGER,
328         str SEQUENCE OF SEQUENCE {
329           type OCTET STRING,
330           value INTEGER
331         }
332
333         # Perl
334         { int => 5, str => [
335           { type => "abc", value => 4 },
336           { type => "def", value => -1 },
337         ]}
338
339   Exceptions
340       There are some exceptions where Convert::ASN1 does not require an
341       element to be named.  These are SEQUENCE {...}, SET {...} and CHOICE.
342       In each case if the element is not given a name then the elements
343       inside the {...} will share the same namespace as the elements outside
344       of the {...}.
345

TODO

347       ·   XS implementation.
348
349       ·   More documentation.
350
351       ·   More tests.
352

AUTHOR

354       Graham Barr <gbarr@pobox.com>, Report bugs via
355       <bug-Convert-ASN1@rt.cpan.org>
356
358       Copyright (c) 2000-2005 Graham Barr <gbarr@pobox.com>. All rights
359       reserved.  This program is free software; you can redistribute it
360       and/or modify it under the same terms as Perl itself.
361
362
363
364perl v5.10.1                      2008-09-15                  Convert::ASN1(3)
Impressum