Convert-PEM
view release on metacpan or search on metacpan
NAME
Convert::PEM - Read/write encrypted ASN.1 PEM files
SYNOPSIS
use Convert::PEM;
my $pem = Convert::PEM->new(
Name => "DSA PRIVATE KEY",
Macro => "DSAPrivateKey",
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 an optional 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 when an ASN.1 description is
provided.
* InForm
Specify what type of file to expect when using the *read* method.
Value may be either PEM or DER. Default is "PEM".
If "DER" is specified, encryption options are ignored when using the
*read* method and file is read as an unencrypted blob. This option
does not affect the *decode* behavior.
*InForm* is an optional argument.
* OutForm
Specify what type of file the *write* method should output. Value
may be either PEM or DER. Default is "PEM".
If "DER" is specified, encryption options are ignored when using the
*write* method and the file is written as an uncrypted blob. This
option does not affect the *encode* behavior.
*OutForm* 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
The Cipher to use if a password is provided. This is an optional
argument; if not provided, the default of DES-EDE3-CBC will be used
or the cipher configured is $Convert::PEM::DefaultCipher. See below
for a list of supported ciphers.
$obj = $pem->read(%args)
Reads, decodes, and, optionally, decrypts a PEM file, returning the
object as decoded by *Convert::ASN1* (or binary blob if ASN.1
description was not provided). 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* argument), *%args* can contain:
* Filename
The location of the PEM file that you wish to read.
* InForm
Specify what file type to read. Description can be found under *new*
method. If specified, will override InForm provided in *new* method.
$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.
* OutForm
Specify format to write out. Description can be found under *new*
method. If specified, will override OutForm provided in *new*
method.
$pem->from_der(%args)
Method used internally, but may be accessed directly decode an ASN.1
string into a perl structure object. If the Convert::PEM object has no
ASN.1 definition, this method has no effect.
* DER
Binary string to convert to an object.
This option is required.
* Macro
If the object has an ASN definition, a Macro may be specified. If
specified, it will override the object's Macro if one exists.
Macro is an optional argument.
$pem->to_der(%args)
Method used internally, but may be accessed directly to encode Content
into binary data. If the Convert::PEM object has no ASN.1 definition,
this method has no effect.
* Content
An object to be ASN.1 encoded to a binary string.
* Macro
If the object has an ASN definition, a Macro may be specified. If
specified, it will override the object's Macro if one exists.
Macro is an optional argument.
$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' } );
CONFIGURATION
To support any encryption/decryption, the appropriate cipher module
needs to be installed.
Some settings may be viewed or configured through variables or methods.
Configuration settings are global to the package. If a setting is
changed, it affects all Convert::PEM objects.
$Convert::PEM::DefaultCipher *or* $OBJ->DefaultCipher(*[NEW_CIPHER]*)
Used to configure a default cipher when writing to the disk. When using
the method form " $OBJ-"DefaultCipher([NEW_CIPHER]) >, if NEW_CIPHER is
not specified, will return the current setting. If the specified cipher
is not recognized/valid, an error will be raised.
To list supported ciphers, use "Convert::PEM::list_ciphers". Here is a
list of supported Ciphers:
* DES-CBC
* DES-EDE3-CBC
* AES-128-CBC
* AES-192-CBC
* AES-256-CBC
* CAMELLIA-128-CBC
* CAMELLIA-192-CBC
* CAMELLIA-256-CBC
* IDEA-CBC
* SEED-CBC
Convert::PEM->has_cipher(*$cipher_name*)
Will see if the cipher is supported and is configured with an encryption
module.
Convert::PEM->has_cipher_module(*$cipher_name*)
Will see if the cipher is supported and if the configured encryption
( run in 1.371 second using v1.01-cache-2.11-cpan-437f7b0c052 )