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

NAME

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

VERSION

9       version 0.33
10

SYNOPSIS

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

DESCRIPTION

40       Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER
41       rules.
42

METHODS

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

EXPORTS

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

EXPORT TAGS

276       :all
277           All exported functions
278
279       :const
280           ASN_BOOLEAN,     ASN_INTEGER,      ASN_BIT_STR,      ASN_OCTET_STR,
281           ASN_NULL,        ASN_OBJECT_ID,    ASN_REAL,
282           ASN_ENUMERATED, ASN_SEQUENCE,    ASN_SET,          ASN_PRINT_STR,
283           ASN_IA5_STR, ASN_UTC_TIME,    ASN_GENERAL_TIME, ASN_UNIVERSAL,
284           ASN_APPLICATION,  ASN_CONTEXT,      ASN_PRIVATE, ASN_PRIMITIVE,
285           ASN_CONSTRUCTOR,  ASN_LONG_LEN,     ASN_EXTENSION_ID, ASN_BIT
286
287       :debug
288           asn_dump, asn_hexdump
289
290       :io asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
291
292       :tag
293           asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length,
294           asn_encode_length
295

MAPPING ASN.1 TO PERL

297       Every element in the ASN.1 definition has a name, in perl a hash is
298       used with these names as an index and the element value as the hash
299       value.
300
301         # ASN.1
302         int INTEGER,
303         str OCTET STRING
304
305         # Perl
306         { int => 5, str => "text" }
307
308       In the case of a SEQUENCE, SET or CHOICE then the value in the
309       namespace will be a hash reference which will be the namespace for the
310       elements with that element.
311
312         # ASN.1
313         int INTEGER,
314         seq SEQUENCE {
315           str OCTET STRING,
316           bool BOOLEAN
317         }
318
319         # Perl
320         { int => 5, seq => { str => "text", bool => 1}}
321
322       If the element is a SEQUENCE OF, or SET OF, then the value in the
323       namespace will be an array reference. The elements in the array will be
324       of the type expected by the type following the OF. For example with
325       "SEQUENCE OF STRING" the array would contain strings. With "SEQUENCE OF
326       SEQUENCE { ... }" the array will contain hash references which will be
327       used as namespaces
328
329         # ASN.1
330         int INTEGER,
331         str SEQUENCE OF OCTET STRING
332
333         # Perl
334         { int => 5, str => [ "text1", "text2"]}
335
336         # ASN.1
337         int INTEGER,
338         str SEQUENCE OF SEQUENCE {
339           type OCTET STRING,
340           value INTEGER
341         }
342
343         # Perl
344         { int => 5, str => [
345           { type => "abc", value => 4 },
346           { type => "def", value => -1 },
347         ]}
348
349       Finally, if you wish to pre-parse ASN.1 and hold it to include inline
350       in your PDU, you can coerce it into the ASN.1 spec by defining the
351       value as ANY in the schema, and then pass the pre encoded value inline.
352
353         # ASN.1
354         int INTEGER,
355         str OCTET STRING,
356         pre ANY
357
358         # Perl
359         { int => 5, str => "text", pre=>"\x03\x03\x00\x0a\x05" }
360
361       passes a pre-encoded BIT STRING instance as hex text. -But it could be
362       a previous run of $obj->encode() from another run held in some
363       variable.
364
365   Exceptions
366       There are some exceptions where Convert::ASN1 does not require an
367       element to be named.  These are SEQUENCE {...}, SET {...} and CHOICE.
368       In each case if the element is not given a name then the elements
369       inside the {...} will share the same namespace as the elements outside
370       of the {...}.
371

TODO

373       •   XS implementation.
374
375       •   More documentation.
376
377       •   More tests.
378

AUTHOR

380       Graham Barr <gbarr@cpan.org>
381

SUPPORT

383       Report issues via github at
384       https://github.com/gbarr/perl-Convert-ASN1/issues
385
386       To contribute I encourage you to create a git fork of the repository at
387       https://github.com/gbarr/perl-Convert-ASN1 do you work on a fresh
388       branch created from master and submit a pull request
389
391       Copyright (c) 2000-2012 Graham Barr <gbarr@cpan.org>. All rights
392       reserved.  This program is free software; you can redistribute it
393       and/or modify it under the same terms as Perl itself.
394
395
396
397perl v5.36.0                      2022-07-22                  Convert::ASN1(3)
Impressum