Scroll to navigation

PKCSICSF(1) openCryptoki PKCSICSF(1)

NAME

pkcsicsf - configuration utility for the ICSF token

SYNOPSIS

pkcsicsf [-h] [-l] [-a token-name] -m mechanism [-u URI] [-b BINDDN] [-c client-cert-file] [-C CA-cert-file] [-k privatekey] [-s slot] [-R RACF-passwd] [-S SO-pin]
pkcsicsf -p token-name [-R RACF-passwd] [-S SO-pin]

DESCRIPTION

The pkcsicsf utility lists available ICSF tokens, adds a specific ICSF token to opencryptoki, and updates the locally stored RACF password for an existing token.

The ICSF token must be added first to opencryptoki. This creates an entry in the opencryptoki.conf file for the ICSF token. It also creates a token_name.conf configuration file in the same directory as the opencryptoki.conf file, containing ICSF specific information. This information is read by the ICSF token.

The ICSF token must bind and authenticate to an LDAP server. The supported authentication mechanisms are simple and sasl. One of these mechanisms must be entered when listing the available ICSF tokens or when adding an ICSF token.

The system admin can either allow the ldap calls to utilize existing ldap configs, such as ldap.conf or .ldaprc for bind and authentication information or set the bind and authentication information within opencryptoki by using this utility and its options. The information will then be placed in the token_name.conf file to be used in the ldap calls. When using simple authentication, the user will be prompted for the racf password when listing or adding a token.

The pkcsicsf utility must be run as root when adding an ICSF token to opencryptoki.

TOKEN INITIALIZATION

The ICSF token does not require C_InitToken (i.e. pkcsconf(1) -I) to initialize it. The cryptographic objects and key material reside on the remote z/OS ICSF server, which is already fully provisioned before pkcsicsf is invoked.

In all cases tokversion = 3.28 is recorded in opencryptoki.conf, enabling the FIPS-compliant data store format (see TOKEN DATA FORMAT below). The local credential store created by pkcsicsf -a differs between the two authentication mechanisms.

Simple authentication

pkcsicsf -a prompts for the SO PIN and writes the full local credential store:

  • The token directory under /var/lib/opencryptoki/.
  • The ICSF-specific configuration file /etc/opencryptoki/token_name.conf.
  • NVTOK.DAT with CKF_TOKEN_INITIALIZED and CKF_USER_PIN_TO_BE_CHANGED set, and the SO PIN already recorded.
  • MK_SO — the token master key wrapped under the SO PIN.
  • RACF — the RACF password encrypted with AES-256-GCM.

The correct post-installation sequence for simple authentication is:

1.
Add the token (run as root); you will be prompted for the SO PIN:

pkcsicsf -a token-name -m simple -u ldap://host
2.
Restart the slot daemon so the new token is visible:

systemctl restart pkcsslotd
3.
Initialize the user PIN (run as SO, using the SO PIN from step 1):

pkcsconf -u -c slot

After step 3 the token is fully operational.

SASL authentication

pkcsicsf -a does not prompt for a PIN. It writes only:

  • The token directory under /var/lib/opencryptoki/.
  • The ICSF-specific configuration file /etc/opencryptoki/token_name.conf.

No NVTOK.DAT, MK_SO, or RACF file is written. SASL authentication uses client certificates; there is no RACF password to protect. Because no master key or RACF password is required for LDAP binding, the token supports public sessions (sessions opened without prior User or SO login) for accessing and operating on public objects. When the slot daemon first accesses the token it creates NVTOK.DAT and sets CKF_TOKEN_INITIALIZED, CKF_SO_PIN_TO_BE_CHANGED, and CKF_USER_PIN_TO_BE_CHANGED. The SO PIN defaults to 87654321. Both PINs must therefore be set in separate steps after the daemon is restarted.

The correct post-installation sequence for SASL authentication is:

1.
Add the token (run as root):

pkcsicsf -a token-name -m sasl -u ldaps://host -c client.crt -k client.key -C server.crt
2.
Restart the slot daemon so the new token is visible:

