Keys used by IBM Z cryptographic hardware

Key categories

The keys processed by the systems as described in IBM Z cryptographic hardware categories 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.

This documentation describes the APIs offered by the libzpc library. Use these APIs to exploit the advantages of CPACF cryptographic functions working with protected keys. In libzpc, a protected key is derived from a persistent secure key, both using the same effective key. The effective key of the persistent secure key is unwrapped with the master key of a cryptographic coprocessor and is re-wrapped with the wrapping key of an LPAR or virtual guest. Therefore, as protected keys are volatile, this method ensures that a new protected key with the same wrapped effective key can always be derived whenever an old protected key does no longer exist or is no longer valid.

Key types

Key types as used by libzpc can be classified depending on the method by which libzpc converts them into protected keys for use on the CPACF for quick cryptographic processing.

CCA keys

Generally, CCA keys are secure key tokens (or blobs) where the wrapping master key is stored on a cryptographic coprocessor configured in CCA mode and where these CCA secure keys are used for encryption and decryption, for example. Therefore, the conversion of such CCA secure keys into protected keys always requires a cryptographic adapter. And consequently, the resulting converted protected key is called a CCA key by libzpc.

EP11 keys

EP11 secure keys are blobs where the wrapping key is stored on a cryptographic coprocessor configured in EP11 mode. The conversion into a protected key therefore requires a so-called EP11 coprocessor. The resulting converted protected key is called an EP11 key by libzpc.

Note:

In the EP11 context, a key that wraps a clear key to form a secure key is called a wrapping key which can be identified by its wrapping key verification pattern (WKVP).

In the CCA context, such a wrapping key is called a master key which can be identified by its master key verification pattern (MKVP).

Retrievable secrets

Keys - or better secrets - of this type only exist in an IBM Secure Execution for Linux® (SEL) environment, where such a retrievable secret was added to the ultravisor for a KVM SEL guest with an add-secret request. libzpc can derive protected keys from such a secret only on a KVM SEL guest.

Read about the underlying concepts in Introducing IBM Secure Execution for Linux (SC34-7721).

CCA and EP11 key types are backed by related secure keys, while retrievable secrets have no corresponding secure key and no associated adjunct processor queue number (APQN) nor master key verification pattern (MKVP). Instead, they are backed by secrets stored in the guest's ultravisor. With a given secret ID, libzpc can derive the related protected key with the information stored in the ultravisor (see How to create a protected key for libzpc programming). Just like protected keys derived from CCA and EP11 secure keys, these retrievable secret protected keys can be used for AES or ECC cryptography and additionally in the provided HMAC and full-XTS APIs.

Key algorithms

Keys are also distinguished by the algorithms with which they are used.

AES keys

AES is an algorithm for symmetric (secret) keys. AES keys can be used with all AES modes of operation.

AES-XTS keys

AES-XTS keys can only be used with the AES-XTS mode of operation.

ECC keys

Elliptic curve cryptography (ECC) algorithms are used for operations with an asymmetric key pair of a private and a public key. So, ECC keys can be used for private-key operations with the elliptic curve cryptography algorithm.

HMAC keys

Hash-based message authentication code (HMAC) is an algorithm that uses a secret cryptographic key and a hash function to generate a fixed-size authentication tag for a message. HMAC keys can be used for operations with the HMAC algorithm (in libzpc: only SHA2 hash configurations).

Protected keys reference