Using a customer-communication-key based extension secret

Edit online

Use the pvsecret create command with the -cck option to use an RFC-5869-HKDF derivative of the customer communication key (CCK) to enhance security of the pvsecret create command.

This ensures that only the builder of the secure-execution header, that is, someone who knows the CCK, can add add-secrets request to the guest instance.

About this task

During the creation of a secure execution boot image, the creator can specify that the extension secret must be derived from the customer communication key (CCK). 
# pvimg create <other_pvimg_options> --enable-cck-extension-secret -cck <cck_file>
If that option was specified at image creation, the add-secret request must use the corresponding -cck <cck_file> option. For details about using pvimg create to create an image, see Securing the guest.
Note: The pvimg create command option --cck was called --comm-key in previous versions.

The pvsecret command derives the extension secret from the CCK by performing an RFC-5869 HMAC-based extract-and-expand key derivation function (HKDF) operation with hashed message authentication code (HMAC) SHA-512 and "IBM Z Ultravisor Add-Secret" as information material. The firmware verifies that the extension secret was indeed derived from the CCK; otherwise it aborts the operation.

Procedure

Add the --cck 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> 
--cck <cck_file>  <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).
  • --cck <cck_file> specifies the customer-communication key (CCK) to derive the extension secret.
  • <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
and let the command create a random association secret that is named myConfidentialSecret and derive the extension secret from the CCK:
[trusted]# pvsecret create association -k z16.crt --hdr se.hdr 
-o addSecretReqCCK -C DigiCertCA.crt -C ibm-sign.crt 
--cck cck "myConfidentialSecret"
The command creates an add-secret request that contains a random association secret with the name myConfidentialSecret and writes it to addSecretReqCCK. The command also creates an identifier for the request, consisting of an SHA-256 hash of the string myConfidentialSecret and writes it to myConfidentialSecret.yaml.

If the CCK does not match the CCK of the running guest instance, pvsecret add fails.