[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