[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 =head1 NAME 2 3 Convert::ASN1 - ASN.1 Encode/Decode library 4 5 =head1 SYNOPSYS 6 7 use Convert::ASN1; 8 9 $asn = Convert::ASN1->new; 10 $asn->prepare(q< 11 12 [APPLICATION 7] SEQUENCE { 13 int INTEGER, 14 str OCTET STRING 15 } 16 17 >); 18 19 $pdu = $asn->encode( int => 7, str => "string"); 20 21 $out = $asn->decode($pdu); 22 print $out->{int}," ",$out->{str},"\n"; 23 24 use Convert::ASN1 qw(:io); 25 26 $peer = asn_recv($sock,$buffer,0); 27 $nbytes = asn_read($fh, $buffer); 28 $nbytes = asn_send($sock, $buffer, $peer); 29 $nbytes = asn_send($sock, $buffer); 30 $nbytes = asn_write($fh, $buffer); 31 $buffer = asn_get($fh); 32 $yes = asn_ready($fh) 33 34 =head1 DESCRIPTION 35 36 Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER 37 rules. 38 39 =head1 METHODS 40 41 =head2 new ( [OPTIONS] ) 42 43 Contructor, creates a new object. 44 45 If given, B<OPTIONS> are the same ones as for L</"configure ( OPTIONS )"> below. 46 47 =head2 error () 48 49 Returns the last error. 50 51 =head2 configure ( OPTIONS ) 52 53 Configure options to control how Convert::ASN1 will perform various tasks. 54 Options are passed as name-value pairs. 55 56 =over 4 57 58 =item encode 59 60 Reference to a hash which contains various encode options. 61 62 =item decode 63 64 Reference to a hash which contains various decode options. 65 66 =item encoding 67 68 One of 'BER' or 'DER'. The default is 'BER' 69 70 =back 71 72 Encode options 73 74 =over 4 75 76 =item real 77 78 Which encoding to use for real's. One of 'binary', 'nr1', 'nr2', 'nr3' 79 80 =item time 81 82 This controls how UTCTime and GeneralizedTime elements are encoded. The default 83 is C<withzone>. 84 85 =over 4 86 87 =item utctime 88 89 The value passed will be encoded without a zone, ie a UTC value. 90 91 =item withzone 92 93 The value will be encoded with a zone. By default it will be encoded 94 using the local time offset. The offset may be set using the C<timezone> 95 configure option. 96 97 =item raw 98 99 The value passed should already be in the correct format and will be copied 100 into the PDU as-is. 101 102 =back 103 104 =item timezone 105 106 By default UTCTime and GeneralizedTime will be encoded using the local 107 time offset from UTC. This will over-ride that. It is an offset from UTC 108 in seconds. This option can be overriden by passing a reference to a 109 list of two values as the time value. The list should contain the time 110 value and the offset from UTC in seconds. 111 112 =item bigint 113 114 If during encoding an value greater than 32 bits is discovered and 115 is not already a big integer object, then the value will first be 116 converted into a big integer object. This option controls the big 117 integer class into which the objects will be blessed. The default 118 is to use Math::BigInt 119 120 =back 121 122 Decode options 123 124 =over 4 125 126 =item time 127 128 This controls how a UTCTime or a GeneralizedTime element will be decoded. The default 129 is C<utctime>. 130 131 =over 4 132 133 =item utctime 134 135 The value returned will be a time value as returned by the C<time> function. 136 137 =item withzone 138 139 The value returned will be a reference to an array of two values. The first is the 140 same as with C<utctime>, the second is the timezone offset, in seconds, that was 141 used in the encoding. 142 143 =item raw 144 145 The value returned will be the raw encoding as extracted from the PDU. 146 147 =back 148 149 =item bigint 150 151 If during decoding any big integers are discovered (integers greater 152 than 32 bits), they will be decoded into big integer objects. This option 153 controls the big integer class into which the objects will be blessed. 154 The default is to use Math::BigInt. 155 156 =item null 157 158 The value to decode ASN.1 NULL types into. 159 If not set, it defaults to C<1>. 160 161 =back 162 163 =head2 prepare ( ASN ) 164 165 Compile the given ASN.1 descripton which can be passed as a string 166 or as a filehandle. The syntax used is very close to ASN.1, but has 167 a few differences. If the ASN decribes only one macro then encode/decode can be 168 called on this object. If ASN describes more than one ASN.1 macro then C<find> 169 must be called. The method returns undef on error. 170 171 =head2 prepare_file ( ASNPATH ) 172 173 Compile the ASN.1 description to be read from the specified pathname. 174 175 =head2 find ( MACRO ) 176 177 Find a macro from a prepared ASN.1 description. Returns an object which can 178 be used for encode/decode. 179 180 =head2 encode ( VARIABLES ) 181 182 Encode a PDU. Top-level variable are passed as name-value pairs, or as a reference 183 to a hash containing them. Returns the encoded PDU, or undef on error. 184 185 =head2 decode ( PDU ) 186 187 Decode the PDU, returns a reference to a hash containg the values for the PDU. Returns 188 undef if there was an error. 189 190 =head2 registeroid ( OID, HANDLER ) 191 192 Register a handler for all ASN.1 elements 193 that are C<DEFINED BY> the given OID. 194 195 B<HANDLER> must be a Convert::ASN1 object, e.g. as returned by L</"find ( MACRO )">. 196 197 =head2 registertype ( NAME, OID, HANDLER ) 198 199 Register a handler for all ASN.1 elements named C<NAME>, 200 that are C<DEFINED BY> the given OID. 201 202 B<HANDLER> must be a Convert::ASN1 object, e.g. as returned by L</"find ( MACRO )">. 203 204 =head1 EXPORTS 205 206 As well as providing an object interface for encoding/decoding PDUs Convert::ASN1 207 also provides the following functions. 208 209 =head2 IO Functions 210 211 =over 4 212 213 =item asn_recv ( SOCK, BUFFER, FLAGS ) 214 215 Will read a single element from the socket SOCK into BUFFER. FLAGS may 216 be MSG_PEEK as exported by C<Socket>. Returns the address of the sender, 217 or undef if there was an error. Some systems do not support the return 218 of the peer address when the socket is a connected socket, in these 219 cases the empty string will be returned. This is the same behaviour 220 as the C<recv> function in perl itself. 221 222 It is recommended that if the socket is of type SOCK_DGRAM then C<recv> 223 be called directly instead of calling C<asn_recv>. 224 225 =item asn_read ( FH, BUFFER, OFFSET ) 226 227 =item asn_read ( FH, BUFFER ) 228 229 Will read a single element from the filehandle FH into BUFFER. Returns the 230 number of bytes read if a complete element was read, -1 if an incomplete 231 element was read or undef if there was an error. If OFFSET is specified 232 then it is assumed that BUFFER already contains an incomplete element 233 and new data will be appended starting at OFFSET. 234 235 If FH is a socket the asn_recv is used to read the element, so the same 236 restiction applies if FH is a socket of type SOCK_DGRAM. 237 238 =item asn_send ( SOCK, BUFFER, FLAGS, TO ) 239 240 =item asn_send ( SOCK, BUFFER, FLAGS ) 241 242 Identical to calling C<send>, see L<perlfunc> 243 244 =item asn_write ( FH, BUFFER ) 245 246 Identical to calling C<syswrite> with 2 arguments, see L<perlfunc> 247 248 =item asn_get ( FH ) 249 250 C<asn_get> provides buffered IO. Because it needs a buffer FH must be a GLOB 251 or a reference to a GLOB. C<asn_get> will use two entries in the hash element 252 of the GLOB to use as its buffer: 253 254 asn_buffer - input buffer 255 asn_need - number of bytes needed for the next element, if known 256 257 Returns an element or undef if there was an error. 258 259 =item asn_ready ( FH ) 260 261 C<asn_ready> works with C<asn_get>. It will return true if C<asn_get> has already 262 read enough data into the buffer to return a complete element. 263 264 =back 265 266 =head2 Encode/Decode Functions 267 268 =over 4 269 270 =item asn_tag ( CLASS, VALUE ) 271 272 Given B<CLASS> and a B<VALUE>, calculate an integer which when encoded 273 will become the tag. 274 275 =item asn_decode_tag ( TAG ) 276 277 Decode the given ASN.1 encoded C<TAG>. 278 279 =item asn_encode_tag ( TAG ) 280 281 Encode B<TAG> value for encoding. 282 We assume that the tag has been correctly generated with L</"asn_tag ( CLASS, VALUE )">. 283 284 =item asn_decode_length ( LEN ) 285 286 Decode the given ASN.1 decoded C<LEN>. 287 288 =item asn_encode_length ( LEN ) 289 290 Encode the given C<LEN> to its ASN.1 encoding. 291 292 =back 293 294 =head2 Constants 295 296 =over 4 297 298 =item ASN_BIT_STR 299 300 =item ASN_BOOLEAN 301 302 =item ASN_ENUMERATED 303 304 =item ASN_GENERAL_TIME 305 306 =item ASN_IA5_STR 307 308 =item ASN_INTEGER 309 310 =item ASN_NULL 311 312 =item ASN_OBJECT_ID 313 314 =item ASN_OCTET_STR 315 316 =item ASN_PRINT_STR 317 318 =item ASN_REAL 319 320 =item ASN_SEQUENCE 321 322 =item ASN_SET 323 324 =item ASN_UTC_TIME 325 326 =item ASN_APPLICATION 327 328 =item ASN_CONTEXT 329 330 =item ASN_PRIVATE 331 332 =item ASN_UNIVERSAL 333 334 =item ASN_PRIMITIVE 335 336 =item ASN_CONSTRUCTOR 337 338 =item ASN_LONG_LEN 339 340 =item ASN_EXTENSION_ID 341 342 =item ASN_BIT 343 344 =back 345 346 =head2 Debug Functions 347 348 =over 4 349 350 =item asn_dump ( [FH,] BUFFER ) 351 352 Try to decode the given buffer as ASN.1 structure and dump it to the 353 given file handle, or C<STDERR> if the handle is not given. 354 355 =item asn_hexdump ( FH, BUFFER ) 356 357 =back 358 359 =head1 EXPORT TAGS 360 361 =over 4 362 363 =item :all 364 365 All exported functions 366 367 =item :const 368 369 ASN_BOOLEAN, ASN_INTEGER, ASN_BIT_STR, ASN_OCTET_STR, 370 ASN_NULL, ASN_OBJECT_ID, ASN_REAL, ASN_ENUMERATED, 371 ASN_SEQUENCE, ASN_SET, ASN_PRINT_STR, ASN_IA5_STR, 372 ASN_UTC_TIME, ASN_GENERAL_TIME, 373 ASN_UNIVERSAL, ASN_APPLICATION, ASN_CONTEXT, ASN_PRIVATE, 374 ASN_PRIMITIVE, ASN_CONSTRUCTOR, ASN_LONG_LEN, ASN_EXTENSION_ID, ASN_BIT 375 376 =item :debug 377 378 asn_dump, asn_hexdump 379 380 =item :io 381 382 asn_recv, asn_send, asn_read, asn_write, asn_get, asn_ready 383 384 =item :tag 385 386 asn_tag, asn_decode_tag, asn_encode_tag, asn_decode_length, asn_encode_length 387 388 =back 389 390 =head1 MAPPING ASN.1 TO PERL 391 392 Every element in the ASN.1 definition has a name, in perl a hash is used 393 with these names as an index and the element value as the hash value. 394 395 # ASN.1 396 int INTEGER, 397 str OCTET STRING 398 399 # Perl 400 { int => 5, str => "text" } 401 402 403 In the case of a SEQUENCE, SET or CHOICE then the value in the namespace will 404 be a hash reference which will be the namespce for the elements with 405 that element. 406 407 # ASN.1 408 int INTEGER, 409 seq SEQUENCE { 410 str OCTET STRING, 411 bool BOOLEAN 412 } 413 414 # Perl 415 { int => 5, seq => { str => "text", bool => 1}} 416 417 If the element is a SEQUENCE OF, or SET OF, then the value in the namespace 418 will be an array reference. The elements in the array will be of 419 the type expected by the type following the OF. For example 420 with "SEQUENCE OF STRING" the array would contain strings. With 421 "SEQUENCE OF SEQUENCE { ... }" the array will contain hash references 422 which will be used as namespaces 423 424 # ASN.1 425 int INTEGER, 426 str SEQUENCE OF OCTET STRING 427 428 # Perl 429 { int => 5, str => [ "text1", "text2"]} 430 431 # ASN.1 432 int INTEGER, 433 str SEQUENCE OF SEQUENCE { 434 type OCTET STRING, 435 value INTEGER 436 } 437 438 # Perl 439 { int => 5, str => [ 440 { type => "abc", value => 4 }, 441 { type => "def", value => -1 }, 442 ]} 443 444 =head2 Exceptions 445 446 There are some exceptions where Convert::ASN1 does not require an element to be named. 447 These are SEQUENCE {...}, SET {...} and CHOICE. In each case if the element is not 448 given a name then the elements inside the {...} will share the same namespace as 449 the elements outside of the {...}. 450 451 =head1 TODO 452 453 =over 4 454 455 =item * 456 457 XS implementation. 458 459 =item * 460 461 More documentation. 462 463 =item * 464 465 More tests. 466 467 =back 468 469 =head1 AUTHOR 470 471 Graham Barr <gbarr@pobox.com>, Report bugs via <bug-Convert-ASN1@rt.cpan.org> 472 473 =head1 COPYRIGHT 474 475 Copyright (c) 2000-2005 Graham Barr <gbarr@pobox.com>. All rights reserved. 476 This program is free software; you can redistribute it and/or 477 modify it under the same terms as Perl itself. 478 479 =cut 480
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |