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 crl2pkcs7 () - Convert a crl and/or certs into pkcs7 structure.

	This function converts certificates (optional) and a crl
	(also optional) into a pkcs7 structure. It is used to build
	strucutures to load certificates/crls into some browsers.
	Accepted parameters are:

		DATA      - PEM|DER formatted CRL(*);
		INFORM    - Input crl format (DER|PEM) (*);
		OUTFORM   - Output pkcs7 structure format (DER|PEM) (*);
		INFILE    - Input crl file (*);
		OUTFILE   - Output pkcs7 file (*);
		CERTSLIST - List of files containing certificates to
                            be added to the pkcs7 structure (*);

	(*) - Optional parameters;

	EXAMPLE:

		$pkcs7 = $openssl->crl2pkcs7( DATA=>$crl->getPEM(),
				CERTSLIST=>[ "cert1.pem", "cert2.pem" ]);

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.
	CACERT	- CA-certificate to add if OUTFORM is PKCS#12

(*) - 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);

sub updateDB () - Updates the OpenSSL index.txt

This functions updates the index.txt file and returns the
output of the command in the form:

	<SER>=Expired

Accepted parameters are:

	CAKEY   - CA private key file;
	CACERT  - CA certificate file;
	PASSWD  - Password to decrypt priv. CA key(*);
	OUTFILE - Output file(*);

(*) - Optional parameters;

EXAMPLE:

	$ret = $openssl->updateDB();

Exportable constants

