phpman > perldoc > Convert::PEM

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 AT stupidfool.org. All
    rights reserved.