Protected key device driver

Red Hat Enterprise Linux 9.2 LPAR mode z/VM guest KVM guest

The protected key device driver provides functions for generating and verifying protected keys.

Protected keys are encrypted with wrapping keys that, for Linux® in LPAR mode, are specific to the LPAR. For guests of z/VM® or KVM, the wrapping key is specific to the guest. Both the wrapping keys and the clear key values of protected keys are invisible to the operating system. Protected keys are designed for accelerated encryption and decryption with CPACF. For more information, see the chapter about protected keys in z/Architecture® Principles of Operation, SA22-7832.

Pervasive encryption uses protected keys for data-at-rest, see Pervasive Encryption for Data Volumes, SC34-2782.

Functions

The device driver provides the following functions to cryptographic applications. The following secure key functions require a Crypto Express adapter:

Generate a secure key from random data, then generate a protected key from the secure key.
The secure key must be available to create a new version of the protected key whenever the current protected key is invalidated.
Generate a secure key from a clear key, then generate a protected key from the secure key.
The clear key must be in memory when the protected key is generated. Thereafter, the clear key can be deleted.

The secure key must be available to create a new version of the protected key whenever the current protected key is invalidated.

The following functions do not require a Crypto Express adapter:

Generate a protected key from a clear key. The clear key must be in memory when the protected key is generated.
The clear key must also be available to create a new protected key if the existing protected key is invalidated.
Generate a protected AES key from random data.
The effective clear key is never exposed in memory.

Important: The key is volatile and cannot be recreated if lost, for example during a reboot. Use a protected key generated from random data only to protect transient data.

The device driver also provides an in-kernel interface to generate protected keys. This interface is used, for example, by the paes_s390 module.

Prerequisites

The protected key device driver requires the message-security-assist-extension 3 facility (MSA level 3), which was introduced with z196.

The protected key device driver requires permission for the AES key import functions. To grant this permission, go to the security settings within the profile of the applicable LPAR on the HMC. In the CPACF Key Management Operations section, select the Permit AES Key import functions option. For z/VM and KVM guests, the LPAR in which the hypervisor runs requires this option.

Secure keys are encoded with a master key that is held in an AP queue. Functions that involve secure keys require an IBM® Crypto Express adapter in CCA coprocessor mode with a valid master key. For Linux on z/VM, the adapter must be dedicated to the z/VM guest virtual machine.

Crypto Express adapters can provide the following types of secure keys:

CCA AES data secure key: Requires an IBM CEX4S or later adapter in CCA coprocessor mode.
CCA AES cipher secure key: Requires an IBM CEX6S or later adapter in CCA coprocessor mode.
CCA ECC secure key: Requires an IBM CEX7S or later adapter in CCA coprocessor mode.
EP11 AES secure key: Requires an IBM CEX7S adapter in EP11 coprocessor mode.
EP11 ECC secure key: Requires an IBM CEX7S adapter in EP11 coprocessor mode.