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 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) 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 module is usable. If it is not usable, will return "undef". If it is usable, will return the name of the cipher module. Convert::PEM->set_cipher_module($cipher,$module[,$all]) This function/method is used to specify a module name for a supported cipher. It accepts 2 or 3 arguments. Convert::PEM->set_cipher_module(, [,0]) or $OBJ->set_cipher_module(, [,0]) "cipher_name" A supported cipher name. Use Convert::PEM::list_ciphers() to retrieve a list of supported ciphers. "module_name" A cipher module. The module must support the following methods: $cipher_object = Cipher->new($key) $cipher_object->encrypt($plaintext) $cipher_object->decrypt($ciphertext) $cipher_object->blocksize() "all" An optional boolean argument. If true will replace the modules for all supported ciphers matching the cipher being set. Default is true. If setting a cipher, only set this to false if it is desired to use a separate cipher for different key lengths of the same algorithm. Convert::PEM->list_cipher_modules([$cipher_name]) If a *cipher_name* is provided, will return the module configured for the matching cipher name or "undef" if cipher is not supported. If *cipher_name* is not provided, will return a list of modules names configured as an array in array context or as a colon separated list in scalar context. Here is a list of the cipher modules used by default. * Crypt::DES * Crypt::DES_EDE3 * Crypt::Rijndael - "AES-128-CBC, AES-192-CBC and AES-256-CBC" * Crypt::Camellia - "CAMELLIA-128-CBC, CAMELLIA-192-CBC and CAMELLIA-256-CBC" * Crypt::IDEA * Crypt::SEED 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@stupidfool.org. All rights reserved.