Convert-PEM
view release on metacpan or search on metacpan
);
$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
This method requires either Content or DER. An error will be
generated if one of these arguments are not present.
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 is required unless DER is specified.
* DER
A string containing actual binary of the contents to be encoded.
This bypasses ASN.1 encoding.
May be used in lieu of Content. If specified, will override Content.
* 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.
* Cipher
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)
( run in 1.446 second using v1.01-cache-2.11-cpan-39bf76dae61 )