Defining an EP11 token configuration file

Options for the EP11 token configuration file

The following is a list of available options for an EP11 token configuration file. A sample of such a file is shown in Figure 3.

‣ APQN_ALLOWLIST

Because different EP11 hardware security modules (HSM) can use different wrapping keys (referred to as master keys in the TKE environment), users need to specify which HSM, in practice an adapter/domain pair, can be used by the EP11 token as a target for cryptographic requests. Therefore, an EP11 token configuration file contains a list of adapter/domain pairs to be used.

You start this list of adapter/domain pairs starting with a line containing the keyword APQN_ALLOWLIST. Next follows the list which can specify up to 512 adapter/domain pairs, denoted by decimal numbers in the range 0 - 255. Each pair designates an adapter (first number) and a domain (second number) accessible to the EP11 token. Close the list using the keyword END.

Alternatively, you can use the keyword APQN_ANY to define that all adapter/domain pairs with EP11 firmware, that are available to the system, can be used as target adapters. This is the default.

Notes:

• The term APQN stands for adjunct processor queue number. It designates the combination of a cryptographic coprocessor (adapter) and a domain, a so-called adapter/domain pair. At least one adapter/domain pair must be specified.
• If more than one APQN is used by a token, then these APQNs must be configured with the same master key.
• This attribute used to be APQN_WHITELIST but has been renamed due to the inclusive terminology initiative. For compatibility reasons, you can still use the old name, but this is considered to be deprecated.

An adapter/domain pair is displayed by the lszcrypt tool or in the sys file system (for example, in /sys/bus/ap/devices) in the form card .domain, where both numbers are displayed in hexadecimal format.

There are two ways to specify the cryptographic adapter:

• either as an explicit list of adapter/domain pairs:

  
  APQN_ALLOWLIST
    8 13
   10 13
  END

  The adapter and domain can be given in decimal, octal (with leading 0), or hexadecimal (with leading 0x) notation:

  
  APQN_ALLOWLIST
    8 0x0d
    0x0a 13
  END

  Valid adapter and domain values are in the range 0 to 255.

• or as any available cryptographic adapters:

  APQN_ANY

In the example from Figure 3, adapter 0 with domains 0 and 1, and adapter 2 with domain 84 are specified as target for requests from the EP11 token. In Figure 1, these adapter/domain pairs are shown in hexadecimal notation as APQNs (00,0000), (00,0001), and (02,0054).

‣ CPFILTER

The list of mechanisms returned by C_GetMechanismList is filtered using the domain or access control point (ACP) settings of the used cryptographic coprocessors. The EP11 access control point filter configuration file (ACP-filter configuration file) is used to associate certain access (domain) control points with mechanisms that are dependent on these access control points. The default ACP-filter configuration file is ep11cpfilter.conf located in the same directory as this EP11 token configuration file. You can optionally specify the name or location, or both, of the ACP-filter file:

CPFILTER /etc/opencryptoki/ep11cpfilter.conf

# EP11 token CP-filter configuration
#
# The list of mechanisms returned by C_GetMechanismList is filtered
# using the control point settings of the used crypto adapters.
# The EP11 CP-filter config file is used to associate certain control
# points with mechanisms that are dependent on these control points.
# 
# Syntax:
#       cp: mech1, mech2, ...
#
# Both, cp as well as mech is specified as name or in decimal, octal
# (with leading 0) or hexadecimal (with leading 0x):
#
#       XCP_CPB_SIGN_SYMM: CKM_SHA256_HMAC, CKM_SHA256_HMAC_GENERAL
#       4: 0x00000251, 0x00000252

