Scroll to navigation

PKCSCCA(1) openCryptoki PKCSCCA(1)

NAME

pkcscca - configuration utility for the CCA token

SYNOPSIS

VERSION MIGRATION

pkcscca -m v2objectsv3 [-d directory] [-v LEVEL]

KEY MIGRATION

pkcscca -m keys -s SLOTID -k aes|apka|asym|sym [-d directory] [-v LEVEL]

OLD RSA KEY MIGRATION

pkcscca -m oldrsakeys -s SLOTID [-d directory] [-v LEVEL]

HELP

pkcscca -h

DESCRIPTION

The pkcscca utility assists in administering the CCA token.

In version 2 of opencryptoki, CCA private token objects were encrypted in CCA hardware. In version 3 these objects are encrypted in software. The v2objectsv3 migration option migrates these v2 objects by decrypting them in CCA hardware using a secure key and then re-encrypting them in software using a software key. Afterwards, v2 objects can be accessed in version 3.

There may be situations where CCA master keys must be changed. All CCA secret and private keys are wrapped with a master key. After a CCA master key is changed, keys wrapped with the old master key need to be re-wrapped with the current master key. The keys migration option migrates these wrapped keys by unwrapping them with the old master key and wrapping them with the current master key.

Up to opencryptoki version 3.14.0, RSA keys were created using the RSA-CRT key token format (private key section X'08'). RSA-CRT keys are encrypted with the CCA ASYM master key, and cannot be used for certain mechanisms, e.g. RSA-PSS or RSA-OAEP. In newer opencryptoki versions, RSA keys are created using the RSA-AESC key token format (private key section X'31'). Up to version 3.16.0, RSA public keys also contained full CCA secure key tokens, including the private key section (which is encrypted by the CCA master key). The oldrsakeys migration option migrates old RSA private key tokens to the new format, and also extracts the public key sections from RSA public key tokens containing a full CCA secure key token.

GENERAL OPTIONS

Print a help message and exit.
The directory where the CCA token information is kept. This directory will be used to locate the private token objects to be migrated, e.g. /var/lib/opencryptoki/ccatok. If not specified, the compiled-in default /var/lib/opencryptoki/ccatok is used.
Set the verbosity level. LEVEL must be one of:
No extra output (default).
Report errors only.
Report warnings and errors.
Report informational messages, warnings, and errors.
Report developer-level messages and all of the above.
Report all debug messages (most verbose).

VERSION MIGRATION

Migrates CCA private token objects from CCA encryption (used in v2) to software encryption (used in v3).

KEY MIGRATION

Unwraps private keys with an old CCA master key and wraps them with a new CCA master key.
Migrate keys wrapped with the selected CCA master key type. The argument selects which master key domain to target:
AES-DATA keys, AES-CIPHER keys (including AES-XTS), and HMAC keys (all wrapped with the CCA AES master key).
New-format RSA keys (RSA-AESC / RSA-AESM), ECC keys, IBM Dilithium keys, IBM ML-DSA keys, IBM ML-KEM keys, and ML-DSA keys (all wrapped with the CCA APKA master key).
Old-format RSA keys (RSA-CRT, private key section X'08') (wrapped with the CCA ASYM master key).
DES, 2DES, and 3DES keys (wrapped with the CCA SYM master key).
The PKCS#11 slot number. Required.

OLD RSA KEY MIGRATION

Converts old RSA keys (RSA-CRT) to the new format (RSA-AESC) and extracts the public key section only from key objects containing the full RSA key token.
The PKCS#11 slot number. Required.

FILES

/var/lib/opencryptoki/ccatok/TOK_OBJ/OBJ.IDX
Contains the current list of public and private token objects for the CCA token.
/var/lib/opencryptoki/ccatok/MK_SO
Contains the Security Officer (SO) master key, encrypted with the SO PIN. Used by the v2objectsv3 migration to verify the SO PIN and retrieve the master key for re-encryption.
/var/lib/opencryptoki/ccatok/MK_USER
Contains the user master key, encrypted with the user PIN. Used by the v2objectsv3 migration to verify the user PIN.

SEE ALSO

August 2026 3.28.0