Using a simple extension secret

Edit online

Use the --extension-secret option to use a 32-byte random secret to enhance the security of the pvsecret create command.

For a specific secure-execution guest instance, the ultravisor only accepts add-secret requests that share the same extension secret. You can specify the extension secret with the --extension-secret option to prevent your add-secret request from being used together with an add-secret request of an attacker.

After you prime the ultravisor with an extension secret, all subsequent add-secret requests must include the same extension secret. If no extension secret is specified with either the --extension-secret option or the --cck option, a string consisting of 32 zeroes is used.

Procedure

On a trusted system, add the extension secret to the pvsecret create command.
Specify a command of the following form on one line:
[trusted]# pvsecret create association -k <host_key_document> --hdr <SEL_header> 
-o <request_file> -C <CA_certificate> -C <IBM_signing_certificate> 
--extension-secret <ext_secret>  <name>
where:
  • association specifies that the add-secret request is for an association secret.
  • -k <host_key_document> specifies the host key document.
  • --hdr <SEL_header> specifies the header of the KVM guest.
  • -o <request_file> specifies the file that contains the generated add-secret request.
  • -C <CA_certificate> specifies the certificate that is used to establish a chain of trust for the verification of the host key documents. Specify this option twice to specify the IBM Z signing-key certificate and the intermediate CA certificate (signed by the root CA).
  • --extension-secret <ext_secret> uses the contents of the input file as extension secret. The file must be exactly 32 bytes long. If this request is the first, all subsequent requests must have the same extension secret. If no extension secret is specified with either the --extension-secret option or the --cck option, a string consisting of 32 zeroes is used.
  • <name> A string that identifies the new secret. Strings are hashed with SHA-256 to form the ID that is used by the ultravisor. The ID is saved in <name>.yaml with white-spaces mapped to underscores ( _ ).
For example, to use:
  • a host-key document z16.crt
  • a guest header se.hdr
  • a CA certificate DigiCert.crt
  • an IBM signing key ibm-sign.crt
  • a random association secret named myConfidentialSecret
  • a file called myExtSecret that contains the extension secret
issue the following command on a trusted system:
[trusted]# pvsecret create association -k z16.crt --hdr se.hdr 
-o addSecretReq -C DigiCertCA.crt -C ibm-sign.crt 
--extension-secret myExtSecret "myConfidentialSecret"
The command creates an add-secret request in addSecretReq. The security of the request is now enhanced by an extension secret.