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.