# sign with HMAC or CMAC
XCP_CPB_SIGN_SYMM: CKM_SHA256_HMAC, CKM_SHA256_HMAC_GENERAL, CKM_SHA224_HMAC,   
...
# verify with HMAC or CMAC
XCP_CPB_SIGVERIFY_SYMM: CKM_SHA256_HMAC, CKM_SHA256_HMAC_GENERAL, CKM_SHA224_HMAC,   
...
# sign with private keys
XCP_CPB_SIGN_ASYMM: CKM_RSA_PKCS, CKM_RSA_PKCS_PSS, CKM_SHA1_RSA_X9_31, CKM_SHA1_RSA_PKCS,  
...
# encrypt with symmetric keys
XCP_CPB_ENCRYPT_SYMM: CKM_AES_ECB, CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_ECB, 
...
# decrypt with symmetric keys
XCP_CPB_DECRYPT_SYMM: CKM_AES_ECB, CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_ECB, CKM_DES3_CBC,
...
# key export with symmetric keys
XCP_CPB_WRAP_SYMM: CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_CBC, CKM_DES3_CBC_PAD, 
...
# key import with symmetric keys
XCP_CPB_UNWRAP_SYMM: CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_DES3_CBC, CKM_DES3_CBC_PAD
# generate asymmetric keypairs
XCP_CPB_KEYGEN_ASYMM: CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_RSA_X9_31_KEY_PAIR_GEN, 
...
# generate or derive symmetric keys
XCP_CPB_KEYGEN_SYMM: CKM_AES_KEY_GEN, CKM_DES2_KEY_GEN, CKM_DES3_KEY_GEN,
... 
# RSA private-key or key-encrypt use
XCP_CPB_ALG_RSA: CKM_RSA_PKCS, CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_RSA_X9_31_KEY_PAIR_GEN,  
...
# DSA private-key use
XCP_CPB_ALG_DSA: CKM_DSA_KEY_PAIR_GEN, CKM_DSA, CKM_DSA_SHA1
# EC private-key use
XCP_CPB_ALG_EC: CKM_EC_KEY_PAIR_GEN, CKM_ECDH1_DERIVE, CKM_ECDSA, CKM_ECDSA_SHA224, 
...
# Diffie-Hellman use (private keys)
XCP_CPB_ALG_DH: CKM_ECDH1_DERIVE, CKM_DH_PKCS_KEY_PAIR_GEN, CKM_DH_PKCS_DERIVE
# allow key derivation (symmetric+EC/DH)
XCP_CPB_DERIVE: CKM_SHA1_KEY_DERIVATION, CKM_SHA256_KEY_DERIVATION, 
...
# enable support of curve25519, c448 and related algorithms incl. EdDSA (ed25519 and ed448)
XCP_CPB_ALG_EC_25519: CKM_IBM_EC_X25519, CKM_IBM_ED25519_SHA512, CKM_IBM_EC_X448, 
...
#enable support of Dilithium
XCP_CPB_ALG_PQC: CKM_IBM_DILITHIUM, CKM_IBM_KYBER
...

‣ DIGEST_LIBICA <libica-path> | DEFAULT | OFF

To improve the performance of required hash functions, the EP11 token on initialization loads the default libica library. If required, the EP11 token invokes the libica SHA-based hash functions, because the libica library performs these hash functions on the CPACF, thus avoiding hash processing on a cryptographic coprocessor which results in I/O operations to the adapter.

libica provides an OpenSSL based software fall-back, in case CPACF or a certain hashing function of CPACF is not available. In case a libica operation fails, because neither the hardware nor the software support is available, or if libica is not available at all, then the request is passed to the EP11 library instead.

With the DIGEST_LIBICA option, you can control which libica library is loaded:

DEFAULT

The default libica library is loaded. If libica could not be found, a message is issued to syslog, and all hash based functions use the EP11 host library.

The same behavior is applied if the DIGEST_LIBICA option is not specified at all.

<libica-path>

The specified library is loaded. If it can not be found, a message is issued to syslog, and token initialization fails.

OFF

No libica is loaded, and all hash based functions use the EP11 host library.

If DIGEST_LIBICA is not specified, then the default libica library is loaded (same behavior as for DIGEST_LIBICA DEFAULT).

‣ EXPECTED_WKVP

Use this option to ensure that all APQNs assigned to an EP11 token - dependent on the APQN configuration (APQN_ANY or APQN_ALLOWLIST) - are configured with the same wrapping key. You specify the expected wrapping key verification pattern (WKVP) as hex string. With this option, the assigned APQNs are checked to all match the specified expected WKVP during token initialization, or if no EXPECTED_WKVP is specified, all WKVPs must match on all assigned APQNs anyway.

