Install openCryptoki

Prerequisites

Before you start the setup, verify that the system meets all prerequisites and that the required tokens are present and accessible:

For this setup Red Hat Enterprise Linux (RHEL) 10 is used.
IBM Crypto Express 8S (CEX8S) – 4770 Cryptographic Coprocessor is used for CCA and EP11.
IBM Z and LinuxOne (s390x)

Note: Clear keys, such as Soft token or ICA token, are fully software-based and do not require an IBM Crypto Express card. Secure keys, such as CCA or EP11, require a Crypto Express card installed and configured on IBM Z Systems. For details about ordering options or supported systems, refer to the official IBM documentation.

Install openCryptoki

Install the openCryptoki package in RHEL.

The openCryptoki package is shipped as part of the RHEL distribution.

dnf install opencryptoki

Installed opencryptoki version.

Installed Packages
opencryptoki.s390x    3.24.0-4.el10          @rhel10.0-bistro_baseos

Start the pkcsslotd service to enable openCryptoki. pkcsslotd runs as a background daemon that manages slot and token state, coordinates concurrent access by PKCS#11 applications, and maintains shared memory for token data. Only one instance should run per host, and non‑root users must be members of the "pkcs11" group. The PKCS#11 interface requires pkcsslotd to be running.
```
systemctl enable pkcsslotd
systemctl start pkcsslotd
```

Note: For more information about the openCryptoki, go to Fastpath to openCryptoki and for openCryptoki configuration, go to Adjusting the openCryptoki configuration file.

Install the tokens

The Soft token and ICA token packages are available from the RHEL repository. For the CCA token and EP11 token, you need to purchase and install an IBM Crypto Express card in the machine. After installation, you can configure it as CCA or EP11. Before you use it, load and set the master key using (Trusted Key Entry) TKE for EP11 token, and TKE or panel.exe for CCA token. Then, download the matching host libraries. These libraries are available from the IBM Marketing Registration Service (MRS) and require an IBM ID.

Install Soft token

Install the opencryptoki-swtok-3.24.0-4.el10.s390x package. This package is included with the RHEL operating system.
```
dnf install opencryptoki-swtok-3.24.0-4.el10.s390x
```

Run pkcsconf -t to verify and view the token.

pkcsconf -t
Token #3 Info:
    Label: softtok
    Manufacturer: IBM
    Model: Soft
    Serial Number:
    Flags: 0x880245 (RNG|LOGIN_REQUIRED|CLOCK_ON_TOKEN|DUAL_CRYPTO_OPERATIONS|USER_PIN_TO_BE_CHANGED|SO_PIN_TO_BE_CHANGED)
    Sessions: 0/[effectively infinite]
    R/W Sessions: 0/[effectively infinite]
    PIN Length: 4-8
    Public Memory: [information unavailable]/[information unavailable]
    Private Memory: [information unavailable]/[information unavailable]
    Hardware Version: 0.0
    Firmware Version: 0.0
    Time: 2025102717062300
    URI: pkcs11:manufacturer=IBM;model=Soft;token=softtok

Install ICA token

Install the opencryptoki-icatok-3.24.0-4.el10.s390x package . This package is included in the RHEL operating system.
```
dnf install opencryptoki-icatok-3.24.0-4.el10.s390x
```

Run pkcsconf -t to verify and view the token.

pkcsconf -t
Token #1 Info:
    Label: icatoken
    Manufacturer: IBM
    Model: ICA
    Serial Number:
    Flags: 0x64D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|DUAL_CRYPTO_OPERATIONS|TOKEN_INITIALIZED)
    Sessions: 0/[effectively infinite]
    R/W Sessions: 0/[effectively infinite]
    PIN Length: 4-8
    Public Memory: [information unavailable]/[information unavailable]
    Private Memory: [information unavailable]/[information unavailable]
    Hardware Version: 0.0
    Firmware Version: 0.0
    Time: 2025102816240700
    URI: pkcs11:manufacturer=IBM;model=ICA;token=icatoken

Install CCA token

Before you start the installation, make sure at least one crypto card is configured with the CCA token in your machine and its online.

lszcrypt --ccaonly
CARD.DOM TYPE  MODE        STATUS     REQUESTS
----------------------------------------------
10       CEX8C CCA-Coproc  online          783
10.0019  CEX8C CCA-Coproc  online          783

Install the prerequisite package.

dnf install opencryptoki-ccatok-3.24.0-4.el10.s390x

