Convert::PEM - Read/write encrypted ASN.1 PEM files
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
);
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.
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.
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.
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.
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.
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.
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.
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' } );
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;
Convert::PEM is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.
Except where otherwise noted, Convert::PEM is Copyright Benjamin Trott,
[email protected]. All rights reserved.