Using a random secret

By default, a random association secret is created. You need to save this secret for later updates of the image.

Procedure

On a trusted Linux instance, issue a pvsecret create command to create the request for adding a random association secret. The request is written to a file that you specify.
Specify a command of the following form on one line:
```
[trusted]# pvsecret create association -k <host_key_doc> --hdr <SEL_header> 
-o <request_file> --crt <CA_certificate> --crt <IBM_signing_certificate> 
 <name> --output-secret <association_secret>
```
The command uses the following options:
- association specifies that the add-secret request is for an association secret.
- The -k option specifies the host key certificate, which assures that the request can only be processed on the intended IBM Z® or IBM® LinuxONE 4 system.
- The --hdr option specifies the header of the secure image, or the IBM Secure Execution image itself.
- The -o option specifies the output file, <request_file>, for the request.
- The string, <name>, from which the pvsecret command computes the identifier of the secret as an SHA-256 hash.
- Two --crt options specify the IBM Z signing key and the CA certificate to establish the chain of trust.
- The --output-secret option saves the random association secret as plain text to <association_secret>. Save the resulting file securely. The value of the random association 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 it is no longer used. For more details, see pvsecret create.
The command creates these output files:
- The request, written to <request_file>.
- A .yaml file with an identifier of the secret, written to <name>.yaml.
- The random association secret as plain text, written to <association_secret>.
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 my secret and save this random association secret to my_random_secret, issue the following command on a trusted system:
```
# pvsecret create -k z16.crt --se-hdr se.hdr -o my_addsecreq \
--crt DigiCertCA.crt --crt ibm-sign.crt association "my secret" --output-secret my_random_secret
```
The command creates:
- An add-secret request that contains a random association secret with the name my secret. The request is written to my_addsecreq.
- An identifier for the secret, consisting of an SHA-256 hash of the given association string my secret. The identifier is written to my_secret.yaml.
- The random association secret as plain text, written to my_random_secret.
Create a pvapconfig configuration file (in .yaml format) with an entry that describes your AP queue.
You need the secret ID from the .yaml file created with the pvsecret create command in the previous step, the master key verification pattern of the AP queue from the HSM domain administrator, and optionally the serial number of the Crypto Express adapter.
For example, a simple pvapconfig configuration file file can look like this:
```
- mode: EP11
  mkvp: 0xdb3c3b3c3f097dd55ec7eb0e7fdbcb93
  serialnr: 93AADFK719460083
  secretid: 0x546869732069732061207665727920736563726574207365637265742069642e
```
For details about the syntax of the pvapconfig configuration file, see pvapconfig configuration file.
Transfer the request and configuration file to the secure guest.
You can use secure copy, or a similar program.
For example:
```
[trusted]# scp my_addsecreq seguest:
[trusted]# scp my_apconfig.yaml seguest:  
```
On the KVM guest running in secure-execution mode, add the secret to the ultravisor.
Issue a command of the following form:
```
[se_guest]# pvsecret add <request_file>
```
For example, to use the add-secret request that was created in the previous steps, issue:
```
[se_guest]# pvsecret add my_addsecreq
```

Optionally list the secrets.

The pvsecret list command now displays the secret index and the secret ID.

For example:

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

0 Ap-Association:

546869732069732061207665727920736563726574207365637265742069642e

After all association secrets are added, you can prevent anyone from adding more secrets. To do this issue the pvsecret lock command.
After this command, the ultravisor rejects any further add-secret requests for your secure guest.
```
[se_guest]# pvsecret lock
```
Run the pvapconfig command with your .yaml configuration file as input.
The command now checks for AP queues that are available to the secure guest and that satisfy the specifications in the configuration file. The master key verification pattern assures that your guest is not presented with a tampered AP queue.
For example:
```
[se_guest]# pvapconfig my_apconfig.yaml
```
For details about the pvapconfig command, see pvapconfig - Implement an AP queue configuration.

Results

The ultravisor exclusively binds the AP queue to the secure guest. Other operating systems, including that of the KVM host, cannot access the AP queue or observe exchanges between the secure guest and the AP queue.

The ultravisor uses the secret to associate the secure guest with the AP queue. Only the secure guest that has created the secret can access the AP queue. Malicious peers cannot exploit a stolen secure key.

What to do next

You can automate steps 5 - 7 of the previous section by running the pvapconfig command with a policy that describes which association secrets shall be used with which APQN configurations. See Preventing the misuse of add-secret requests.