How and why to exploit protected keys

Edit online

For the CCA token and the EP11 token you can optionally improve the performance of your cryptographic processing of certain algorithms by enabling the use of protected keys for these tokens. For the use of the AES XTS cipher mode, exploitation of protected keys is mandatory for these tokens.

The keys processed by the openCryptoki tokens fall into one of the following categories:

clear key
A clear key is an effective key in plain text. That is, the bit pattern of a clear key is the one that is used by the cipher algorithm. Thus, the clear key is the same as the effective key. The term clear key is commonly used in the context of IBM Z® cryptographic hardware. Therefore, whoever knows the clear key can perform cryptographic operations (like encrypt or decrypt) using that clear key.
secure key
A secure key is a clear or effective key encrypted by an HSM master key. Secure keys can be used in cryptographic functions performed by the HSM. Thus, each cryptographic function on a secure key requires I/O operations to the HSM. A secure key is only usable in the HSM in which it was generated, or in an HSM that is configured with the same master key as the HSM that was used to generate the secure key.
protected key
Protected keys are keys encrypted by the machine-generated IBM® firmware wrapping key of an LPAR, a virtual server, or a z/VM® or KVM guest. A protected key is created by IBM Z firmware and can only be used by the instance of the operating system that created that key. Also, protected keys are volatile, because they are only valid as long as the LPAR, the virtual server, or the z/VM or KVM guest that generated the key is running. The operating system has no access to the effective key within a protected key, and protected keys are useless on any other system. Protected keys are used for high performance symmetric AES cryptographic functions processed by the CPACF. The CPACF also provides protected key support for DES/TDES and ECDSA and EdDSA signing functions. As the CPACF is implemented as a feature of an IBM Z CPU, it performs cryptographic operations at CPU speed.

IBM Z cryptographic hardware can use clear keys, secure keys or protected keys. The difference between these key types is not the value of the effective key which is the plain text key that is used to encrypt the data. However, the difference is the strength of protection that is applied to the effective key. And, of course, resulting from the different strength of protection, there is also a difference in the performance. There is no difference in the cryptographic algorithms used by the hardware, and the resulting cipher text is the same for all types of key if the underlying effective key is the same.

When working within the openCryptoki environment, the type of key that you use is determined by the token type. That is, in openCryptoki there are clear key tokens and secure key tokens:

  • ICA tokens and Soft tokens are clear key tokens.
  • CCA tokens and EP11 tokens are secure key tokens. Secure keys can only be processed on IBM Z cryptographic coprocessors configured as HSM with a valid master key. However, openCryptoki on IBM Z provides an option for these token types to transparently derive a high performance protected key from a strongly shielded secure key, which provides advantages for certain use cases.

Protected keys versus secure keys

The differences between protected and secure keys are the following:

  • In contrast to cryptographic operations performed with protected keys on the CPACF, operations with secure keys are performed on IBM Z cryptographic coprocessors.
  • Protected keys offer performance advantages, but are not quite as secure than secure keys. On the other hand, secure keys work on tamper-proof hardware security modules like the IBM Z cryptographic adapters, and therefore require input/output operations.
  • With CCA tokens and EP11 tokens you can explicitly set a configuration option PKEY_MODE to allow the derivation of a protected key from a secure key if adequate and required. This derivation then works transparently during the affected cryptographic operations.

    Thus, you can optionally enable CCA and EP11 tokens to exploit the performance optimization provided by protected keys in contrast to secure keys. If you enable option PKEY_MODE, then all applicable cryptographic operations are performed with derived or existing protected keys on the CPACF. If no protected key is allowed or cannot currently be derived, then the affected cryptographic operations are performed with a secure key on the cryptographic coprocessor.

Protected keys in read-only and read-write sessions

In PKCS #11, an application either opens a read-only or a read-write session.

  • In both session types, applications can create, read, modify, and delete session objects. Session objects have the attribute CKA_TOKEN=FALSE.
  • In read-write sessions, applications can additionally create, read, modify, and delete token objects. Token objects have the attribute CKA_TOKEN=TRUE.
  • Read-only sessions can also read token objects.

Token objects are persistent and are saved on disk in the token repository. Session objects are non-persistent and are destroyed when the session ends.

