1Convert::ASN1(3) User Contributed Perl Documentation Convert::ASN1(3)
2
6 Convert::ASN1 - ASN.1 Encode/Decode library
7
9 use Convert::ASN1;
10 $asn = Convert::ASN1->new;
12 $asn->prepare(q<
13 [APPLICATION 7] SEQUENCE {
15 int INTEGER,
16 str OCTET STRING
17 }
18 >);
20 $pdu = $asn->encode( int => 7, str => "string");
22 $out = $asn->decode($pdu);
24 print $out->{int}," ",$out->{str},"\n";
25 use Convert::ASN1 qw(:io);
27 $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
37 Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER
38 rules.
39
41 new ( [OPTIONS] )
42 Contructor, creates a new object.
43 If given, OPTIONS are the same ones as for "configure ( OPTIONS )"
45 below.
46 error ()
48 Returns the last error.
49 configure ( OPTIONS )
51 Configure options to control how Convert::ASN1 will perform various
52 tasks. Options are passed as name-value pairs.
53 encode
55 Reference to a hash which contains various encode options.
56 decode
58 Reference to a hash which contains various decode options.
59 encoding
61 One of 'BER' or 'DER'. The default is 'BER'
62 Encode options
64 real
66 Which encoding to use for real's. One of 'binary', 'nr1', 'nr2',
67 'nr3'
68 time
70 This controls how UTCTime and GeneralizedTime elements are encoded.
71 The default is "withzone".
72 utctime
74 The value passed will be encoded without a zone, ie a UTC
75 value.
76 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 raw The value passed should already be in the correct format and
83 will be copied into the PDU as-is.
84 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 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 Decode options
101 time
103 This controls how a UTCTime or a GeneralizedTime element will be
104 decoded. The default is "utctime".
105 utctime
107 The value returned will be a time value as returned by the
108 "time" function.
109 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 raw The value returned will be the raw encoding as extracted from
116 the PDU.
117 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 null
125 The value to decode ASN.1 NULL types into. If not set, it defaults
126 to 1.
127 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 prepare_file ( ASNPATH )
136 Compile the ASN.1 description to be read from the specified pathname.
137 find ( MACRO )
139 Find a macro from a prepared ASN.1 description. Returns an object which
140 can be used for encode/decode.
141 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 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 registeroid ( OID, HANDLER )
152 Register a handler for all ASN.1 elements that are "DEFINED BY" the
153 given OID.
154 HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
156 MACRO )".
157 registertype ( NAME, OID, HANDLER )
159 Register a handler for all ASN.1 elements named "NAME", that are
160 "DEFINED BY" the given OID.
161 HANDLER must be a Convert::ASN1 object, e.g. as returned by "find (
163 MACRO )".
164
166 As well as providing an object interface for encoding/decoding PDUs
167 Convert::ASN1 also provides the following functions.
168 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 It is recommended that if the socket is of type SOCK_DGRAM then
179 "recv" be called directly instead of calling "asn_recv".
180 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 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 asn_send ( SOCK, BUFFER, FLAGS, TO )
194 asn_send ( SOCK, BUFFER, FLAGS )
195 Identical to calling "send", see perlfunc
196 asn_write ( FH, BUFFER )
198 Identical to calling "syswrite" with 2 arguments, see perlfunc
199 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 asn_buffer - input buffer
206 asn_need - number of bytes needed for the next element, if known
207 Returns an element or undef if there was an error.
209 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 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 asn_decode_tag ( TAG )
221 Decode the given ASN.1 encoded "TAG".
222 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 asn_decode_length ( LEN )
228 Decode the given ASN.1 decoded "LEN".
229 asn_encode_length ( LEN )
231 Encode the given "LEN" to its ASN.1 encoding.
232 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 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 asn_hexdump ( FH, BUFFER )
264
266 :all
267 All exported functions
268 :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 :debug
278 asn_dump, asn_hexdump
279 :io asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
281 :tag
283 asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length,
284 asn_encode_length
285
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 # ASN.1
292 int INTEGER,
293 str OCTET STRING
294 # Perl
296 { int => 5, str => "text" }
297 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 # ASN.1
303 int INTEGER,
304 seq SEQUENCE {
305 str OCTET STRING,
306 bool BOOLEAN
307 }
308 # Perl
310 { int => 5, seq => { str => "text", bool => 1}}
311 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 # ASN.1
320 int INTEGER,
321 str SEQUENCE OF OCTET STRING
322 # Perl
324 { int => 5, str => [ "text1", "text2"]}
325 # ASN.1
327 int INTEGER,
328 str SEQUENCE OF SEQUENCE {
329 type OCTET STRING,
330 value INTEGER
331 }
332 # Perl
334 { int => 5, str => [
335 { type => "abc", value => 4 },
336 { type => "def", value => -1 },
337 ]}
338 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
347 · XS implementation.
348 · More documentation.
350 · More tests.
352
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.
361perl v5.12.0 2008-09-15 Convert::ASN1(3)