Crypto Express adapters for secure-execution guests

Edit online

You can use Crypto Express adapters for KVM guests that run in secure-execution mode.

Each adapter is divided into multiple domains. Each domain acts as an independent cryptographic device, for example, as a hardware security module (HSM), with its own state, including its own HSM master key. In Linux, cryptographic adapter resources are managed as AP queues. An AP queue corresponds to a specific cryptographic domain on a specific cryptographic adapter and is denoted by the pair of adapter ID and domain ID in hexadecimal format, for example, 27.0014, 28.0014, or 28.0015. This is also called an AP queue number (APQN).

Prerequisites

You need a secure-execution boot image that supports the insertion of secrets into the ultravisor, see Submitting an association secret.

You can use Crypto Express8S adapters:
  • Configured in accelerator mode.
  • Configured in Enterprise PKCS #11 coprocessor mode. You require Enterprise PKCS #11 version 5.8.30.

The adapter domains must be configured in passthrough mode (dedicated) for Crypto Express8S adapters. A maximum of 12 adapter domains per secure guest can be configured.

Binding

Both accelerator and Enterprise PKCS #11 coprocessor mode AP queues must be bound to the secure guest.

For a Crypto Express adapter in accelerator mode, binding is all you need to do. For details, see Crypto Express adapter in accelerator mode.

Associating

To use HSMs, that is Crypto Express adapters in Enterprise PKCS #11 coprocessor mode, you must also associate corresponding AP queues with a secret. A secure-execution guest must submit the secret to the ultravisor before it can be associated with an AP queue.

Before an AP queue is associated with an association secret, you should verify that the adapter domain addressed by the AP queue is configured as expected. In particular, confirm that the master key verification pattern of the AP queue is the expected one.

Associating a secret with an AP queue that is configured with the wrong HSM master key might lead to security issues.

All requests that do not involve a secure key can be submitted to an AP queue that is bound, but not yet associated. Such requests include querying the properties of an EP11 domain, and issuing the commands needed to set the HSM master key through the ep11TKEd.