DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Convert::PEM



NAME

Convert::PEM - Read/write encrypted ASN.1 PEM files


SYNOPSIS

    use Convert::PEM;
    my $pem = Convert::PEM->new(
                   Name => "DSA PRIVATE KEY",
                   ASN => qq(
                       DSAPrivateKey SEQUENCE {
                           version INTEGER,
                           p INTEGER,
                           q INTEGER,
                           g INTEGER,
                           pub_key INTEGER,
                           priv_key INTEGER
                       }
                  ));
    my $pkey = $pem->read(
                   Filename => $keyfile,
                   Password => $pwd
             );
    $pem->write(
                   Content  => $pkey,
                   Password => $pwd,
                   Filename => $keyfile
             );


DESCRIPTION

Convert::PEM reads and writes PEM files containing ASN.1-encoded objects. The files can optionally be encrypted using a symmetric cipher algorithm, such as 3DES. An unencrypted PEM file might look something like this:

    -----BEGIN DH PARAMETERS-----
    MB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=
    -----END DH PARAMETERS-----

The string beginning MB4C... is the Base64-encoded, ASN.1-encoded ``object.''

An encrypted file would have headers describing the type of encryption used, and the initialization vector:

    -----BEGIN DH PARAMETERS-----
    Proc-Type: 4,ENCRYPTED
    DEK-Info: DES-EDE3-CBC,C814158661DC1449
    AFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==
    -----END DH PARAMETERS-----

The two headers (Proc-Type and DEK-Info) indicate information about the type of encryption used, and the string starting with AFAZ... is the Base64-encoded, encrypted, ASN.1-encoded contents of this ``object.''

The initialization vector (C814158661DC1449) is chosen randomly.


USAGE

$pem = Convert::PEM->new( %arg )

Constructs a new Convert::PEM object designed to read/write an object of a specific type (given in %arg, see below). Returns the new object on success, undef on failure (see ERROR HANDLING for details).

%arg can contain:

$obj = $pem->decode(%args)

Decodes, and, optionally, decrypts a PEM file, returning the object as decoded by Convert::ASN1. The difference between this method and read is that read reads the contents of a PEM file on disk; this method expects you to pass the PEM contents as an argument.

If an error occurs while reading the file or decrypting/decoding the contents, the function returns undef, and you should check the error message using the errstr method (below).

%args can contain:

$blob = $pem->encode(%args)

Constructs the contents for the PEM file from an object: ASN.1-encodes the object, optionally encrypts those contents.

Returns undef on failure (encryption failure, file-writing failure, etc.); in this case you should check the error message using the errstr method (below). On success returns the constructed PEM string.

%args can contain:

$obj = $pem->read(%args)

Reads, decodes, and, optionally, decrypts a PEM file, returning the object as decoded by Convert::ASN1. This is implemented as a wrapper around decode, with the bonus of reading the PEM file from disk for you.

If an error occurs while reading the file or decrypting/decoding the contents, the function returns undef, and you should check the error message using the errstr method (below).

In addition to the arguments that can be passed to the decode method (minus the Content method), %args can contain:

$pem->write(%args)

Constructs the contents for the PEM file from an object: ASN.1-encodes the object, optionally encrypts those contents; then writes the file to disk. This is implemented as a wrapper around encode, with the bonus of writing the file to disk for you.

Returns undef on failure (encryption failure, file-writing failure, etc.); in this case you should check the error message using the errstr method (below). On success returns the constructed PEM string.

In addition to the arguments for encode, %args can contain:

$pem->errstr

Returns the value of the last error that occurred. This should only be considered meaningful when you've received undef from one of the functions above; in all other cases its relevance is undefined.

$pem->asn

Returns the Convert::ASN1 object used internally to decode and encode ASN.1 representations. This is useful when you wish to interact directly with that object; for example, if you need to call configure on that object to set the type of big-integer class to be used when decoding/encoding big integers:

    $pem->asn->configure( decode => { bigint => 'Math::Pari' },
                          encode => { bigint => 'Math::Pari' } );


ERROR HANDLING

If an error occurs in any of the above methods, the method will return undef. You should then call the method errstr to determine the source of the error:

    $pem->errstr

In the case that you do not yet have a Convert::PEM object (that is, if an error occurs while creating a Convert::PEM object), the error can be obtained as a class method:

    Convert::PEM->errstr

For example, if you try to decode an encrypted object, and you do not give a passphrase to decrypt the object:

    my $obj = $pem->read( Filename => "encrypted.pem" )
        or die "Decryption failed: ", $pem->errstr;


AUTHOR & COPYRIGHTS

Benjamin Trott, ben@rhumba.pair.com

Except where otherwise noted, Convert::PEM is Copyright 2001 Benjamin Trott. All rights reserved. Convert::PEM is free software; you may redistribute it and/or modify it under the same terms as Perl itself.