/ 
OpenCA-OpenSSL-0.8.43
River stage one • 1 direct dependent • 1 total dependent
/ OpenCA::OpenSSL

NAME

OpenCA::OpenSSL - Perl Crypto Extention to OpenSSL

SYNOPSIS

use OpenCA::OpenSSL;

DESCRIPTION

This Perl Module implements an interface to the openssl backend program. It actually uses the openssl command and it is not fully integrated as PERL/C mixture.

Passing parameters to functions should be very simple as them have no particular order and have, often, self-explaining name. Each parameter should be passed to the function like this:

... ( NAME=>VALUE, NAME=>VALUE, ... );

FUNCTIONS

sub new () - Creates a new Class instance.

This functions creates a new instance of the class. It accepts
only one parameter: the path to the backend command (openssl).
This is due because if it cannot find the openssl command it
will return an uninitialized class (default value is /usr/bin/
openssl which may not fit many distributions/OSs)

EXAMPLE:

	my $openssl->new OpenCA::OpenSSL( $path );

sub setParams () - Set internal module variables.

This function can handle the internal module data such as the
backend path or the tmp dir. Accepted parameters are:

	SHELL   - Path to the openssl command.
	CONFIG  - Path to the openssl config file.
	TMPDIR  - Temporary files directory.
	STDERR  - Where to redirect the STDERR file.

(*) - Optional parameters;

EXAMPLE:

	$openssl->setParams( SHELL=>'/usr/local/ssl/bin/openssl',
			     CONFIG=>$ca/stuff/openssl.cnf,
			     TMPDIR=>'/tmp',
			     STDERR=>'/dev/null' );

sub errno () - Get last command errno value.

	This functions returns last operation's errno value. Non
        zero value means there has been an error.

	EXAMPLE:

		print $openssl->errno;

sub errval () - Get last command errval value.

	This functions returns last operation's errval value. This
        value usually has a brief error description.

	EXAMPLE:

		print $openssl->errval;

sub genKey () - Generate a private Key.

This functions let you generate a new private key. Accepted
parameters are:

	BITS      - key lengh in bits(*);
	OUTFILE   - Output file name(*);
	ALGORITHM - Encryption Algorithm to be used(*);
	PASSWD    - Password to be used when encrypting(*);

(*) - Optional parameters;

EXAMPLE:

	my $key = $openssl->genKey( BITS=>1024 );

sub genReq () - Generate a new Request.

	This function generate a new certificate request. Accepted
	parameters are:

		OUTFILE  - Output file(*);
		KEYFILE  - File containing the key;
		PASSWD   - Password to decript key (if needed) (*);
		DN       - Subject list (as required by openssl, see
			   the openssl.cnf doc on policy);
		SUBJECT  - DN string (use this instead of passing separate
                           attributes list)(*);

	(*) - Optional parameters;

	EXAMPLE:

		my $req = $openssl->genReq( KEYFILE=>"00_key.pem",
			DN => [ "madwolf@openca.org","Max","","","" ] );

		my $req = $openssl->genReq( KEYFILE=>"00_key.pem",
			SUBJECT => "CN=Madwolf, O=OpenCA, C=IT" );

sub genCert () - Generate a certificate from a request.

This function let you generate a new certificate starting
from the request file. It is used for self-signed certificate
as it simply converts the request into a x509 structure.
Accepted parameters are:

	OUTFILE   - Output file(*);
	KEYFILE   - File containing the private key;
	REQFILE   - Request File;
	PASSWD    - Password to decrypt private key(*);
	DAYS      - Validity days(*);

(*) - Optional parameters;

EXAMPLE:

	$cert = $openssl->genCert( KEYFILE=>"priv_key.pem",
		REQFILE=>"req.pem",
		DAYS=>"720" );

sub dataConvert () - Convert data to different format.

This functions will convert data you pass to another format. Ir
requires you to provide with the data's type and IN/OUT format.
Accepted parameters are:

	DATA    - Data to be processed;
	INFILE  - Data file to be processed (one of DATA and
	  	  INFILE are required and exclusive);
	KEYFILE  - file with the priv. key (* PEM to PKCS12 only).
	           Not needed if key is presented in DATA or INFILE too.
	DATATYPE - Data type ( CRL | CERTIFICATE | REQUEST );
	OUTFORM  - Output format (PEM|DER|NET|TXT)(*);
	INFORM   - Input format (PEM|DER|NET|TXT)(*);
	OUTFILE  - Output file(*);
	PASSWD   - priv. key password (* PKCS12 to PEM only)
		   omitting the PASSWD leads into an unencrypted priv. key 
	ALGO     - des,des3 or idea. Default is des3 encryption for priv. key
	P12PASSWD - PKCS12 export password (* only needed for PKCS12)
	NOKEYS   - extract only the certificate (* PKCS12 to PEM only)
	           No need for the PASSWD parameter with this option.

(*) - Optional parameters;

