Binding and associating an EP11 adapter AP queue using the pvapconfig command

You can use the pvapconfig command to implement AP queue device configurations that are defined in a configuration YAML file to bind and associate an AP queue from a Crypto Express adapter configured as an Enterprise PKCS#11 coprocessor.

Use the pvapconfig command to automate the mapping of AP queues to association secrets. The command is also useful if many AP queues need to be configured.

About this task

IBM Secure Execution for Linux uses a special secret to associate a secure guest to an AP queue. The untrusted provider of the host environment configures the AP queue for the KVM guest, but cannot use it once it is associated with the secure guest.

For details of how to enhance the security of an add-secret request, see Preventing the misuse of add-secret requests.

For Crypto Express8S adapters in Enterprise PKCS #11 coprocessor mode, you need to bind and associate an AP queue with a secret.

The procedure that follows presents a simple example of binding an EP11 AP queue and associating it with a specific HSM master key, thus making it usable for the secure guest.

Note: The simple procedure does not ensure that the origin of the add-secret request is the current owner of the guest.

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:
```
[trusted]# pvsecret create -k <host_key_doc> --hdr <secure_exe_header> -o <request_file> \
--crt <CA_certificate> --crt <IBM_signing_certificate> association <name> \
--output-secret <association_secret>
```
The command uses the following options:
- 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 IBM Secure Execution 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 association parameter specifies a 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. Use the --input-secret option to create new add secret requests, for example after an update of the 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.