Skip to content

Add wrapped-key cipher support to cryptsetup

username-removed-1252795 requested to merge (removed):wrapped-key-support into master

This merge request introduces support for using wrapped-key ciphers for disk encryption. Wrapped-key ciphers use a key, which itself is encrypted (wrapped) by another key (the wrapping or key-encryption key). Wrapped-key ciphers are identified by its name, as specified by the --cipher option.

The primary benefit of using wrapped keys rather than clear keys is that the wrapped clear key is never exposed in the memory of the operating system. With this you can provide end-to-end security systems where the wrapping/key-encryption keys, for example, are maintained in an HSM. For disk encryption, that means, the volume encryption key on the disk exists in its wrapped form only.

Summary of cryptsetup changes

To support wrapped-key ciphers, a set of callback functions are introduced that need to be implemented by wrapped-key cipher implementations. These functions integrate seamlessly into cryptsetup to deal with the differences that originate from using wrapped keys.

Also, the protected-AES (paes) wrapped-key cipher implementation is added by using the previously introduced functions. The paes cipher implements the AES encryption standard but uses wrapped keys. It is available on the Linux on z Systems platform. To use the paes cipher to encrypt a disk, specify '--cipher paes-cbc-plain64' or '--cipher paes-xts-plain64' with luksFormat.

Concepts and details on wrapped-key cipher support

To perform cipher operations with wrapped keys, wrapped keys must be be un-wrapped but for this, the wrapping key must be known. Wrapping/key-encryption keys are typically stored in Hardware Security Modules (HSMs) and do never leave the HSM. Wrapped-key cipher operations thus happen inside the HSM. The data to be encrypted or decrypted and the wrapped key is passed to the HSM. Within the HSM, the wrapped key is un-wrapped (using the wrapping/key-encryption key) and, then, the crypto operation is performed.

Note that wrapped keys typically have a different format and size than a clear-key. They are mostly contained in a key-blob that might contain additional meta-information. Because of this, wrapped-key ciphers have certain constraints to the key material. For example, wrapped keys cannot be simply generated as random byte strings, but must be generated within an HSM. Also, wrapping/key-encryption keys might expire and become replaced with new ones which requires that a wrapped key must be re-wrapped. (See also patch 2/3).

As reference implementation and example, the protected-key-AES (paes) wrapped-key cipher implementation is added.

The paes cipher is an in-kernel crypto module (kernel >v4.11) available on the Linux on z Systems platform. It implements AES but uses wrapped keys. The key that is passed to the paes cipher is a so-called 'secure key'. Secure keys are wrapped keys that are generated by an HSM, in particular, an IBM CryptoExpress card (in CCA coprocessor mode). The kernel also provides the pkey ioctl interface to generate, convert, and validate secure keys.

The clear key used for the cipher operations is encrypted (wrapped) with the master key of the HSM, forming a secure key. To speed up secure key cipher operations, the paes cipher transforms secure keys into so-called 'protected keys' as intermediate wrapped keys. Protected keys are wrapped keys whereby the clear-key is wrapped by a wrapping key stored in hidden memory accessible only by z Systems firmware. Cipher operations with protected keys are performed on a co-processor inside the CPU and are therefore much faster than secure key operations which require an I/O to the HSM for each cipher operation. With the help of a CryptoExpress card a secure key can securely be transformed into a protected key. Note, the wrapping keys inside the z Systems firmware are (re)generated with every system boot. Therefore protected keys are volatile and must be regenerated from the (non-volatile) secure keys whenever they are used for the first time after an system boot (or image migration).

Thanks and kind regards, Ingo, Hendrik

Merge request reports