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. Works with OpenSSL static and dynamic engine support (automatic detection from configuration).
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 15 seconds. This value can be configured by setting CHECKCMDTIMEOUT to the desired value in the token configuration file.
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 variable ONLINECHECKGRACEPERIOD to the desired value in the token config file.
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. This configuration reflects the use of OpenSSL static engine support. In order to use dynamic engine (e. g. when using OpenSSL 0.9.8), it is necessary to specify the location of the dynamic engine nCipher shared library in the token configuration:
<option> <name>PRE_ENGINE</name> <value>SO_PATH:/usr/local/openssl-snap/lib/engines/libncipher.so</value> </option>
Be sure to specify the correct location of the dynamic engine lib for the OpenSSL binary specified with the SHELL setting.
If at least one PRE_ENGINE setting is specified, the nCipher token module will automatically switch to dynamic engine semantics when talking to the OpenSSL backend. Definition of SO_PATH is the only mandatory setting in this case, and the following default PRE_ENGINE settings are automatically added (unless explicitly specified in the token configuration file):
ID:chil
LIST_ADD:1
LOAD
THREAD_LOCKING:1
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.
token.xml
with a freely
choosable name.