I had some time and so I write down the specification of the actual OpenCA::OpenSSL including the first interfacebugs.
Perhaps it helps you, Julio.
Best regards
Michael
--
-------------------------------------------------------------------
Michael Bell Email (private): [EMAIL PROTECTED]
Rechenzentrum - Datacenter Email: [EMAIL PROTECTED]
Humboldt-University of Berlin Tel.: +49 (0)30-2093 2482
Unter den Linden 6 Fax: +49 (0)30-2093 2959
10099 Berlin
Germany http://www.openca.org
This document contain the description of the OpenCA::Crypt interface. This interface is the toplayer on all supported cryptoshells.
Variables:
==========
$OpenCA::Crypt::errno
$OpenCA::Crypt::errval
Functions:
==========
* new
* setParams
* genKey
* genReq
* genCert
* issueCert
* revoke
* getDigest (perhaps directly from Digest::XYZ)
* updateDB
* getSMIME
* getPIN
* crl2pkcs7
* dataConvert
* SPKAC
* getCertAttribute
* getReqAttribute
* getCRLAttribute
* pkcs7Certs
* verify
* sign
* getNumericDate
* getOpenSSLDate
Problems:
=========
* md5 is several times the default but sha1 is more secure
* des is used as default but des3 should be the minimum
* dataConvert is really fat but not complete. There are several functions
which convert data but are not part of dataConvert.
Solution: make a full-featured dataConvert which use several functions like
convertCert, convertReq, convertKey, convertCRL, extractCerts
This is better maintainable and more robust.
* sign and verify are seperate programs - a break in the abstractionlayer?
Specification fo functions:
===========================
new
---
Input: see setParams
Output:
* undef if failed
* objectreference if all is ok
setParams
---------
Input:
* CONFIG - the configurationfile for the cryptoshell
* SHELL - the binary of the cryptoshell
* TMPDIR - secure temporary directory
* BINDIR - directory which includes the binaries
* VERIFY - program to verify signatures (incl. absolute path)
* SIGN - program to create signatures (incl. absolute path)
* STDERR - other filename for STDERR
Output: 1
genKey
------
Input:
* BITS - length of the new key (not required)
* OUTFILE - file which contains the new key (not required)
* ALGORITHM - algorithm to encrypt the private key (not required)
# des, 3des or idea
# if PASSWD is set then des is the default
* TYPE - algorithm of the key (not required)
# rsa or dsa
# rsa is the default
* PASSWD (not required)
* ENGINE - name of the used engine (not required)
* RAND - name of the randomfile (not required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the key in rsa-format (should be perhaps in PKCS#8-format?)
* undef if failed
genReq
------
Input:
* ENGINE - name of the used engine (not required)
* OUTFILE - file which contains the new request (not required)
* OUTFORM - outputformat (not required)
# PEM or DER
# PEM is the default
* KEYFILE - name of the file which includes the key (REQUIRED)
* SUBJECT - dn of the request (not required --> REQUIRED)
* the fallback is DN which is deprected --> REQUIRED
* PASSWD - passphrase of the key (not required)
* DN - array with the elements of the dn (absolutely deprecated)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the request in OUTFORM-format (should be perhaps in PKCS#8-format?)
* undef if failed
genCert
-------
This will only be used to generate a self-signed certificate. The function
to create normal certificates is issueCert.
Input:
* ENGINE - name of the used engine (not required)
* OUTFILE - file which contains the new certificate (not required)
* KEYFILE - name of the file which includes the key (REQUIRED)
* REQFILE - name of the file which includes the request (REQUIRED)
* SUBJECT - dn of the request (not required)
* NOEMAILDN - supress the emailaddress in the dn (not required)
* PASSWD - passphrase of the key (not required)
* DAYS- validity period of the certificate
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the certificate in PEM-format
* undef if failed
crl2pkcs7
---------
This function converts a PEM-formatted CRL or some certificates into
a PKCS#7-structure. The name itslef is completely confusing because it is
the name of the OpenSSL-command but the meaning is different from the name.
Input:
* DATA - contains the CRL (not required)
* CRLFILE - contains the CRL (not required)
* INFORM - format of the CRL (not required)
* PEM or DER
* PEM is the default
* OUTFILE - file which contains the new pkcs#7-structure (not required)
* OUTFORM - outputformat (not required)
# PEM or DER
# PEM is the default
* CERTSLIST - an array which contains the filenames of the certificates
(nor required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the pkcs#7-structure in OUTFORM-format
* undef if failed
dataConvert
-----------
Input:
* INFILE or DATA (REQUIRED)
* DATA - the data of the object
* INFILE - the filename which contains the data of the object
* DATATYPE - the objecttype which should be converted (REQUIRED)
* OUTFILE - file which contain the output (not required)
* OUTFORM - format of the output (not required)
* PEM is the default
* INFORM - format of the input (not required)
* PEM is the default
* ALGORITHM - algorithm to encrypt private data
* des, des3, idea
* des is the default (is this a bug - 3-des should be the minimum?)
DATATYPE == CRL
* INFORM - PEM,DER
* OUTFORM - PEM,DER,TXT
* ALGORITHM ignored
DATATYPE == CERTIFICATE
* INFORM - PEM,DER,PKCS12
* OUTFORM - PEM,DER,PKCS12,TXT
* OUTFORM == PKCS12
* NOKEYS is not allowed
* KEYFILE - contains the private key for PKCS#12 conversion
* PASSWD - passphrasse of the private key (not required)
* P12PASSWD - passphrase for the PKCS#12-file (not requird)
* ALGORITHM - algorithm used to encrypt the private key if INFORM is
PKCS#12 and PASSWD is set (not required)
* CACERT - ca-certificate which will be attached to PKCS#12-file
(not required)
* NOKEYS - used to supress the private key if input format is PKS12
DATATYPE == REQUEST
* INFORM - PEM,DER
* OUTFORM - PEM,DER,TXT
DATATYPE == KEY
* INFORM - PEM(SSLeay),DER(SSLeay),PKCS8(PEM)
* OUTFORM - PEM(SSLeay),DER(SSLeay),PKCS8(PEM)
* INPASSWD - input passphrase (not required)
* OUTPASSWD - output passphrase (not required)
* ENCODING - format of the output if OUTFORM is PKCS8
* PEM or DER
* PEM is the default
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the converted object in OUTFORM-format
* undef if failed
issueCert
---------
Input:
* ENGINE - name of the used engine (not required)
* REQDATA or REQFILE (REQUIRE)
* REQDATA - contains the request
* REQFILE - filename of the request
* INFORM - format of the request
* PKCS#10 PEM, PKCS#10 DER or SPKAC
* default is PKCS#10 PEM
* PRESERVE_DN - protect the dn from reconfiguration (not required)
* N is default
* CAKEY - CA-key to sign the certificate
* DAYS - validity period of the certificate (not required)
* START_DATE - OpenSSL timestamp for NOT BEFORE (not required)
* END_DATE - OpenSSL timestamp for NOT AFTER (not required)
* PASSWD - passphrase of the CA-key
* EXTS - section which contains the extensionconfiguration (not required)
* EXTFILE - file which contains the extensionconfiguration (not required)
* SUBJECT - dn of the request (not required)
* REQFILES - requests which has to be handled (not required)
* OUTDIR - directory where the new certs should be placed (not required)
* works only with PEM and DER
* CA_NAME - section which contain the CA-configuration (not required)
* NOEMAILDN - if true then the emailAddress will be supressed in the dn
(not required)
* NOUNIQUEDN - if true then the dn has not to be unique (not required)
Output:
* 1 if succeeded
* undef if failed
* the new certificate is in the directory which was specified by OUTDIR or
in the default directory which was specified in the configuration
revoke
------
Input:
* ENGINE - name of the used engine (not required)
* CAKEY - CA-key (REQUIRED)
* CACERT - CA-certificate (REQUIRED)
* PASSWD - passphrase of the CA-key (REQUIRED)
* INFILE - filename of the certificate which has to be revoked (REQUIRED)
* CRL_REASON - the reason why the certificate was revoked (not required)
* NOUNIQUEDN - if true then the dn has not to be unique (not required)
Output:
* 1 if succeeded
* undef if failed
issueCrl
--------
Input:
* ENGINE - name of the used engine (not required)
* CAKEY - CA-key (REQUIRED)
* CACERT - CA-certificate (REQUIRED)
* PASSWD - passphrase of the CA-key (REQUIRED)
* DAYS - validity period of the CRL (not required)
* OUTFILE - file which contain the output (not required)
* OUTFORM - format of the output (not required)
* PEM or DER
* PEM is the default
* EXTS - section which contains the extensionconfiguration (not required)
* EXTFILE - file which contains the extensionconfiguration (not required)
* NOUNIQUEDN - if true then the dn has not to be unique (not required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the converted object in OUTFORM-format
* undef if failed
SPKAC
-----
This function looks like a relict which was forgotten to integrate into dataConvert
Input:
* ENGINE - name of the used engine (not required)
* INFILE or SPKAC (REQUIRED)
* SPKAC - contains the request
* INFILE - filename of the request
* OUTFILE - file which contains the converted request (not required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the textoutput of the SPKAC-request
* undef if failed
getDigest
---------
Input:
* ENGINE - name of the used engine (not required)
* DATA - data which should be hashed (REQUIRED)
* ALGORITHM - the algorithm which should be used to generate the hash (not
required)
# md5, md4, md2, sha1, sha, mdc2, ripemd160 or dss1
# md5 is the default
Output:
* the digest of the data if succeeded
* undef if failed
verify
------
Input:
* DATA or DATA_FILE (REQUIRED)
* DATA - contains the data
* DATAFILE - filename of the data
* SIGNATURE or SIGNATURE_FILE (REQUIRED)
* SIGNATURE - contains the signature
* SIGNATURE_FILE - filename of the signature
* CA_CERT - ca-cert for chainverification (not required)
* CA_DIR - directory with the ca-chain (not required)
* VERBOSE - the output will be in verbose-format (not required)
* OUTFILE - file where the output is stored (not required)
* NOCHAIN - no chainverification (not required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the textoutput of the verification
* undef if failed
sign
----
Input:
* DATA or DATA_FILE (REQUIRED)
* DATA - contains the data
* DATA_FILE - filename of the data
* OUTFILE - file where the output is stored (not required)
* CERT or CERT_FILE (REQUIRED)
* CERT - contains the certificate
* CERT_FILE - filename of the certificate
* KEY or KEY_FILE (REQUIRED)
* KEY - contains the key
* KEY_FILE - filename of the key
* INCLUDE_DATA -include the data into the PKCS#7-structure
* PWD or PASSWD - passphrase for the key
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the PKCS#7-signature if suceeded
* undef if failed
getCertAttribute
----------------
Input:
* ENGINE - name of the used engine (not required)
* DATA or FILE (REQUIRED)
* DATA - contains the certificate
* FILE - filename of the certificate
* INFORM - format of the certificate (not required)
* PEM or DER
* PEM is the default
* ATTRIBUTE or ATTRIBUTE_LIST (REQUIRED)
* ATTRIBUTE - name of the needed attribute
* ATTRIBUTE_LIST - list of the attributes which should be parsed
* supported attributes
# ALIAS
# DN (SUBJECT)
# EMAILADDRESS
# FINGERPRINT
# HASH
# ISSUER
# MODULUS
# NOTAFTER (ENDDATE)
# NOTBEFORE (STARTDATE)
# PUBKEY
# SERIAL
Output:
* if ATTRIBUTE_LIST defined
* hash if succeeded
* undef if failed
* if ATTRIBUTE_LIST not defined
* the value of the requested attribute if suceeded
* undef if failed
getReqAttribute
---------------
Input:
* ENGINE - name of the used engine (not required)
* DATA or FILE (REQUIRED)
* DATA - contains the certificate
* FILE - filename of the certificate
* FORMAT or INFORM - format of the certificate (not required)
* PEM, DER or SPKAC
* PEM is the default
* ATTRIBUTE or ATTRIBUTE_LIST (REQUIRED)
* ATTRIBUTE - name of the needed attribute
* ATTRIBUTE_LIST - list of the attributes which should be parsed
* supported attributes
# DN (SUBJECT)
# PUBKEY
Output:
* if ATTRIBUTE_LIST defined
* hash if succeeded
* undef if failed
* if ATTRIBUTE_LIST not defined
* the value of the requested attribute if suceeded
* undef if failed
getCRLAttribute
---------------
Input:
* ENGINE - name of the used engine (not required)
* DATA or FILE (REQUIRED)
* DATA - contains the certificate
* FILE - filename of the certificate
* FORMAT or INFORM - format of the certificate (not required)
* PEM, DER or SPKAC
* PEM is the default
* ATTRIBUTE or ATTRIBUTE_LIST (REQUIRED)
* ATTRIBUTE - name of the needed attribute
* ATTRIBUTE_LIST - list of the attributes which should be parsed
* supported attributes
# ISSUER
# LASTUPDATE
# NEXTUPDATE
Output:
* if ATTRIBUTE_LIST defined
* hash if succeeded
* undef if failed
* if ATTRIBUTE_LIST not defined
* the value of the requested attribute if suceeded
* undef if failed
pkcs7Certs
----------
This should be part of dataConvert.
Input:
* ENGINE - name of the used engine (not required)
* OUTFILE - file which contain the output (not required)
* PKCS7 or INFILE (REQUIRED)
* PKCS7 - contains the pkcs#7-structure
* FILE - filename of the pkcs#7-structure
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the output if succeeded
* undef if failed
updateDB
--------
This function updates the internal database of OpenSSL. This is mainly used
to update the certificate state (valid --> expired).
Input:
* CAKEY - filename of the key of the ca-certificate (not required)
* CACERT - filename of the ca-certificate (not required)
* PASSWD - passphrase for the ca-key (not required)
* OUTFILE - file which contain the output (not required)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the output if succeeded
* undef if failed
getSMIME
--------
This is the S/MIME-function of OpenCA.
Input:
* ENGINE - name of the used engine (not required)
* DECRYPT, ENCRYPT or SIGN (REQUIRED)
* DECRYPT - decrypt a given S/MIME-mail
* CERT - certficate which is used for
* ENCRYPT - encrypt a given mail
* SIGN - sign a given mail
* KEY - key which is used for decryption/signing
* PASSWD - passphrase for the key
* ENCRYPT_CERT - certificate for encryption
* SIGN_CERT - certiciate for signing
* INFILE, DATA or MESSAGE (REQUIRED)
* INFILE - this file includes the message (lowest priority)
* DATA - this is the message
* MESSAGE - this is the message (highest priority)
* OUTFILE - file which contain the output (not required)
* TO - the recipient (REQUIRED)
* FROM - the sender (REQURED)
* SUBJECT - the subject of the mail (REQUIRED)
Output:
* if OUTFILE defined
* 1 if succeeded
* undef if failed
* if OUTFILE not defined
* the output if succeeded
* undef if failed
getPIN
------
Generate safe PINs.
Input:
* ENGINE - name of the used engine (not required)
* LENGTH, PIN_LENGTH or RANDOM_LENGTH (REQUIRED)
* LENGTH - set the real length of the PIN (lowest priority)
* PIN_LENGTH - set the real length og the PIN
* RANDOM_LENGTH - set the exact number of random bytes in the PIN
(highest priority)
Output:
* the new PIN if succeeded
* undef if failed
getOpenSSLDate
--------------
Input:
* simply take the first argument as returned by time
Example: Mar 10 19:36:45 2001 GMT
Output:
* timestamp in OpenSSL-format
getNumericDate
--------------
Input:
* simply take the first argument as returned by time
Example: Mar 10 19:36:45 2001 GMT
Output:
* timestampe in numeric format
Example: 20010310193645
