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 $keyfile = 'private-key.pem';
my $pwd = 'foobar';
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:
* Name
The name of the object; when decoding a PEM-encoded stream, the name
in the encoding will be checked against the value of *Name*.
Similarly, when encoding an object, the value of *Name* will be used
as the name of the object in the PEM-encoded content. For example,
given the string "FOO BAR", the output from *encode* will start with
a header like:
-----BEGIN FOO BAR-----
*Name* is a required argument.
* ASN
An ASN.1 description of the content to be either encoded or decoded.
*ASN* is a required argument.
* Macro
If your ASN.1 description (in the *ASN* parameter) includes more
than one ASN.1 macro definition, you will want to use the *Macro*
parameter to specify which definition to use when encoding/decoding
objects. For example, if your ASN.1 description looks like this:
Foo ::= SEQUENCE {
x INTEGER,
bar Bar
}
Bar ::= INTEGER
If you want to encode/decode a "Foo" object, you will need to tell
*Convert::PEM* to use the "Foo" macro definition by using the
*Macro* parameter and setting the value to "Foo".
*Macro* is an optional argument.
$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:
* Content
The PEM contents.
* Password
The password with which the file contents were encrypted.
If the file is encrypted, this is a mandatory argument (well, it's
not strictly mandatory, but decryption isn't going to work without
it). Otherwise it's not necessary.
$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:
* Content
A hash reference that will be passed to *Convert::ASN1::encode*, and
which should correspond to the ASN.1 description you gave to the
*new* method. The hash reference should have the exact same format
as that returned from the *read* method.
This argument is mandatory.
* Password
A password used to encrypt the contents of the PEM file. This is an
optional argument; if not provided the contents will be unencrypted.
$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:
* Filename
The location of the PEM file that you wish to read.
$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:
* Filename
The location on disk where you'd like the PEM file written.
$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;
LICENSE
Convert::PEM is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
AUTHOR & COPYRIGHTS
Except where otherwise noted, Convert::PEM is Copyright Benjamin Trott,
cpan@stupidfool.org. All rights reserved.