EXAMPLES:
	# PEM file to TXT format
	print $openssl->dataConvert( INFILE=>"crl.pem",
		OUTFORM=>"TXT" );

	# PEM file to PKCS12 format, priv key will be des3 encrypted
	print $openssl->dataConvert( INFILE=>"crl.pem",
		DATATYPE=>'CERTIFICATE',
		OUTFORM=>"PKCS12",
		PASSWD=>$pem_pass,
		P12PASSWD=>$export_pass );

	# PKCS12 data to PEM formated certificate (no key)
	print $openssl->dataConvert( DATA=>$pkcs12_cert,
		DATATYPE=>'CERTIFICATE',
		INFORM=>"PKCS12",
		NOKEYS=>1,
		P12PASSWD=>$export_pass );

sub issueCert () - Issue a certificate.

This function should be used when you have a CA certificate and
a request (either DER|PEM|SPKAC) and want to issue the certificate.
Parameters used will override the configuration values (remember
to set to appropriate value the CONFIG with the setParams func).
Accepted parameters are:

	REQDATA       - Request;
	REQFILE       - File containing the request (one of
			REQDATA, REQFILE or REQFILES are required);
	REQFILES      - An array ref to an array of files that
			contain the request.
	OUTDIR        - What directory to put the files from 
			REQFILES. (This is required iff 
			you use REQFILES.)
	INFORM        - Input format (PEM|DER|NET|SPKAC)(*);
	PRESERVE_DN   - Preserve DN order (Y|N)(*);
	CA_NAME	      - CA sub section to be used (take a
			look at the OpenSSL docs for adding
			support of multiple CAs to the conf
			file)(*);
	CAKEY	      - CA key file;
	CACERT	      - CA certificate file;
	DAYS	      - Days the certificate will be valid(*);
	START_DATE    - Starting validity date (YYMMDDHHMMSSZ)(*);
	END_DATE      - Ending validity date (YYMMDDHHMMSSZ)(*);
	PASSWD	      - Password to decrypt priv. CA key(*);
	EXTS	      - Extentions to be used (configuration
			section of the openssl.cnf file)(*);
	REQTYPE	      - Request type (NETSCAPE|MSIE)(*);

(*) - Optional parameters;

EXAMPLE:

	$openssl->issueCert( REQFILE=>"myreq",
		INFORM=>SPKAC,
		PRESERVE_DN=>Y,
		CAKEY=>$ca/private/cakey.pem,
		CACERT=>$ca/cacert.pem,
		PASSWD=>$passwd,
		REQTYPE=>NETSCAPE );

sub revoke () - Revoke a certificate.

This function is used to revoke a certificate. Accepted parameters
are:

	CAKEY   - CA private key file(*);
	CACERT  - CA certificate file(*);
	PASSWD  - Password to decrypt priv. CA key(*);
	INFILE  - Input PEM formatted certificate filename(*);

(*) - Optional parameters;

EXAMPLE:

	if( not $openssl->revoke( INFILE=>$certFile ) ) {
		print "Error while revoking certificate!";
	}

sub issueCrl () - Issue a CRL.

This function is used to issue a CRL. Accepted parameters
are:

	CAKEY   - CA private key file;
	CACERT  - CA certificate file;
	PASSWD  - Password to decrypt priv. CA key(*);
	DAYS    - Days the CRL will be valid for(*);
	EXTS    - Extentions to be added ( see the openssl.cnf
		  pages for more help on this )(*);
	EXTFILE - Extensions file to be used (*);
	OUTFILE - Output file(*);
	OUTFORM - Output format (PEM|DER|NET|TXT)(*);

(*) - Optional parameters;

EXAMPLE:

	print $openssl->issueCrl( CAKEY=>"$ca/private/cakey.pem",
				  CACERT=>"$ca/cacert.pem",
				  DAYS=>7,
				  OUTFORM=>TXT );

sub SPKAC () - Get SPKAC infos.

This function returns a text containing all major info
about an spkac structure. Accepted parameters are:

	SPKAC     - spkac data ( SPKAC = .... ) (*);
	INFILE	  - An spkac request file (*);
	OUTFILE   - Output file (*);
	
(*) - Optional parameters;

EXAMPLE:

	print $openssl->SPKAC( SPKAC=>$data, OUTFILE=>$target );

sub pkcs7Certs () - Get PKCS7 structure certificate(s).

This function returns a PEM formatted (file or ret value)
contained in the pkcs7 structure. Accepted parameters are:

	PKCS7     - pkcs7 data (*);
	INFILE	  - A pkcs7 (signature?) file (*);
	OUTFILE   - Output file (*);
	
(*) - Optional parameters;

EXAMPLE:

	print $openssl->pkcs7Cert( PKCS7=>$data, OUTFILE=>$target );

sub getDigest () - Get a message digest.

This function returns a message digest. Default digest
algorithm used is MD5. Accepted parameters are:

	DATA      - Data on which to perform digest;
	ALGORITHM - Algorithm to be used(*);
	
(*) - Optional parameters;

EXAMPLE:

	print $openssl->getDigest( DATA=>$data,
				   ALGORITHM=>sha1);

AUTHOR

Massimiliano Pala <madwolf@openca.org>

SEE ALSO

OpenCA::X509, OpenCA::CRL, OpenCA::REQ, OpenCA::TRIStateCGI, OpenCA::Configuration