2. Token and keyconfiguration

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.

Figure 4.3. Tokenconcept

Here you can see a schemtaic overview about the concept
                        of the tokens.

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!

name

which will be used by the software for the token. There are four names today - CA, BP (batch processors), KEYBACKUP and LOG.

type

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.

mode

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.

login_sheet

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.

2.1. OpenSSL

OpenSSL only support the operational mode standby. Additionaly it support several other dynamic options which are required to work properly.

SHELL

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.

KEY

filename of the file with the private key

PASSWD_PARTS

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.

PEM_CERT

path to the PEM formatted certificate

DER_CERT

path to the DER formatted certificate

TXT_CERT

path to the TXT formatted certificate - this is only important for the CA token.

CHAIN

directory which includes the certification path - this is not only important for the CA because the chain is sometimes included into signatures.

2.2. Empty

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.

2.3. LunaCA3

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:

UTILITY

Luna CA3 comes with a utility to manage things like login and keygeneration. You have to enter the complete path here.

SLOT

This is an ID for the slot of the token.

APPID

This is the application ID to avoid conflicts with other application. Please remeber that the APPID must be lesser than the SLOT.

LOCK_FILE

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.

2.4. nCipher

2.4.1. Introduction

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

2.4.2. Implementation

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

2.4.3. Usage

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).

2.4.4. HSM login shell

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.

2.4.5. OpenCA Configuration

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

2.4.6. Example for the setup

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:

  1. 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

  2. verify that the security world has been created

    • /opt/nfast/bin/nfkminfo

  3. optionally: erase cards

    • /opt/nfast/bin/bulkerase -m 1 -s 0

  4. initialize Root CA operator card set

    • /opt/nfast/bin/createocs --name=RootCA --ocs-quorum=2/3 -m 1 -s 0

  5. verify that the operator card set has been created

    • /opt/nfast/bin/nfkminfo -c

  6. create Root CA key

    • /opt/nfast/bin/generatekey2 --cardset=RootCA hwcrhk (example values: token, 0, RootCA, yes, RSA, 2048, 0, "", rootkey, no)

  7. verify that the root key has been created

    • /opt/nfast/bin/nfkminfo -k

2.5. OpenSC

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):

KEY

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.

ENGINE

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.

PRE_ENGINE

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.

CARDDRIVER

This is the name of the OpenSC carddriver. This option is only necessary if you want to create the key with OpenCA.

CARDREADER

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.)

PKCS15_INIT

The path to the command pkcs15-init.

PKCS15_TOOL

The path to the command pkcs15-tool.

OPENSC_TOOL

The path to the command opensc-tool.

Note

If you get performance problems with an OpenSC engine what is normal because smartcards are not fast then please configure another default token than the CA token. You can create a new token in token.xml with a freely choosable name.