The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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>

SEE ALSO

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