CTX_TEST
EXFLAG_BCONS
EXFLAG_CA
EXFLAG_INVALID
EXFLAG_KUSAGE
EXFLAG_NSCERT
EXFLAG_SET
EXFLAG_SS
EXFLAG_V1
EXFLAG_XKUSAGE
GEN_DIRNAME
GEN_DNS
GEN_EDIPARTY
GEN_EMAIL
GEN_IPADD
GEN_OTHERNAME
GEN_RID
GEN_URI
GEN_X400
KU_CRL_SIGN
KU_DATA_ENCIPHERMENT
KU_DECIPHER_ONLY
KU_DIGITAL_SIGNATURE
KU_ENCIPHER_ONLY
KU_KEY_AGREEMENT
KU_KEY_CERT_SIGN
KU_KEY_ENCIPHERMENT
KU_NON_REPUDIATION
NS_OBJSIGN
NS_OBJSIGN_CA
NS_SMIME
NS_SMIME_CA
NS_SSL_CA
NS_SSL_CLIENT
NS_SSL_SERVER
X509V3_EXT_CTX_DEP
X509V3_EXT_DYNAMIC
X509V3_EXT_MULTILINE
X509V3_F_COPY_EMAIL
X509V3_F_COPY_ISSUER
X509V3_F_DO_EXT_CONF
X509V3_F_DO_EXT_I2D
X509V3_F_HEX_TO_STRING
X509V3_F_I2S_ASN1_ENUMERATED
X509V3_F_I2S_ASN1_INTEGER
X509V3_F_I2V_AUTHORITY_INFO_ACCESS
X509V3_F_NOTICE_SECTION
X509V3_F_NREF_NOS
X509V3_F_POLICY_SECTION
X509V3_F_R2I_CERTPOL
X509V3_F_S2I_ASN1_IA5STRING
X509V3_F_S2I_ASN1_INTEGER
X509V3_F_S2I_ASN1_OCTET_STRING
X509V3_F_S2I_ASN1_SKEY_ID
X509V3_F_S2I_S2I_SKEY_ID
X509V3_F_STRING_TO_HEX
X509V3_F_SXNET_ADD_ASC
X509V3_F_SXNET_ADD_ID_INTEGER
X509V3_F_SXNET_ADD_ID_ULONG
X509V3_F_SXNET_GET_ID_ASC
X509V3_F_SXNET_GET_ID_ULONG
X509V3_F_V2I_ACCESS_DESCRIPTION
X509V3_F_V2I_ASN1_BIT_STRING
X509V3_F_V2I_AUTHORITY_KEYID
X509V3_F_V2I_BASIC_CONSTRAINTS
X509V3_F_V2I_CRLD
X509V3_F_V2I_EXT_KU
X509V3_F_V2I_GENERAL_NAME
X509V3_F_V2I_GENERAL_NAMES
X509V3_F_V3_GENERIC_EXTENSION
X509V3_F_X509V3_ADD_VALUE
X509V3_F_X509V3_EXT_ADD
X509V3_F_X509V3_EXT_ADD_ALIAS
X509V3_F_X509V3_EXT_CONF
X509V3_F_X509V3_EXT_I2D
X509V3_F_X509V3_GET_VALUE_BOOL
X509V3_F_X509V3_PARSE_LIST
X509V3_F_X509_PURPOSE_ADD
X509V3_R_BAD_IP_ADDRESS
X509V3_R_BAD_OBJECT
X509V3_R_BN_DEC2BN_ERROR
X509V3_R_BN_TO_ASN1_INTEGER_ERROR
X509V3_R_DUPLICATE_ZONE_ID
X509V3_R_ERROR_CONVERTING_ZONE
X509V3_R_ERROR_IN_EXTENSION
X509V3_R_EXPECTED_A_SECTION_NAME
X509V3_R_EXTENSION_NAME_ERROR
X509V3_R_EXTENSION_NOT_FOUND
X509V3_R_EXTENSION_SETTING_NOT_SUPPORTED
X509V3_R_EXTENSION_VALUE_ERROR
X509V3_R_ILLEGAL_HEX_DIGIT
X509V3_R_INVALID_BOOLEAN_STRING
X509V3_R_INVALID_EXTENSION_STRING
X509V3_R_INVALID_NAME
X509V3_R_INVALID_NULL_ARGUMENT
X509V3_R_INVALID_NULL_NAME
X509V3_R_INVALID_NULL_VALUE
X509V3_R_INVALID_NUMBER
X509V3_R_INVALID_NUMBERS
X509V3_R_INVALID_OBJECT_IDENTIFIER
X509V3_R_INVALID_OPTION
X509V3_R_INVALID_POLICY_IDENTIFIER
X509V3_R_INVALID_SECTION
X509V3_R_INVALID_SYNTAX
X509V3_R_ISSUER_DECODE_ERROR
X509V3_R_MISSING_VALUE
X509V3_R_NEED_ORGANIZATION_AND_NUMBERS
X509V3_R_NO_CONFIG_DATABASE
X509V3_R_NO_ISSUER_CERTIFICATE
X509V3_R_NO_ISSUER_DETAILS
X509V3_R_NO_POLICY_IDENTIFIER
X509V3_R_NO_PUBLIC_KEY
X509V3_R_NO_SUBJECT_DETAILS
X509V3_R_ODD_NUMBER_OF_DIGITS
X509V3_R_UNABLE_TO_GET_ISSUER_DETAILS
X509V3_R_UNABLE_TO_GET_ISSUER_KEYID
X509V3_R_UNKNOWN_BIT_STRING_ARGUMENT
X509V3_R_UNKNOWN_EXTENSION
X509V3_R_UNKNOWN_EXTENSION_NAME
X509V3_R_UNKNOWN_OPTION
X509V3_R_UNSUPPORTED_OPTION
X509V3_R_USER_TOO_LONG
X509_PURPOSE_ANY
X509_PURPOSE_CRL_SIGN
X509_PURPOSE_DYNAMIC
X509_PURPOSE_DYNAMIC_NAME
X509_PURPOSE_MAX
X509_PURPOSE_MIN
X509_PURPOSE_NS_SSL_SERVER
X509_PURPOSE_SMIME_ENCRYPT
X509_PURPOSE_SMIME_SIGN
X509_PURPOSE_SSL_CLIENT
X509_PURPOSE_SSL_SERVER
XKU_CODE_SIGN
XKU_SGC
XKU_SMIME
XKU_SSL_CLIENT
XKU_SSL_SERVER

AUTHOR

Massimiliano Pala <madwolf@openca.org> Julio Sanchez, <j_sanchez@localdomain>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)