OpenCA has a concept which abstracts every key. Every key is a token and be putted into a slot. This mean that the software can ask the cryptolayer for a token ca and the cryptolayer checks it's configuration for a token called ca.
Now we will explain the token configuration because this is the most interesting thing for an administrator. The basic schema is the following one:
<openca> <token_config> <default_token>CA</default_token> <token>...</token> ... </token_config> </openca>
Every token configuration includes some common parts which will be described here. The names of the options are tag names!
which will be used by the software for the token. There are four names today - CA, BP (batch processors), KEYBACKUP and LOG.
This defines the type of the token. Today there are three types (OpenSSL, Empty and LunaCA3) but we can add modules for every token you need if the token is supported by OpenSSL. We add a module per token to be able to handle the different details and proprietary tools to manage the tokens.
The mode describes how the token should be used. OpenCA knows three modes standby, session and daemon. standby means that you must login to the token for every action, session activates the token for the whole user session and daemon runs the token in a daemon mode which means that the token must be stopped explicitly. Please read the docs about the different token types because not every token supports every mode.
If the token login requires a password which the user have to enter at the webpage then you should specify a sheet where the user can do it. Usually there are prepared sheets already installed at OPENCADIR/lib/servers/server_name/sheets/token_login.html. So you have only to specify the default sheet.
We will describe now the configuration of different token types.
OpenSSL only support the operational mode standby. Additionaly it support several other dynamic options which are required to work properly.
This is the path to binary of OpenSSL. It is called SHELL because it is the cryptoshell which we use. Simply run the binary without any options and you know what we mean.
filename of the file with the private key
the number of the components of the passphrase. If you have two groups of administrators and every group has only one part of the passphrase then you can enter 2 and OpenCA will display two seperate input fields for the different parts.
path to the PEM formatted certificate
path to the DER formatted certificate
path to the TXT formatted certificate - this is only important for the CA token.
directory which includes the certification path - this is not only important for the CA because the chain is sometimes included into signatures.
This token is only a dummy if the key is not a really seperate key. Often the administrators simply use symlinks to the CA keys and certs for the keybackup etc.. An empty token is redirect to the default token which is usually the CA token.
This token accepts all the options like OpenSSL tokens except of PASSWD_PARTS because Chrysalis-ITS Luna CA3 uses hardware (PIN pad) for login to prevent electronic reconnaisance actions. Luna CA3 supports all operational modes (standby, session and daemon. This module requires some additional options:
Luna CA3 comes with a utility to manage things like login and keygeneration. You have to enter the complete path here.
This is an ID for the slot of the token.
This is the application ID to avoid conflicts with other application. Please remeber that the APPID must be lesser than the SLOT.
OpenCA uses this file to detect that the token is already activated if the token runs in daemon mode. There is no way to find out this fact directly via a tool from Chrysalis-ITS.
This module provides basic support for nCipher HSM tokens and was tested with the following configuration:
SuSE Linux 8.1 and SLES 8
nCipher software
hwsp: 0.0.24cam37, 0.0.34cam7
hwcrhk: 1.9.0cam27, 1.9.7cam24
ctls: 0.0.24cam12, 0.0.32cam27
nCipher Modules verified (others may work)
nShield F3 SCSI module (nC3031S)
nShield F2 PCI module (nC1002P/nC3022P)
nShield F2 SCSI module (nC4022W)
The current status is considered to be stable.
Features:
Uses nCipher hwcrhk application and 'with-nfast' wrapper to perform nShield private key operations.
Detects a number of problems and error conditions:
Middleware not running/operational (HSM online test)
Private key not available (key online test)
Current limitations:
Key generation is not supported (and will probably never be)
PIN entry is not supported
The module was derived from OpenCA::Token::OpenSSL and other existing token implementations.
All external program calls are subject to a hard timeout that is initially set to 6 seconds. This value can be configured by setting the class attribute CHECKCMDTIMEOUT to the desired value (see constructor).
If an external program does not terminate within a certain timeout, it is killed by SIGALRM and the method fails with a timeout error (7151015). This was introduced in order to handle hanging nCipher utility processes after e. g. switching of an external SCSI HSM.
genKey() - This method is administratively disabled and always returns the error code 7154001.
online() - The online test performs the following tests:
Run 'enquiry' and check return code and program output
verify that the nCipher server daemon is operational
verify that at least one nCipher module is operational
The method returns true without calling external checks if the module accessibility was checked within the last 60 seconds. This value can be configured by setting the class attribute ONLINECHECKGRACEPERIOD to the desired value (see constructor).
keyOnline() - The following tests are performed in order to determine the key online status:Run 'nfkminfo' with the WRAPPER command (usually 'with-nfast -M') and check return code and output.
verify Security World status (must be initialized and usable)
verify that at least one object is preloaded
get object hash for private key to be used and verify it against the list of preloaded objects
The module requires a properly set up nCipher "Security World" including a private key to operate. Key generation is not supported by the module (as it really does not make much sense for a HSM based CA).
See Section 2.4.6, “Example for the setup” for an example.
In order to use the HSM protected key, log in into the CA computer and run /opt/nfast/bin/with-nfast pause in a shell.
You will be prompted to insert as many Operator Cards and input their corresponding PINs as required by the Operator Card Set Quorum.
As long as 'with-nfast' is not interrupted and the last Operator Card is not removed, any application with the proper Unix permissions may use the keys protected by the Operator Card Set.
To log out from the module it is recommended to terminate the with-nfast program (pulling the SmartCard works, too, but is not recommended, because it leaves the program waiting).
A simple login mechanism can be implemented using a special HSM login user. The user must have write access to the file /opt/nfast/kmdata/preload/default. For example create a user 'hsmlogin' with primary group 'kmdata'.
Change ownership and permissions of directory /opt/nfast/kmdata/preload so that 'hsmlogin' can enter ("execute") this directory.
Change ownership and permissions of the file /opt/nfast/kmdata/preload/default so that 'hsmlogin' can write to this file and that the www user running the ca CGI script can read it.
Create a login wrapper shell script /usr/local/bin/hsmlogin and assign this as login shell to the 'hsmlogin' user:
#!bin/sh exec /opt/nfast/bin/with-nfast pause
Login as hsmlogin in order to login into the HSM, use Ctrl-C to logout.
The key name should be the same as reported by /opt/nfast/bin/nfkminfo -k.
Example for creation of a Security World, Operator Cards and CA key.
Assumptions:
example uses a 2 of 3 quorum ("2/3") for Adminstrator Cards and Operator Cards
the Operator Card set protecting the CA key will be named "RootCA"
the CA key will be named "rootkey" in this process
Sample Root Key ceremony:
initialize security world
switch HSM to 'initialize' mode
reset the module: /opt/nfast/bin/nopclearfail -c -m 1
/opt/nfast/bin/newworld --initialize --acs-quorum 2/3
switch HSM to 'operational' mode
reset the module: /opt/nfast/bin/nopclearfail -c -m 1
verify that the security world has been created
/opt/nfast/bin/nfkminfo
optionally: erase cards
/opt/nfast/bin/bulkerase -m 1 -s 0
initialize Root CA operator card set
/opt/nfast/bin/createocs --name=RootCA --ocs-quorum=2/3 -m 1 -s 0
verify that the operator card set has been created
/opt/nfast/bin/nfkminfo -c
create Root CA key
/opt/nfast/bin/generatekey2 --cardset=RootCA hwcrhk (example values: token, 0, RootCA, yes, RSA, 2048, 0, "", rootkey, no)
verify that the root key has been created
/opt/nfast/bin/nfkminfo -k
This token accepts all the options like OpenSSL tokens but soem options has another meaning. The token only operates in mode standby. Other modes are not supported by OpenSC today. The available options have the following meanings (please notice that we only report OpenSSL options if there meaning differ from the original OpenSSL module):
The KEY is a combination of the slot and the ID of the key on the card. This can differ for other PKCS#11 modules than OpenSC. If you use this class with another PKCS#11 than the one from OpenSC then please read the docs of the vendor. The syntax is slot_[0-9]+-id_[0-9]+. A typical example is slot_0-id_45.
The value should be always pkcs11 here. This defines that the OpenSSL dynamic engine pkcs11 should be used. The module is only tested with this module.
These options are used to configure the PKCS#11 engine which is loaded to OpenSSL. SO_PATH is the path of the used OpenSSL engine. ID is the used OpenSSL engine ID. MODULE_PATH is the path to the used PKCS#11 driver. Please notice that we put the complete and partially internal configuration into this parameter. The reason is that we don't want to reduce the flexibility because we don't know the future direction of the OpenSSL engine interface and the OpenSC PKCS#11 engine for OpenSSL.
This is the name of the OpenSC carddriver. This option is only necessary if you want to create the key with OpenCA.
This is the number of the OpenSC carddriver. This option is only necessary if you want to create the key with OpenCA. (It is identical with the slotnumber.)
The path to the command pkcs15-init.
The path to the command pkcs15-tool.
The path to the command opensc-tool.