Submitting a secret to the ultravisor

Edit online

An IBM Secure Execution guest can submit a secret to the ultravisor. The secret must be contained in a an add-secret request.

The add-secret request is protected with the help of the host key and a random Elliptic Curve Diffie–Hellman (ECDH) key pair. Different types of secrets can be submitted:
  • As of IBM z16, null-secrets and association secrets are supported.
  • As of IBM® z17 ™, plaintext secrets and protected keys are supported as retrievable secrets.
  • As of IBM z17, you can submit a customer communication key (CCK) to replace the original CCK from the SE-header if the builder of the SE-header allows this operation.

Inserting a secret into the ultravisor of a guest is a prerequisite for associating an AP queue with the guest, see Binding and associating an EP11 adapter AP queue using the chzcrypt command.

Retrievable secrets

Retrievable secrets can contain key material or plaintext secrets, that can be used, for example, to encrypt I/O or specify service configurations. Since retrievable secrets are stored in the ultravisor, they don’t need to be stored in the secure image. This means that you can create generic images that are later customized through retrievable secrets. Thus initial image generation is simplified as are image updates. There is no need for guest attestation, and no interaction between guest and guest owner during guest start-up is required.

With retrievable secrets, you have a means to pass secrets as protected keys to a SEL guest. Using protected keys means that the plaintext value of the key is never stored in the guest memory. You do not require an HSM to manage protected keys. You can use retrievable secrets with dm-crypt, see Pervasive Encryption for Data Volumes, SC34-2782.

Before you begin

For association and null secrets you require the following hardware and software:
  • IBM® z16® with the latest firmware updates with Crypto Express support for secure execution on IBM Z.
  • A Linux distribution that supports the uv device:
    • Ubuntu 24.04
    • Red Hat® Enterprise Linux® 9.4 and 8.10
    • SUSE Linux Enterprise Server 15 SP6
  • s390-tools version 2.29 or later.
To create the add-secret request you also require:
  • A trusted system - a system that can be trusted to not be compromised or tampered with. For example, an attested IBM Secure Execution guest or a local workstation.
    Important: The trusted system must not be the same guest as the one into which you want to insert the secret. This prevents secrets from appearing in clear text on the target guest.
  • The SEL header of the guest you want to work with. For details about how to extract a header, see Extracting an IBM SEL header.
  • One or more host key documents.
  • An IBM-signing key certificate.
  • An certificate authority (CA) certificate.
For retrievable secrets, you require:
  • an IBM SEL guest on an IBM z17 ™.
  • The ultravisor and the uv device must support the secret-store extension including retrieving secrets.
  • The pvsecret command must support the new secret types and the retrieval function. However, you can create the add-secret request on either z/Architecture or x86, assuming that the pvsecret command is installed.

About this task

You can use the pvsecret command to:

For the complete command syntax and reference, see pvsecret - Create requests, add and list secrets, and lock the store of secrets.