systemctl restart pkcsslotd
3.
Change the SO PIN away from the default 87654321 (CKF_SO_PIN_TO_BE_CHANGED is set):

pkcsconf -P -c slot
4.
Initialize the user PIN (run as SO, using the SO PIN set in step 3):

pkcsconf -u -c slot

After step 4 the token is fully operational and CKF_TOKEN_INITIALIZED will be reported by pkcsconf(1) -t.

RACF PASSWORD CHANGE

When the RACF password for a bind DN is changed on the z/OS ICSF server, the locally stored encrypted copy must be updated using pkcsicsf -p. No token removal or re-initialization is required; the cryptographic objects on the z/OS server are not affected.

Procedure:

1.
Change the RACF password on the z/OS server (outside of openCryptoki).
2.
Run pkcsicsf -p immediately afterwards:

pkcsicsf -p token-name

The authentication mechanism, URI, and bind DN are read automatically from the existing token configuration. You will be prompted for the new RACF password and then for the SO PIN. The new RACF password is first verified against the LDAP server. If that succeeds, the master key is unwrapped using the SO PIN and the RACF file is re-encrypted with the new password.

No restart of pkcsslotd or of any application using the token is required. Both the v3 token format (tokversion = 3.28) and the legacy format are supported.

Operational timing requirement — minimise the update window

There is an unavoidable service window between step 1 and step 2. During this window, any new LDAP connection that the token needs to establish — for a new C_Login or C_OpenSession call — will attempt to bind with the old, now-invalid RACF password and will fail. The caller will receive CKR_FUNCTION_FAILED or CKR_USER_NOT_LOGGED_IN until pkcsicsf -p has been run.

Already-established LDAP connections are not affected: a session that completed C_Login before the password was changed on the z/OS server retains a live, authenticated LDAP connection and continues to operate normally throughout the window.

To keep the window as short as possible, run pkcsicsf -p immediately after the RACF password is changed on z/OS. Repeated failed bind attempts during the window may trigger the RACF account lockout policy on the z/OS server; consult your z/OS security administrator for the applicable lockout threshold.

TOKEN DATA FORMAT

Tokens added by pkcsicsf always use the FIPS-compliant data store format introduced in openCryptoki 3.28. This is indicated by tokversion = 3.28 in the slot entry in opencryptoki.conf.

The format uses the following security properties:

  • NVTOK.DAT — PIN verification and master-key wrapping use PBKDF2-SHA-512 with 100,000 iterations and a 64-byte random salt. The derived login key is stored for PIN verification; a separately derived wrap key protects the master key.
  • MK_SO / MK_USER — the 256-bit AES token master key is wrapped using AES-256 Key Wrap (RFC 3394) under the PBKDF2-derived wrap key. The file contains exactly 40 bytes (the RFC 3394 output) with no additional header.
  • RACF — the RACF password is encrypted using AES-256-GCM. The token name is used as Additional Authenticated Data (AAD), binding the ciphertext to the specific token and detecting any tampering or accidental file substitution. The file contains a big-endian version field, a 12-byte random nonce, a 16-byte GCM authentication tag, a big-endian ciphertext length, and the ciphertext.

Existing ICSF tokens that do not have tokversion = 3.28 in their slot entry continue to use the previous data format and are not affected.

MIGRATION TO THE NEW DATA FORMAT

There is no automated migration tool. To migrate an existing ICSF token to the FIPS-compliant data format, remove the token and add it again using pkcsicsf:

1.
Remove the existing slot entry from opencryptoki.conf and delete the token's local data directory:

rm -rf /var/lib/opencryptoki/token_name
2.
Re-add the token (run as root):

pkcsicsf -a token-name -m mechanism [options]
3.
Restart the slot daemon:

systemctl restart pkcsslotd
4.
Re-initialize the user PIN (run as SO):

pkcsconf -u -c slot

