Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Convert::PEM(3)	      User Contributed Perl Documentation      Convert::PEM(3)

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:

       o   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.

       o   ASN

	   An ASN.1 description	of the content to be either encoded or
	   decoded.

	   ASN is a required argument.

       o   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:

       o   Content

	   The PEM contents.

       o   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:

       o   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.

       o   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:

       o   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:

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

perl v5.32.1			  2010-12-07		       Convert::PEM(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | ERROR HANDLING | LICENSE | AUTHOR & COPYRIGHTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Convert::PEM&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help