openCryptoki overview

openCryptoki consists of an implementation of the PKCS #11 API, a slot manager, an API for slot token dynamic link libraries (STDLLs), and a set of STDLLs (or tokens). The EP11 token is a new STDLL introduced with openCryptoki version 3.1.

The openCryptoki base library (libopencryptoki.so) provides the generic API as outlined in the PKCS #11 specification (version 2.20). This library also loads token-specific modules (STDLLs) that provide the token specific implementation of the PKCS #11 API and cryptographic functions (for example, session management, object management, and crypto algorithms). For a description of the PKCS #11 version 2.20 standard, refer to the following URL: PKCS #11 Cryptographic Token Interface Standard

A global configuration file (/etc/opencryptoki/opencryptoki.conf) is provided which describes the available tokens. This configuration file can be customized for the individual tokens. The openCryptoki package contains man pages that describe the format of the configuration files. For more information, see Adjusting the openCryptoki configuration file.

The EP11 token is a plug-in into the openCryptoki token library, providing support for several cryptographic algorithms.

Slot manager

The slot manager (pkcsslotd) runs as a daemon. Upon startup, it creates a shared memory segment and reads the openCryptoki configuration file to acquire the available token and slot information. The openCryptoki API attaches to this memory segment to retrieve token information. Thus, the slot manager provides the openCryptoki API with the token information when required. An application in turn links to or loads the openCryptoki API.

Slot token dynamic link libraries (STDLLs)

The EP11 token is an example of an STDLL within openCryptoki. STDLLs are plug-in modules to the openCryptoki (main) API. They provide token-specific functions that implement the interfaces. Specific devices can be supported by building an appropriate STDLL. Figure 1 illustrates the stack and the process flow in an IBM Z® environment.

The STDLLs require local disk space to store persistent data, such as token information, personal identification numbers (PINs) and token objects. This information is stored in a separate directory for each token (per default in /var/lib/opencryptoki/ep11tok for the EP11 token). Within each of these directories there is a sub-directory TOK_OBJ that contains the token objects (token key store). Each private token object is represented by an encrypted file. Most of these directories are created during installation of openCryptoki.

The pkcsconf command line program

openCryptoki provides a command line program (/usr/lib/pkcs11/methods/pkcsconf) to configure and administer tokens that are supported within the system. The pkcsconf capabilities include token initialization, and security officer (SO) PIN and user PIN initialization and maintenance (see also Initializing EP11 tokens).

pkcsconf operations that address a specific token must specify the slot that contains the token with the -c option. You can view the list of tokens present within the system by specifying the -t option (without -c option). For example, the following code shows the options for the pkcsconf command and displays slot information for the system: 

# pkcsconf ?
usage: pkcsconf [-itsmlIupPh] [-c slotnumber -U user-PIN -S SO-PIN -n new PIN]

The available options have the following meanings:

-i
display PKCS11 info
-t
display token info
-s
display slot info
-m
display mechanism list
-l
display slot description
-I
initialize token
-u
initialize user PIN
-p
set the user PIN
-P
set the SO PIN
-h | --help | ?
show this help
-c
specify the token slot for the operation
-U
the current user PIN (for use when changing the user pin with -u and -p options); if not specified, user will be prompted
-S
the current Security Officer (SO) pin (for use when changing the SO pin with -P option); if not specified, user will be prompted
-n
the new pin (for use when changing either the user pin or the SO pin with -u, -p or -P options); if not specified, user will be prompted

For more information about the pkcsconf command, see the pkcsconf man page.