Terminology
Often, multiple different terms are used to denote the same technical construct. This publication defines a certain terminology and uses it consistently throughout all topics.
- cryptographic coprocessor
- A Crypto Express cryptographic coprocessor is often also
referred to as cryptographic card or cryptographic adapter or just adapter. If a cryptographic coprocessor is tamper-proof and performs cryptographic
operations on cryptographic keys protected by the coprocessor, then such a coprocessor is called a
hardware security module (HSM).
A cryptographic coprocessor is divided into multiple domains, also called AP queues. Each AP queue acts as an independent cryptographic device (HSM) with its own state, including its own master key.
If this publication mentions a cryptographic coprocessor, this term is used as a synonym for a coprocessor configured in CCA mode (CCA coprocessor) or configured in EP11 mode (EP11 coprocessor).
- APQN
- AP queues are identified by their adjunct processor queue number (APQN). An APQN designates the combination of a cryptographic coprocessor (adapter) and a domain. In the infrastructure for protected volume encryption, for example, the APQN 03.0039 specifies the domain 0039 on the cryptographic coprocessor with ID 03.
- clear key
- A clear key is a key in plain text. That is, the bit pattern of a clear key is the one that is
used in the mathematical description of a cipher. Therefore, whoever knows the clear key can perform
cryptographic operations (like encrypt or decrypt) using that clear key.
Important: Use IBM-provided utilities and hardware to generate a clear key. You should never explicitly generate a clear key unless this operation is performed in a clean room environment. Otherwise you risk being observed during the clear key generation, or some software components still contain some remains of the generated clear key.
- master key
- A master key is a wrapping key or a key-encrypting-key (KEK) used to encrypt a key. In the
IBM Z® cryptographic
hardware, a master key is protected from any
access from outside this hardware.
There are two types of master keys in the IBM Z cryptographic hardware environment:
- HSM master key
- Each domain of a Crypto Express cryptographic coprocessor
can contain active master keys which are used to generate secure keys. The IBM® Crypto Express CCA coprocessor actually can maintain four master keys per domain:
one to wrap DES/Triple DES keys, one to wrap AES (and HMAC) keys, one to wrap RSA keys, and one to
wrap ECC keys. In the context to this document, only AES master keys are of importance.
Starting with IBM z15™, the infrastructure for protected volume encryption also supports the use of the latest generation of Crypto Express cards (CEX7S) as HSMs in EP11 mode (CEX7P). An EP11 cryptographic coprocessor (CEX7P) uses an AES master key for encryption of the secure key. In the EP11 documentation, this master key is often referred to as wrapping key.
- firmware master key
- For each virtual server (LPAR or guest), the firmware maintains master keys in storage, which are used to generate protected keys. These master keys are protected against operating system access. In the context of this document, only the AES master keys of the firmware are of importance.
- effective key
- An effective key is a plain text key. This term is used in connection with wrapped keys. For example, for a secure key consisting of a key wrapped by a master key, that key is the effective key of the secure key. If a protected key is derived from a secure key, then both the protected key and the secure key have the same effective key. The effective key of a multiply wrapped key is the innermost plain text key.
- protected key
- A protected key is a key encrypted by a firmware master key. The effective key of the protected
key cannot be discovered by the operating system. Protected keys can be used in cryptographic
functions performed by the CPACF component of the
IFL (CPU) and therefore are performed at CPU speed.
A protected key is only valid inside the virtual server instance that generated the protected key. A protected key of a virtual server can be derived from a secure key of an HSM attached to that virtual server. In that case, the effective keys of the protected key and the effective key of that secure key are the same.
- secure key
- A secure key is a 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 valid in the HSM it was generated in.
A secure AES key generated in a domain of an IBM Crypto Express coprocessor (configured in CCA or EP11 mode) can be transformed into a protected AES key for the virtual server attached to that domain of the CCA or EP11 coprocessor. Then the effective key of the generating secure key and the effective key of the derived protected key are the same.
In the infrastructure for protected volume encryption, you can decide between various types of secure keys: a CCA AES DATA key, a CCA AES CIPHER key, and an EP11 AES secure key. For information about the differences between these types, read the Secure key considerations.
- hardware security module (HSM)
- A hardware security module is a tamper protected cryptographic device that protects secrets (typically master keys) from being inspected. IBM Crypto Express CCA coprocessors and EP11 coprocessors are certified as HSMs. Each domain of an IBM Crypto Express coprocessor constitutes a (virtual) HSM and maintains a domain-specific master key or a set of master keys.
- volume
- A volume refers to a Linux™ block device (for example, a DASD partition or a SCSI disk, or a logical volume). This publication also uses the term disk or disk partition when referring to an example of a volume.
- LUKS1 or LUKS2 volume key
- A key used to encrypt and decrypt the user data on a volume formatted in LUKS1 or LUKS2 format. A key slot in the LUKS1 or LUKS2 header stores a wrapped copy of this volume key,
where the wrapping key is derived from the user's passphrase. In the infrastructure for protected volume encryption, the LUKS2 volume key is a secure key. Hence, the effective
volume key is twofold protected: it is encrypted by an AES master key from a CCA or EP11 coprocessor and by a wrapping key or KEK derived from
a passphrase. Therefore, to unlock a LUKS2 volume,
a passphrase - provided interactively or from a key file - is required to decrypt the outer
wrapping.
The security provided by the passphrase is typically much lower than that provided by the wrapping AES master key. Therefore the password may be exposed without any loss of security. When a secure key for the PAES cipher is provided to dm-crypt in order to open a volume, it automatically transforms this secure key into a protected key that can be interpreted by the CPACF. The actual effective key of the LUKS2 volume key is never exposed to the operating system.