Defining a CCA token configuration file

Edit online

You can define an optional configuration file for a CCA token.

Other than for the EP11 token, there is no default CCA token configuration file name, and also no environment variable to specify the directory containing the configuration file. Instead, you can specify the CCA token configuration file name (and optionally its absolute path) in the global openCryptoki configuration file called opencryptoki.conf using the keyword confname. If no path is specified, then a specified CCA token configuration file must exist within the openCryptoki directory /etc/opencryptoki/.

Example for a CCA token configuration file specification in opencryptoki.conf:


...
slot 2
{
   stdll = libpkcs11_cca.so
   confname = /etc/opencryptoki/ccatok1.conf
}
...

You can specify the following options in the CCA token configuration file:

EXPECTED_MKVPS
This option defines the expected master key verification patterns for the three CCA master key types: SYM, AES, and APKA. Master key type ASYM is not used by the CCA token. At token initialization, the CCA token checks whether the expected MKVP value is consitent on all assigned APQNs. The set of APQNs is determined by the CCA host library, based on the specifications of the CCA environment variables CSU_DEFAULT_ADAPTER and CSU_DEFAULT_DOMAIN.

Syntax:


EXPECTED_MKVPS
{ 
   SYM = "<8-bytes-hex-string>" 
   AES = "<8-bytes-hex-string>" 
   APKA = "<8-bytes-hex-string>" 
}

For function calls to the key generation functions C_GenerateKey(), C_GenerateKeyPair(), C_UnwrapKey(), C_DeriveKey(), or C_CreateObject(), the CCA token also performs a master key verification check to verify if the master key is generated with the correct and expected master key verification pattern (MKVP). That means, that for an existing EXPECTED_MKVPS specification, the MKVP of the generated key must match the specified value, or, if no EXPECTED_MKVPS value is specified, it must be the MKVP encountered at token initialization time.

In case of a mismatch, token initialization or key generation fails and a syslog message is issued and a flag is set in the token to reject all subsequent cryptographic operations with CKR_DEVICE_ERROR.

PKEY_MODE
Prerequisite for exploiting the PKEY_MODE option is the Linux® kernel 5.10 or later. You can specify this option to define that for CCA secure keys of type AES, AES XTC, or EC, an additional pertaining protected key shall be created, and this protected key shall be used by CPACF whenever possible because of performance reasons (see How and why to exploit protected keys).
  • Supported AES key lengths are 128, 192, and 256 bits.
  • EC key support is limited to the curves supported both by CPACF with MSA9 and by the CCA token. Therefore only the following three curves are supported:
    • prime256 with OID 1.2.840.10045.3.1.7
    • secp384 with OID 1.3.132.0.34
    • secp521 with OID 1.3.132.0.35
  • The following mechanisms are supported for protected keys:
    • CKM_AES_ECB
    • CKM_AES_CBC
    • CKM_AES_CBC_PAD
    • CKM_AES_XTS
    • CKM_ECDSA
    • CKM_ECDSA_SHA1
    • CKM_ECDSA_SHA224
    • CKM_ECDSA_SHA256
    • CKM_ECDSA_SHA384
    • CKM_ECDSA_SHA512
  • The creation of protected keys requires that the native CCA key object (blob) has been created with the CCA keyword XPRTCPAC which is equivalent with the boolean attribute CKA_IBM_PROTKEY_ EXTRACTABLE = TRUE. This keyword has been introduced with CCA 7.0 and CEX7C. Therefore, using the protected key support is possible on IBM z15® or later processors with a CEX7C coprocessor in CCA mode.
  • In CCA a key can be both CKA_EXTRACTABLE and CKA_IBM_ PROTKEY_EXTRACTABLE. Therefore, all new keys may get attribute CKA_IBM_PROTKEY_EXTRACTABLE = TRUE if the application did not explicitly specify CKA_IBM_PROTKEY_EXTRACTABLE = FALSE. If you also work with EP11 tokens, you might notice that this is in contrast to EP11.
  • CCA protected keys are added to key objects via the IBM®-specific key attribute CKA_IBM_OPAQUE_PKEY at first use of the key.
  • Protected keys are created only from symmetric and private keys, not from public keys.
  • For information how to use protected keys for AES XTS support, read How to enable AES XTS support for CCA and EP11 tokens.

Set the PKEY_MODE option to one of the following modes:

DISABLED
Protected key support is disabled. All keys are used as secure keys. This mode allows to completely disable protected key support, for example, for performance comparisons.
DEFAULT
This option specifies to apply the default and works like follows:

If the application did not specify attribute CKA_IBM_PROTKEY_EXTRACTABLE = TRUE in its template for key generation, new keys of any type get CKA_IBM_PROTKEY_EXTRACTABLE= FALSE and CKA_EXTRACTABLE = TRUE and no protected key is created.

Existing secure keys with a valid protected key and CKA_IBM_PROTKEY_EXTRACTABLE = TRUE are used via this protected key, and any invalid protected key is re-created if required with the help of the current firmware master key.

ENABLED
Enable protected key support for all keys. If the application did not specify CKA_IBM_ PROTKEY_EXTRACTABLE = FALSE in its template, new keys of any type get CKA_IBM_PROTKEY_EXTRACTABLE = TRUE and a protected key is automatically created at first use of the key.
Figure 1. Sample of a CCA token configuration file

version cca-0
#
# CCA token configuration
#
EXPECTED_MKVPS
{
   SYM = "130E2053F18E5F4C"
   AES = "7D10D17BC8A409C4"
   APKA = "82A5E2CD5030D5EC"
}

PKEY_MODE = ENABLED