If you create a key object with CCA or EP11 tokens where the PKEY_MODE option is enabled, then the protected key is not derived from the secure key immediately, but only at the first use of the key object (valid for both session or token objects).

  • With a key object that is a persistent token object (CKA_TOKEN=TRUE), a derived protected key is bound to the key object as attribute CKA_IBM_OPAQUE_PKEY and thus is saved in the token repository as part of the key object (see also IBM-specific attributes). This is, however, only possible in a read-write session, because only in a read-write session, an application can create, modify, and delete persistent token objects.
  • With a non-persistent key object (CKA_TOKEN=FALSE), a derived protected key is also bound to the key object as attribute CKA_IBM_OPAQUE_PKEY, but is not saved in the token repository and only exists within memory as long as the creating session exists.

With all this background knowledge, the implemented processing and its consequences for the use of protected keys may be understandable:

If a key object is used for a cryptographic operation, the CCA or EP11 tokens check whether a valid protected key is available (valid means: the current firmware master key can still unwrap the protected key). If this is the case, the protected key is used for improved performance.

If no (or no valid) protected key is available, then the CCA or EP11 tokens try to derive a new protected key. Derivation is of course only performed if the prerequisites of an enabled PKEY_MODE are fulfilled.

  • If the derivation succeeds, the new protected key is used.
  • If a protected key cannot be derived, then the current cryptographic operation is performed with the secure key on the cryptographic coprocessor, which works slower than protected key processing on the CPACF.
    Note: However, if you use the AES XTS cipher mode, then the current cryptographic operation fails, because for CCA and EP11 tokens there is no AES XTS processing possible on the cryptographic coprocessors.

Conditions for a protected key derivation

A protected key can be successfully derived from a key object if several conditions are fulfilled. In addition, a derivation can only be performed in session types where the PKCS #11 standard allows object modification. For a detailed information you can read about PKCS #11 sessions.

  • The hardware supports protected keys: CPACF is required.
  • PKEY_MODE is enabled.
  • The key object has boolean attribute CKA_IBM_PROTKEY_EXTRACTABLE=TRUE.
  • For persistent token key objects (CKA_TOKEN=TRUE):
    • If they have attribute CKA_PRIVATE=TRUE, then derivation is only allowed in R/W User sessions.
    • If they have attribute CKA_PRIVATE=FALSE, then derivation is allowed in R/W Public sessions, R/W User sessions, or R/W SO sessions.
  • For non-persistent session key objects (CKA_TOKEN=FALSE):
    • If they have attribute CKA_PRIVATE=TRUE, then derivation is only allowed in R/W or R/O User sessions.
    • If they have attribute CKA_PRIVATE=FALSE, then derivation is always allowed.

An example where protected key derivation does not work: A persistent key token object that has been created in a R/W session may be used for cryptographic operations for the first time in another session. If this session is for example, a read-only session, it is not possible to derive a protected key, because the key object would need to be updated. For AES XTS keys, such a scenario would lead to an error.

Prerequisites

Note: The documented prerequisites (including a functioning configuration of the PKEY_MODE option in the respective configuration files) are required for protected key processing. For the AES XTS cipher mode, a functioning PKEY_MODE setting is mandatory. For secure key types other than AES XTS, secure key processing on cryptographic coprocessors is used if PKY_MODE is not enabled or other prerequisites are not fulfilled. All detailed information is provided in Defining a CCA token configuration file and Defining an EP11 token configuration file.

There are the following hardware and software prerequisites for enabling protected key support in CCA tokens and EP11 tokens:

Hardware prerequisites common for CCA and EP11 tokens

Using the protected key support is possible on IBM z15® or later processors with a CEX7C coprocessor in CCA mode for CCA tokens or on CEX7P EP11 cryptographic coprocessors for EP11 tokens.

For supporting protected keys for extractable keys with the EP11 token, a CEX7P or CEX8P is required.

Software prerequisites - CCA token:

  • the CCA host library 7.0 or later,
  • the Linux® kernel 5.10 or later.

Software prerequisites - EP11 tokens:

  • the EP11 host library version 3.0 or later.

Configurations in the ccatok.conf and ep11tok.conf configuration files

  • CCA and EP11 tokens must have protected keys enabled using the PKEY_MODE option set as ENABLED (for CCA tokens), ENABLE4NONEXTR (for EP11 tokens), or DEFAULT (valid for both).
  • If PKEY_MODE is set to DISABLED, no protected keys can be used and AES XTS mechanisms are not supported.