For functions calls to the key generation functions C_GenerateKey(), C_GenerateKeyPair(), C_UnwrapKey(), C_DeriveKey(), or C_CreateObject(), the EP11 token also performs a wrapping key verification pattern check to verify if the wrapping key is generated with the correct and expected wrapping key verification pattern (WKVP). That means, that for an existing EXPECTED_WKVP specification, the WKVP of the generated key must match the specified value, or, if no EXPECTED_WKVP value is specified, it must be the WKVP 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.

The EP11 verification pattern is 16 bytes in length, although sometimes 32 bytes are reported. Nevertheless, only the first 16 bytes are compared.

‣ FIPS_SESSION_MODE

Specify this option to enable the FIPS session mode. For the purpose and description of this mode and the prerequisites, see Controlling access to cryptographic objects with session modes. This option can not be combined with the STRICT_MODE option to enable the strict session mode, nor with the VHSM_MODE option to enable the virtual HSM (VHSM) mode. That is, only FIPS_SESSION_MODE or any combination of STRICT_MODE and VHSM_MODE can be specified.

In a standard PKCS #11 environment, from a public session (without login) you can access public session objects and public token objects. In FIPS session mode, a User log-in (that is, a PKCS #11 User session) is always required to access any kind of key objects, regardless of the setting of the CKA_PRIVATE and CKA_TOKEN attributes.

That is, a C_Login() function must be performed with the User PIN to be able to create or use key objects. This is an enforcement compared to the PKCS #11 standard, where public objects (CKA_PRIVATE=FALSE) can be used and created in public or security officer (SO) sessions.

Furthermore, all keys generated by the EP11 token strictly belong to the EP11 token that created it, and the keys can only be used while the respective session is logged-in to the EP11 APQNs configured for the token.

Notes:

• Check the prerequisites for using this option in Prerequisites for using the FIPS session mode. Especially, ensure that the required access control points 48 XCP_CPB_ALLOW_NONSESSION and 73 XCP_CPB_ALLOW_LOGIN_PRE_F2021 are OFF.
• Applying the FIPS session mode to an EP11 token does not mean that the token is operating in FIPS mode, but it means that it only uses FIPS-compliant sessions. Operating entirely in FIPS mode would require additional restrictions, for example, on algorithms or key sizes. If the APQNs configured for the EP11 token operate in FIPS mode, the APQNs may enforce these restrictions though.

‣ FORCE_SENSITIVE

Specify this option to force that the default for CKA_SENSITIVE is CK_TRUE for secret keys. For more information, see Usage notes for the EP11 host library functions.

‣ OPTIMIZE_SINGLE_PART_OPERATIONS

Set this option to optimize the performance of single part sign- and verify-operations, as well as of single part encrypt- or decrypt-operations. Then the init call is not passed through the EP11 host library as long as there is no corresponding multi-part operation.

When this option is enabled, error handling can be slightly different, when errors from the deferred init call are presented during the first update call or during the calls to C_Sign, C_Verify, C_Encrypt, or C_Decrypt for a single part operation. That is, the first update call on a multi part operation or the mentioned calls for a single part operation may return errors, which are usually not returned by the update call. Such errors may be for example:

• CKR_OBJECT_HANDLE_INVALID
• CKR_ATTRIBUTE_VALUE_INVALID
• CKR_KEY_HANDLE_INVALID
• CKR_KEY_SIZE_RANGE
• CKR_KEY_TYPE_INCONSISTENT
• CKR_MECHANISM_INVALID
• CKR_MECHANISM_PARAM_INVALID

‣ PKEY_MODE

Use this option to define that for EP11 secure keys of type AES or EC, an additional pertaining protected key shall be created, and this protected key shall be used whenever possible. This optimizes the performance, because protected keys work on the CPACF feature, and calls to CPACF are faster than calls to an EP11 cryptographic coprocessor.

Secure keys for which you want a pertaining protected key being produced and used, must have the CKA_IBM_PROTKEY_EXTRACTABLE = TRUE attribute specified in their template when being created. Secure keys with this attribute set to FALSE are not eligible for protected key support. See also How and why to exploit protected keys.

