Considerations for programming with retrievable secrets

Edit online

To exploit the libzpc support of retrievable secrets, certain hardware and software prerequisites are required.

Prerequisites for retrievable secrets

libzpc must run in an IBM® Secure Execution for Linux® (SEL) environment:

  • A KVM SEL guest
  • running on an IBM z17 ™ system
  • under a Linux kernel 6.13 or later with support for retrievable secrets.
  • To retrieve the ID of such a secret on the KVM SEL guest, the pvsecret utility from s390-tools v2.37 or later must be available.

Additional hardware prerequisites for protected keys derived from retrievable secrets:

  • Message security assist (MSA) 10 (IBM z17 ) for full-XTS protected keys
  • Message security assist (MSA) 11 (IBM z17 ) for HMAC protected keys

Using libzpc APIs with retrievable secrets

The behavior of retrievable secrets is different to CCA and EP11 keys. You need to observe the following considerations, when using the libzpc APIs for cryptography with retrievable secrets:

  • Retrievable secrets (sometimes also referred to as pvsecrets, where pv stands for protected virtualization) are not wrapped by secure keys, but are identified by 32-byte IDs, from which libzpc can retrieve the pertaining protected key from the ultravisor. Such IDs can be imported and exported in the same way as real secure key blobs for CCA and EP11 type keys.
  • Generating new retrievable secrets with libzpc is not possible. Protected keys can only be derived or re-derived from existing secret IDs.
  • Re-enciphering protected keys is not applicable, because there is no related secure key, nor an HSM with the corresponding master key. Re-enciphering only applies to secure keys, when the effective key is re-wrapped by a new master key. Protected keys can only be re-derived from either a related secure key or from a retrievable secret.
  • There is an important difference of importing ECC retrievable secrets versus importing ECC secure keys. ECC secure key tokens may contain both key parts, the private and the public ECC key. Importing retrievable secrets is just importing the 32-byte ID, followed by the retrieval of the corresponding private protected key. So importing ECC retrievable secrets only covers the private key.
  • You can export a 32-byte secret ID into a buffer of your application with either the zpc_aes_key_export() or the zpc_ec_key_export() API. A use case maybe storing the retrievable secrets on disk for further reuse.