Submitting an association secret

Edit online

Create an add-secret request for an association secret, transfer it to the secure guest, and then submit it to the ultravisor.

About this task

An add-secret request that contains an association secret must be created in a secure environment by using the pvsecret create command with the association sub-command. The add-secret request must be transferred to the IBM Secure Execution guest that shall use the association secret. From within the guest, the add-secret request is submitted to the ultravisor by using the pvsecret add command.

An association secret is a 32-byte value. It is referenced by a corresponding 32-byte identifier, the association secret identifier. If a secret is not provided with the --input-secret option, the command generates a random secret. For details about the --input-secret option, see pvsecret create.

Save the random association secret as plain text by using the --output-secret option. Save the resulting file securely. The value of the random secret is required to create add-secret requests for an updated version of the guest image. In that case, use the --input-secret option to create updated add-secret requests for the updated secure execution boot image. Destroy the secret when you are positive that it is no longer used.

The pvsecret command computes the identifier of the secret as an SHA-256 hash of a string that you specify with the association parameter.

Procedure

On a trusted system, generate an add-secret request. The request is written to a file that you specify.
Issue 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>  
<name> --output-secret <association_secret>
```
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).
- <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
To create an add-secret request that contains a random association secret with the name myConfidentialSecret and save this random association secret to my_random_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  "myConfidentialSecret" --output-secret my_random_secret
```
The command also creates an identifier for the request, consisting of an SHA-256 hash of the string myConfidentialSecret.
On the KVM guest that is running in secure-execution mode, insert the secret.
Issue a command of the following form:
```
[se_guest]# pvsecret add <request_file>
```
where <request_file> contains the request with the association secret to be added to the secret store.
For example, to use the add-secret request that was created in the previous step, issue:
```
[se_guest]# pvsecret add addSecretReq
```

Results

The secret is added to the store of secrets in the ultravisor. You can list all stored secrets by issuing:

[se_guest]# pvsecret list
Total number of secrets: 1

0 Association:

546869732069732061207665727920736563726574207365637265742069642e

The output of pvsecret list shows that one secret is listed which has index 0, is of type Association, and has the association secret identifier 546...42e.

As described so far, add-secret requests are limited to secure guests that are booted from specific boot images. However, without further precautions, nothing prevents attackers from replacing your add-secret request with their own containing a known secret. See Preventing the misuse of add-secret requests for further protection.