Download the CCA host library based on your supported version of openCryptoki supported. The host library is located on the GitHub openCryptoki release page. For this setup, download the csulcca-8.2.54-01.s390x.rpm from the IBM MRS Tool.
Install the CCA package.
```
rpm -i csulcca-8.2.54-01.s390x.rpm
```
Note: To install the csulcca‑8.4.102‑01.s390x CCA package on RHEL 10, the system must have openCryptoki version 3.24.0‑6 or later installed. By default, RHEL 10 includes openCryptoki 3.24.0‑4, and RHEL packages must be updated to the latest available levels to meet this requirement.

Run pkcsconf -t to verify and view the token.

pkcsconf -t
Token #2 Info:
    Label: ccatoken
    Manufacturer: IBM
    Model: CCA
    Serial Number:
    Flags: 0x64D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|DUAL_CRYPTO_OPERATIONS|TOKEN_INITIALIZED)
    Sessions: 0/[effectively infinite]
    R/W Sessions: 0/[effectively infinite]
    PIN Length: 4-8
    Public Memory: [information unavailable]/[information unavailable]
    Private Memory: [information unavailable]/[information unavailable]
    Hardware Version: 0.0
    Firmware Version: 0.0
    Time: 2025102717223300
    URI: pkcs11:manufacturer=IBM;model=CCA;token=ccatoken

Note: If pkcsconf -t does not show the CCA token as available, verify that the CCA master keys are loaded. The CCA token remains unavailable until the master keys are loaded. System log entries (via journalctl or systemctl) contain error messages that help to identify what is missing.

Install EP11 token

Before you start the installation, make sure at least one crypto card is configured with EP11 in your machine and its online.

lszcrypt --ep11only
CARD.DOM TYPE  MODE        STATUS     REQUESTS
----------------------------------------------
11       CEX8P EP11-Coproc online          385
11.0019  CEX8P EP11-Coproc online          385

Download the EP11 host library based on your openCryptoki supported version. It is located on the GitHub openCryptoki release page. For this setup, download the EP11-SupportProg41-pkg from the IBM MRS Tool.
Unzip the file.
```
unzip EP11-SupportProg41-pkg.zip
```
Install the EP11 host library.
```
rpm -i ep11-host-4.0.0.6.s390x.rpm
```

Install the prerequisite package.

dnf install opencryptoki-ep11tok-3.24.0-4.el10.s390x

Run pkcsconf -t to verify and view the EP11 token.

pkcsconf -t
Token #4 Info:
    Label: ep11token
    Manufacturer: IBM
    Model: EP11
    Serial Number: 93AADKUN73550479
    Flags: 0x64D (RNG|LOGIN_REQUIRED|USER_PIN_INITIALIZED|CLOCK_ON_TOKEN|DUAL_CRYPTO_OPERATIONS|TOKEN_INITIALIZED)
    Sessions: 0/[effectively infinite]
    R/W Sessions: 0/[effectively infinite]
    PIN Length: 4-8
    Public Memory: [information unavailable]/[information unavailable]
    Private Memory: [information unavailable]/[information unavailable]
    Hardware Version: 8.38
    Firmware Version: 4.1
    Time: 2025102717482900
    URI: pkcs11:manufacturer=IBM;model=EP11;serial=93AADKUN73550479;token=ep11token

Note: If pkcsconf -t does not show the EP11 token as available, verify that the EP11 master keys are loaded. The EP11 token remains unavailable until the master keys are loaded. System log entries (via journalctl or systemctl) contain error messages that help to identify what is missing.

Initialize the token

After you have installed the correct token package, follow the step below to initialize the token.

You need to know the slot number first. The slot number is a numeric ID that identifies a specific cryptographic token (Soft, ICA, CCA, or EP11). Run pkcsconf -t to find the slot number.

SO PIN: SO PIN (Security Officer PIN) is an administrator password used to initialize and manage the token in IBM OpenCryptoki.

Note: The default SO PIN for all tokens is 87654321.

User PIN: The User PIN is a password that enables you to log in and perform cryptographic tasks such as generating keys, signing, and encrypting data.

Note: Define a User PIN that is different from 12345678, because this pattern is checked internally and marked as the default PIN. A log-in attempt with this User PIN is recognized as not initialized.

pkcsconf -I: Initialize the token and assign a label. Choose a meaningful name for the label, because you need it later for identification.
```
pkcsconf -I -c <slot number>. /* provide the slot number of the token */
```
Note: Use pkcsconf -t or pkcsconf -s to identify the slot number.
pkcsconf -p: Change the default SO PIN (87654321) for the slot (recommended).
```
pkcsconf -P -c <slot number>
```
pkcsconf -u: Initialize the User PIN. The length of User PIN is 4 to 8 characters. The SO PIN is required to initialize the User PIN.
```
pkcsconf -u -c <slot number>
```
pkcsconf -p: Change the existing User PIN (optional).
```
pkcsconf -p -c <slot number>
```