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
42 Contructor, creates a new object.
44 error
46 Returns the last error.
48 configure ( OPTIONS )
50 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 off‐
88 set from UTC in seconds. This option can be overriden by passing a
89 reference to a list of two values as the time value. The list
90 should contain the time value and the offset from UTC in seconds.
91 bigint
93 If during encoding an value greater than 32 bits is discovered and
94 is not already a big integer object, then the value will first be
95 converted into a big integer object. This option controls the big
96 integer class into which the objects will be blessed. The default
97 is to use Math::BigInt
98 Decode options
100 time
102 This controls how a UTCTime or a GeneralizedTime element will be
103 decoded. The default is "utctime".
104 utctime
106 The value returned will be a time value as returned by the
107 "time" function.
108 withzone
110 The value returned will be a reference to an array of two val‐
111 ues. The first is the same as with "utctime", the second is the
112 timezone offset, in seconds, that was used in the encoding.
113 raw The value returned will be the raw encoding as extracted from
115 the PDU.
116 bigint
118 If during decoding any big integers are discovered (integers
119 greater than 32 bits), they will be decoded into big integer
120 objects. This option controls the big integer class into which the
121 objects will be blessed. The default is to use Math::BigInt.
122 prepare ( ASN )
124 Compile the given ASN.1 descripton which can be passed as a string or
126 as a filehandle. The syntax used is very close to ASN.1, but has a few
127 differences. If the ASN decribes only one macro then encode/decode can
128 be called on this object. If ASN describes more than one ASN.1 macro
129 then "find" must be called. The method returns undef on error.
130 prepare_file ( ASNPATH )
132 Compile the ASN.1 description to be read from the specified pathname.
134 find ( MACRO )
136 Find a macro from a prepared ASN.1 description. Returns an object which
138 can be used for encode/decode.
139 encode ( VARIABLES )
141 Encode a PDU. Top-level variable are passed as name-value pairs, or as
143 a reference to a hash containing them. Returns the encoded PDU, or
144 undef on error.
145 decode ( PDU )
147 Decode the PDU, returns a reference to a hash containg the values for
149 the PDU. Returns undef if there was an error.
150
152 As well as providing an object interface for encoding/decoding PDUs
153 Convert::ASN1 also provides the following functions.
154 IO Functions
156 asn_recv SOCK, BUFFER, FLAGS
158 Will read a single element from the socket SOCK into BUFFER. FLAGS
159 may be MSG_PEEK as exported by "Socket". Returns the address of the
160 sender, or undef if there was an error. Some systems do not support
161 the return of the peer address when the socket is a connected
162 socket, in these cases the empty string will be returned. This is
163 the same behaviour as the "recv" function in perl itself.
164 It is recommended that if the socket is of type SOCK_DGRAM then
166 "recv" be called directly instead of calling "asn_recv".
167 asn_read FH, BUFFER, OFFSET
169 asn_read FH, BUFFER
170 Will read a single element from the filehandle FH into BUFFER.
171 Returns the number of bytes read if a complete element was read, -1
172 if an incomplete element was read or undef if there was an error.
173 If OFFSET is specified then it is assumed that BUFFER already con‐
174 tains an incomplete element and new data will be appended starting
175 at OFFSET.
176 If FH is a socket the asn_recv is used to read the element, so the
178 same restiction applies if FH is a socket of type SOCK_DGRAM.
179 asn_send SOCK, BUFFER, FLAGS, TO
181 asn_send SOCK, BUFFER, FLAGS
182 Identical to calling "send", see perlfunc
183 asn_write FH, BUFFER
185 Identical to calling "syswrite" with 2 arguments, see perlfunc
186 asn_get FH
188 "asn_get" provides buffered IO. Because it needs a buffer FH must
189 be a GLOB or a reference to a GLOB. "asn_get" will use two entries
190 in the hash element of the GLOB to use as its buffer:
191 asn_buffer - input buffer
193 asn_need - number of bytes needed for the next element, if known
194 Returns an element or undef if there was an error.
196 asn_ready FH
198 "asn_ready" works with "asn_get". It will return true if "asn_get"
199 has already read enough data into the buffer to return a complete
200 element.
201 Encode/Decode Functions
203 asn_tag
205 asn_decode_tag
206 asn_encode_tag
207 asn_decode_length
208 asn_encode_length
209 Constants
211 ASN_BIT_STR
213 ASN_BOOLEAN
214 ASN_ENUMERATED
215 ASN_GENERAL_TIME
216 ASN_IA5_STR
217 ASN_INTEGER
218 ASN_NULL
219 ASN_OBJECT_ID
220 ASN_OCTET_STR
221 ASN_PRINT_STR
222 ASN_REAL
223 ASN_SEQUENCE
224 ASN_SET
225 ASN_UTC_TIME
226 ASN_APPLICATION
227 ASN_CONTEXT
228 ASN_PRIVATE
229 ASN_UNIVERSAL
230 ASN_PRIMITIVE
231 ASN_CONSTRUCTOR
232 ASN_LONG_LEN
233 ASN_EXTENSION_ID
234 ASN_BIT
235 Debug Functions
237 asn_dump
239 asn_hexdump
240
242 :all
243 All exported functions
244 :const
246 ASN_BOOLEAN, ASN_INTEGER, ASN_BIT_STR, ASN_OCTET_STR,
247 ASN_NULL, ASN_OBJECT_ID, ASN_REAL, ASN_ENUMER‐
248 ATED, ASN_SEQUENCE, ASN_SET, ASN_PRINT_STR,
249 ASN_IA5_STR, ASN_UTC_TIME, ASN_GENERAL_TIME, ASN_UNIVERSAL,
250 ASN_APPLICATION, ASN_CONTEXT, ASN_PRIVATE, ASN_PRIMITIVE,
251 ASN_CONSTRUCTOR, ASN_LONG_LEN, ASN_EXTENSION_ID, ASN_BIT
252 :debug
254 asn_dump, asn_dumphex
255 :io asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready
257 :tag
259 asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length,
260 asn_encode_length
261
263 Every element in the ASN.1 definition has a name, in perl a hash is
264 used with these names as an index and the element value as the hash
265 value.
266 # ASN.1
268 int INTEGER,
269 str OCTET STRING
270 # Perl
272 { int => 5, str => "text" }
273 In the case of a SEQUENCE, SET or CHOICE then the value in the names‐
275 pace will be a hash reference which will be the namespce for the ele‐
276 ments with that element.
277 # ASN.1
279 int INTEGER,
280 seq SEQUENCE {
281 str OCTET STRING,
282 bool BOOLEAN
283 }
284 # Perl
286 { int => 5, seq => { str => "text", bool => 1}}
287 If the element is a SEQUENCE OF, or SET OF, then the value in the
289 namespace will be an array reference. The elements in the array will be
290 of the type expected by the type following the OF. For example with
291 "SEQUENCE OF STRING" the array would contain strings. With "SEQUENCE OF
292 SEQUENCE { ... }" the array will contain hash references which will be
293 used as namespaces
294 # ASN.1
296 int INTEGER,
297 str SEQUENCE OF OCTET STRING
298 # Perl
300 { int => 5, str => [ "text1", "text2"]}
301 # ASN.1
303 int INTEGER,
304 str SEQUENCE OF SEQUENCE {
305 type OCTET STRING,
306 value INTEGER
307 }
308 # Perl
310 { int => 5, str => [
311 { type => "abc", value => 4 },
312 { type => "def", value => -1 },
313 ]}
314 Exceptions
316 There are some exceptions where Convert::ASN1 does not require an ele‐
318 ment to be named. These are SEQUENCE {...}, SET {...} and CHOICE. In
319 each case if the element is not given a name then the elements inside
320 the {...} will share the same namespace as the elements outside of the
321 {...}.
322
324 · XS implementation.
325 · More documentation.
327 · More tests.
329
331 Graham Barr <gbarr@pobox.com>, Report bugs via <bug-Con‐
332 vert-ASN1@rt.cpan.org>
333
335 Copyright (c) 2000-2005 Graham Barr <gbarr@pobox.com>. All rights
336 reserved. This program is free software; you can redistribute it
337 and/or modify it under the same terms as Perl itself.
338perl v5.8.8 2007-02-02 Convert::ASN1(3)