.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Convert::PEM 3pm"
.TH Convert::PEM 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Convert::PEM \- Read/write encrypted ASN.1 PEM files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    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 = \*(Aqprivate\-key.pem\*(Aq;
\&    my $pwd = \*(Aqfoobar\*(Aq;
\&
\&    my $pkey = $pem\->read(
\&                   Filename => $keyfile,
\&                   Password => $pwd
\&             );
\&
\&    $pem\->write(
\&                   Content  => $pkey,
\&                   Password => $pwd,
\&                   Filename => $keyfile
\&             );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIConvert::PEM\fR reads and writes \s-1PEM\s0 files containing \s-1ASN\s0.1\-encoded
objects. The files can optionally be encrypted using a symmetric
cipher algorithm, such as 3DES. An unencrypted \s-1PEM\s0 file might look
something like this:
.PP
.Vb 3
\&    \-\-\-\-\-BEGIN DH PARAMETERS\-\-\-\-\-
\&    MB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=
\&    \-\-\-\-\-END DH PARAMETERS\-\-\-\-\-
.Ve
.PP
The string beginning \f(CW\*(C`MB4C...\*(C'\fR is the Base64\-encoded, \s-1ASN\s0.1\-encoded
\&\*(L"object.\*(R"
.PP
An encrypted file would have headers describing the type of
encryption used, and the initialization vector:
.PP
.Vb 3
\&    \-\-\-\-\-BEGIN DH PARAMETERS\-\-\-\-\-
\&    Proc\-Type: 4,ENCRYPTED
\&    DEK\-Info: DES\-EDE3\-CBC,C814158661DC1449
\&
\&    AFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==
\&    \-\-\-\-\-END DH PARAMETERS\-\-\-\-\-
.Ve
.PP
The two headers (\f(CW\*(C`Proc\-Type\*(C'\fR and \f(CW\*(C`DEK\-Info\*(C'\fR) indicate information
about the type of encryption used, and the string starting with
\&\f(CW\*(C`AFAZ...\*(C'\fR is the Base64\-encoded, encrypted, \s-1ASN\s0.1\-encoded
contents of this \*(L"object.\*(R"
.PP
The initialization vector (\f(CW\*(C`C814158661DC1449\*(C'\fR) is chosen randomly.
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS "$pem = Convert::PEM\->new( %arg )"
.el .SS "\f(CW$pem\fP = Convert::PEM\->new( \f(CW%arg\fP )"
.IX Subsection "$pem = Convert::PEM->new( %arg )"
Constructs a new \fIConvert::PEM\fR object designed to read/write an
object of a specific type (given in \fI\f(CI%arg\fI\fR, see below). Returns the
new object on success, \f(CW\*(C`undef\*(C'\fR on failure (see \fI\s-1ERROR HANDLING\s0\fR for
details).
.PP
\&\fI\f(CI%arg\fI\fR can contain:
.IP "\(bu" 4
Name
.Sp
The name of the object; when decoding a PEM-encoded stream, the name
in the encoding will be checked against the value of \fIName\fR.
Similarly, when encoding an object, the value of \fIName\fR will be used
as the name of the object in the PEM-encoded content. For example, given
the string \f(CW\*(C`FOO BAR\*(C'\fR, the output from \fIencode\fR will start with a
header like:
.Sp
.Vb 1
\&    \-\-\-\-\-BEGIN FOO BAR\-\-\-\-\-
.Ve
.Sp
\&\fIName\fR is a required argument.
.IP "\(bu" 4
\&\s-1ASN\s0
.Sp
An \s-1ASN.1\s0 description of the content to be either encoded or decoded.
.Sp
\&\fI\s-1ASN\s0\fR is a required argument.
.IP "\(bu" 4
Macro
.Sp
If your \s-1ASN.1\s0 description (in the \fI\s-1ASN\s0\fR parameter) includes more than
one \s-1ASN.1\s0 macro definition, you will want to use the \fIMacro\fR parameter
to specify which definition to use when encoding/decoding objects.
For example, if your \s-1ASN.1\s0 description looks like this:
.Sp
.Vb 4
\&    Foo ::= SEQUENCE {
\&        x INTEGER,
\&        bar Bar
\&    }
\&
\&    Bar ::= INTEGER
.Ve
.Sp
If you want to encode/decode a \f(CW\*(C`Foo\*(C'\fR object, you will need to tell
\&\fIConvert::PEM\fR to use the \f(CW\*(C`Foo\*(C'\fR macro definition by using the \fIMacro\fR
parameter and setting the value to \f(CW\*(C`Foo\*(C'\fR.
.Sp
\&\fIMacro\fR is an optional argument.
.ie n .SS "$obj = $pem\->decode(%args)"
.el .SS "\f(CW$obj\fP = \f(CW$pem\fP\->decode(%args)"
.IX Subsection "$obj = $pem->decode(%args)"
Decodes, and, optionally, decrypts a \s-1PEM\s0 file, returning the
object as decoded by \fIConvert::ASN1\fR. The difference between this
method and \fIread\fR is that \fIread\fR reads the contents of a \s-1PEM\s0 file
on disk; this method expects you to pass the \s-1PEM\s0 contents as an
argument.
.PP
If an error occurs while reading the file or decrypting/decoding
the contents, the function returns \fIundef\fR, and you should check
the error message using the \fIerrstr\fR method (below).
.PP
\&\fI\f(CI%args\fI\fR can contain:
.IP "\(bu" 4
Content
.Sp
The \s-1PEM\s0 contents.
.IP "\(bu" 4
Password
.Sp
The password with which the file contents were encrypted.
.Sp
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.
.ie n .SS "$blob = $pem\->encode(%args)"
.el .SS "\f(CW$blob\fP = \f(CW$pem\fP\->encode(%args)"
.IX Subsection "$blob = $pem->encode(%args)"
Constructs the contents for the \s-1PEM\s0 file from an object: \s-1ASN\s0.1\-encodes
the object, optionally encrypts those contents.
.PP
Returns \fIundef\fR on failure (encryption failure, file-writing failure,
etc.); in this case you should check the error message using the
\&\fIerrstr\fR method (below). On success returns the constructed \s-1PEM\s0 string.
.PP
\&\fI\f(CI%args\fI\fR can contain:
.IP "\(bu" 4
Content
.Sp
A hash reference that will be passed to \fIConvert::ASN1::encode\fR,
and which should correspond to the \s-1ASN.1\s0 description you gave to the
\&\fInew\fR method. The hash reference should have the exact same format
as that returned from the \fIread\fR method.
.Sp
This argument is mandatory.
.IP "\(bu" 4
Password
.Sp
A password used to encrypt the contents of the \s-1PEM\s0 file. This is an
optional argument; if not provided the contents will be unencrypted.
.ie n .SS "$obj = $pem\->read(%args)"
.el .SS "\f(CW$obj\fP = \f(CW$pem\fP\->read(%args)"
.IX Subsection "$obj = $pem->read(%args)"
Reads, decodes, and, optionally, decrypts a \s-1PEM\s0 file, returning
the object as decoded by \fIConvert::ASN1\fR. This is implemented
as a wrapper around \fIdecode\fR, with the bonus of reading the \s-1PEM\s0
file from disk for you.
.PP
If an error occurs while reading the file or decrypting/decoding
the contents, the function returns \fIundef\fR, and you should check
the error message using the \fIerrstr\fR method (below).
.PP
In addition to the arguments that can be passed to the \fIdecode\fR
method (minus the \fIContent\fR method), \fI\f(CI%args\fI\fR can contain:
.IP "\(bu" 4
Filename
.Sp
The location of the \s-1PEM\s0 file that you wish to read.
.ie n .SS "$pem\->write(%args)"
.el .SS "\f(CW$pem\fP\->write(%args)"
.IX Subsection "$pem->write(%args)"
Constructs the contents for the \s-1PEM\s0 file from an object: \s-1ASN\s0.1\-encodes
the object, optionally encrypts those contents; then writes the file
to disk. This is implemented as a wrapper around \fIencode\fR, with the
bonus of writing the file to disk for you.
.PP
Returns \fIundef\fR on failure (encryption failure, file-writing failure,
etc.); in this case you should check the error message using the
\&\fIerrstr\fR method (below). On success returns the constructed \s-1PEM\s0 string.
.PP
In addition to the arguments for \fIencode\fR, \fI\f(CI%args\fI\fR can contain:
.IP "\(bu" 4
Filename
.Sp
The location on disk where you'd like the \s-1PEM\s0 file written.
.ie n .SS "$pem\->errstr"
.el .SS "\f(CW$pem\fP\->errstr"
.IX Subsection "$pem->errstr"
Returns the value of the last error that occurred. This should only
be considered meaningful when you've received \fIundef\fR from one of
the functions above; in all other cases its relevance is undefined.
.ie n .SS "$pem\->asn"
.el .SS "\f(CW$pem\fP\->asn"
.IX Subsection "$pem->asn"
Returns the \fIConvert::ASN1\fR object used internally to decode and
encode \s-1ASN.1\s0 representations. This is useful when you wish to
interact directly with that object; for example, if you need to
call \fIconfigure\fR on that object to set the type of big-integer
class to be used when decoding/encoding big integers:
.PP
.Vb 2
\&    $pem\->asn\->configure( decode => { bigint => \*(AqMath::Pari\*(Aq },
\&                          encode => { bigint => \*(AqMath::Pari\*(Aq } );
.Ve
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
If an error occurs in any of the above methods, the method will return
\&\f(CW\*(C`undef\*(C'\fR. You should then call the method \fIerrstr\fR to determine the
source of the error:
.PP
.Vb 1
\&    $pem\->errstr
.Ve
.PP
In the case that you do not yet have a \fIConvert::PEM\fR object (that is,
if an error occurs while creating a \fIConvert::PEM\fR object), the error
can be obtained as a class method:
.PP
.Vb 1
\&    Convert::PEM\->errstr
.Ve
.PP
For example, if you try to decode an encrypted object, and you do not
give a passphrase to decrypt the object:
.PP
.Vb 2
\&    my $obj = $pem\->read( Filename => "encrypted.pem" )
\&        or die "Decryption failed: ", $pem\->errstr;
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
Convert::PEM is free software; you may redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Except where otherwise noted, Convert::PEM is Copyright Benjamin
Trott, cpan@stupidfool.org. All rights reserved.