The cryptographic objects and key material reside on the remote z/OS ICSF server and are not stored locally. They are therefore not affected by the migration and remain fully available after the token is re-added.

OPTIONS

Add the specified ICSF token to opencryptoki. See TOKEN INITIALIZATION above for the steps that follow. To add all available ICSF token, specify all.
The distinguished name to bind when using simple authentication.
The client certificate file for SASL authentication. If not specified, the value from ldap.conf(5) or ~/.ldaprc is used. Relative paths are resolved to absolute paths before being written to the token configuration file.
The CA certificate file for SASL authentication. If not specified, the value from ldap.conf(5) or ~/.ldaprc is used. Relative paths are resolved to absolute paths before being written to the token configuration file.
Show usage information.
The client private key file for SASL authentication. If not specified, the value from ldap.conf(5) or ~/.ldaprc is used. Relative paths are resolved to absolute paths before being written to the token configuration file.
List available ICSF tokens.
The authentication mechanism to use when binding to the LDAP server (either simple or sasl). This option is required whenever -l or -a is used. Must not be specified with -p.
Update the locally stored RACF password for the named token after the RACF password has been changed on the z/OS ICSF server. The authentication mechanism, URI, and bind DN are read automatically from the existing token configuration; -m, -u, and -b must not be specified. Only tokens using simple authentication have a locally stored RACF password; the command will refuse with an error if the token uses SASL. The new RACF password is prompted for and verified by binding to the LDAP server before anything is written locally. The SO PIN is then prompted for to unwrap the token master key, which is used to re-encrypt the RACF password in place. The caller must be a member of the pkcs11 group. See RACF PASSWORD CHANGE below for the full procedure.
The RACF password to use for simple authentication. If not specified, the password is prompted for interactively. This option may be used with -l, -a, and -p when the authentication mechanism is simple. Security note: Passing a password on the command line may expose it to other local users via process listings (e.g. ps(1) or /proc/<pid>/cmdline). Prefer interactive prompting in security-sensitive environments.
The SO PIN for the token. If not specified, the PIN is prompted for interactively. This option may be used with -a (simple authentication) and -p. Security note: Passing a PIN on the command line may expose it to other local users via process listings (e.g. ps(1) or /proc/<pid>/cmdline). Prefer interactive prompting in security-sensitive environments.
The slot number to assign to the token when adding it with -a. The tool verifies that the requested slot number is not already in use and returns an error if it is occupied. If -s is not specified, the next available slot number is used automatically. This option may only be used together with -a.
The URI of the LDAP server (e.g. ldap://hostname or ldaps://hostname).

FILES

/etc/opencryptoki/opencryptoki.conf
The opencryptoki config file containing token configuration information. A slot entry for the ICSF token is added here by pkcsicsf -a, including tokversion = 3.28 to enable the FIPS-compliant data store format.
/etc/opencryptoki/token_name.conf
Contains ICSF configuration information for the ICSF token.
/var/lib/opencryptoki/token_name/NVTOK.DAT
Local token data file. Stores PBKDF2-SHA-512 PIN verification keys, wrap-key parameters, and token flags including CKF_TOKEN_INITIALIZED. Written by pkcsicsf -a and updated by pkcsconf.
/var/lib/opencryptoki/token_name/MK_SO
Contains the token master key wrapped under the SO PBKDF2-derived wrap key using AES-256 Key Wrap (RFC 3394). Written by pkcsicsf -a and updated when the SO PIN is changed.
/var/lib/opencryptoki/token_name/MK_USER
Contains the token master key wrapped under the user PBKDF2-derived wrap key using AES-256 Key Wrap (RFC 3394). Written when the user PIN is initialized or changed.
/var/lib/opencryptoki/token_name/RACF
Contains the RACF password encrypted with AES-256-GCM under the token master key. Written by pkcsicsf -a and updated by pkcsicsf -p.

SEE ALSO

opencryptoki(7),
pkcsslotd(8),
pkcsconf(1).
September 2026 3.28.0