Keys created before introducing the protected key option are not usable for protected key support, because they do not have the CKA_IBM_PROTKEY_EXTRACTABLE = TRUE attribute. Only keys created after activating the protected key option with the ENABLE4NONEXTR mode are eligible for getting a protected key, depending on their key type (only AES and EC) and attributes. See also IBM-specific attributes.

Keys created before introducing the protected key option do not have a CKA_IBM_PROTKEY_EXTRACTABLE attribute and are considered to be not usable for protected key support.

Notes:

• Protected keys are created only from symmetric and private keys, not from public keys. They are created by a transparent IBM-specific mechanism. This mechanism in turn reads certain attributes of the processed key object to determine the generation of the protected key. The new protected key is bound to the original secure key object by the attribute CKA_IBM_OPAQUE_PKEY (see also IBM-specific attributes.
• The PKEY_MODE option is only supported on IBM z15® processors or later, with EP11 cryptographic coprocessors starting with CEX7P. It requires the EP11 host library 3.0 or later.
• The EP11 host library 3.0 or later does not allow attribute-bound keys to be transformed into protected keys.

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 or CKA_EXTRACTABLE = FALSE 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.

ENABLE4NONEXTR

Enable protected key support for non-extractable keys. If the application did not specify CKA_IBM_PROTKEY_EXTRACTABLE = FALSE in its template for key generation, new keys of any type with CKA_EXTRACTABLE = FALSE (non-extractable keys) get CKA_IBM_PROTKEY_EXTRACTABLE = TRUE and a protected key is automatically created at first use of the key.

ENABLE4EXTR

Enable protected key support for extractable keys. If the application did not specify CKA_IBM_PROTKEY_EXTRACTABLE in its template, new keys of any type with CKA_EXTRACTABLE=TRUE get CKA_IBM_PROTKEY_EXTRACTABLE=TRUE and a protected key is automatically created at first use of the key.

ENABLE4ALL

Enable protected key support for all keys. If the application did not specify CKA_IBM_PROTKEY_EXTRACTABLE in its template, new keys of any type, regardless of the CKA_EXTRACTABLE attribute, get CKA_IBM_PROTKEY_EXTRACTABLE=TRUE and a protected key is automatically created at first use of the key.

A prerequisite for using the options ENABLE4EXTR or ENABLE4ALL is to set the following access control point (ACP):

75 XCP_CPB_ALLOW_COMBINED_EXTRACT    allow creation and usage of keys with both EXTRACTABLE 
                                     and PROTKEY_EXTRACTABLE attributes set

If any of the two options is active, but not all configured APQNs have ACP 75 set to ON, the token fails to start.

With the new parameter values, it may happen that a key is created in an environment supporting keys being both EXTRACTABLE and PROTKEY_EXTRACTABLE, but used in an environment where this is not supported. This kind of key usage is restricted by the crypto adapter firmware, that is, it is not possible to use a key with both attributes set to TRUE in older environments. Therefore, in case the control point setting of the adapters do not allow that attributes CKA_EXTRACTABLE and CKA_IBM_PROTKEY_EXTRACTABLE are both true, then openCryptoki rejects this with CKR_TEMPLATE_INCONSISTENT.

‣ STRICT_MODE

In strict-mode, all session-keys strictly belong to the PKCS #11 session that created it. When the PKCS #11 session ends, all session keys created for this session can no longer be used. This option can not be combined with FIPS_SESSION_MODE, but can be combined with VHSM_MODE.

For more information, read topic Controlling access to cryptographic objects in Exploiting Enterprise PKCS #11 using openCryptoki.

‣ USE_PRANDOM

Set this option to control from where the EP11 token reads random data. With USE_PRANDOM specified, the EP11 token reads random data from /dev/prandom, or from /dev/urandom if /dev/prandom is not available. The default is to read the random data using the m_GenerateRandom function from the Crypto Express EP11 coprocessor.

‣ VHSM_MODE

In VHSM mode (virtual-HSM), all keys generated by the EP11 token strictly belong to the EP11 token that created it. Every EP11 token running in this mode requires a VHSM card-PIN which must be set using the pkcsep11_session tool.

This option can not be combined with FIPS_SESSION_MODE, but can be combined with STRICT_MODE.