1Convert::ASN1(3) User Contributed Perl Documentation Convert::ASN1(3)
2
6 Convert::ASN1 - ASN.1 Encode/Decode library
7
9 version 0.27
10
12 use Convert::ASN1;
13 $asn = Convert::ASN1->new;
15 $asn->prepare(q<
16 [APPLICATION 7] SEQUENCE {
18 int INTEGER,
19 str OCTET STRING
20 }
21 >);
23 $pdu = $asn->encode( int => 7, str => "string");
25 $out = $asn->decode($pdu);
27 print $out->{int}," ",$out->{str},"\n";
28 use Convert::ASN1 qw(:io);
30 $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
40 Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER
41 rules.
42
44 new ( [OPTIONS] )
45 Contructor, creates a new object.
46 If given, OPTIONS are the same ones as for "configure ( OPTIONS )"
48 below.
49 error ()
51 Returns the last error.
52 configure ( OPTIONS )
54 Configure options to control how Convert::ASN1 will perform various
55 tasks. Options are passed as name-value pairs.
56 encode
58 Reference to a hash which contains various encode options.
59 decode
61 Reference to a hash which contains various decode options.
62 encoding
64 One of 'BER' or 'DER'. The default is 'BER'
65 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 Encode options
74 real
76 Which encoding to use for real's. One of 'binary', 'nr1', 'nr2',
77 'nr3'
78 time
80 This controls how UTCTime and GeneralizedTime elements are encoded.
81 The default is "withzone".
82 utctime
84 The value passed will be encoded without a zone, ie a UTC
85 value.
86 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 raw The value passed should already be in the correct format and
93 will be copied into the PDU as-is.
94 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 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 Decode options
111 time
113 This controls how a UTCTime or a GeneralizedTime element will be
114 decoded. The default is "utctime".
115 utctime
117 The value returned will be a time value as returned by the
118 "time" function.
119 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 raw The value returned will be the raw encoding as extracted from
126 the PDU.
127 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 null
135 The value to decode ASN.1 NULL types into. If not set, it defaults
136 to 1.
137 prepare ( ASN )
139 Compile the given ASN.1 descripton 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 decribes 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 prepare_file ( ASNPATH )
146 Compile the ASN.1 description to be read from the specified pathname.
147 find ( MACRO )
149 Find a macro from a prepared ASN.1 description. Returns an object which
150 can be used for encode/decode.
151 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 decode ( PDU )
158 Decode the PDU, returns a reference to a hash containg the values for
159 the PDU. Returns undef if there was an error.
160 registeroid ( OID, HANDLER )
162 Register a handler for all ASN.1 elements that are "DEFINED BY" the
163 given OID.
164 HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
166 MACRO )".
167 registertype ( NAME, OID, HANDLER )
169 Register a handler for all ASN.1 elements named "NAME", that are
170 "DEFINED BY" the given OID.
171 HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
173 MACRO )".
174
176 As well as providing an object interface for encoding/decoding PDUs
177 Convert::ASN1 also provides the following functions.
178 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 It is recommended that if the socket is of type SOCK_DGRAM then
189 "recv" be called directly instead of calling "asn_recv".
190 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 If FH is a socket the asn_recv is used to read the element, so the
201 same restiction applies if FH is a socket of type SOCK_DGRAM.
202 asn_send ( SOCK, BUFFER, FLAGS, TO )
204 asn_send ( SOCK, BUFFER, FLAGS )
205 Identical to calling "send", see perlfunc
206 asn_write ( FH, BUFFER )
208 Identical to calling "syswrite" with 2 arguments, see perlfunc
209 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 asn_buffer - input buffer
216 asn_need - number of bytes needed for the next element, if known
217 Returns an element or undef if there was an error.
219 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 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 asn_decode_tag ( TAG )
231 Decode the given ASN.1 encoded "TAG".
232 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 asn_decode_length ( LEN )
238 Decode the given ASN.1 decoded "LEN".
239 asn_encode_length ( LEN )
241 Encode the given "LEN" to its ASN.1 encoding.
242 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 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 asn_hexdump ( FH, BUFFER )
274
276 :all
277 All exported functions
278 :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 :debug
288 asn_dump, asn_hexdump
289 :io asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
291 :tag
293 asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length,
294 asn_encode_length
295
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 # ASN.1
302 int INTEGER,
303 str OCTET STRING
304 # Perl
306 { int => 5, str => "text" }
307 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 namespce for the
310 elements with that element.
311 # ASN.1
313 int INTEGER,
314 seq SEQUENCE {
315 str OCTET STRING,
316 bool BOOLEAN
317 }
318 # Perl
320 { int => 5, seq => { str => "text", bool => 1}}
321 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 # ASN.1
330 int INTEGER,
331 str SEQUENCE OF OCTET STRING
332 # Perl
334 { int => 5, str => [ "text1", "text2"]}
335 # ASN.1
337 int INTEGER,
338 str SEQUENCE OF SEQUENCE {
339 type OCTET STRING,
340 value INTEGER
341 }
342 # Perl
344 { int => 5, str => [
345 { type => "abc", value => 4 },
346 { type => "def", value => -1 },
347 ]}
348 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 # ASN.1
354 int INTEGER,
355 str OCTET STRING,
356 pre ANY
357 # Perl
359 { int => 5, str => "text", pre=>"\x03\x03\x00\x0a\x05" }
360 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 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
373 • XS implementation.
374 • More documentation.
376 • More tests.
378
380 Graham Barr <gbarr@cpan.org>
381
383 Report issues via github at
384 https://github.com/gbarr/perl-Convert-ASN1/issues
385 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.
394perl v5.32.1 2021-01-27 Convert::ASN1(3)