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

To use a Crypto Express adapter in Enterprise PKCS #11 coprocessor mode, you must first bind an AP queue to the guest, verify the master key verification pattern of the AP queue, and then associate the AP queue with an association secret. You can use the chzcrypt command to bind an AP queue from a Crypto Express adapter configured as an EP11 coprocessor to a secure-execution guest, and associate the AP queue with a secret.

Alternatively you can use the pvapconfig command to bind and associate AP queues.

Before you begin

To use a Crypto Express adapter in Enterprise PKCS #11 coprocessor mode, you need an HSM with your HSM master key. Setting an HSM master key is a sensitive task that is performed by an HSM domain administrator, who can be yourself or a trusted agent. However, it is not necessary to set the HSM master key before the guests starts. It is possible to set it using a secure guest that runs an ep11TKEd.

About this task

This example uses the chzcrypt and lszcrypt commands to bind and associate an AP queue. For an alternative, see pvapconfig - Implement an AP queue configuration.

Procedure

Optionally, on the secure-execution guest, list the available AP queues.

Use the lszcrypt command with the -V option to see AP queues listed under SESTAT.

For example:

[secguest]: lszcrypt -V
CARD.DOMAIN  TYPE   MODE        STATUS  REQ... PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER     SESTAT
--------------------------------------------------------------------------------------------------------
28           CEX8P  EP11-Coproc online       0       0     14     08 -----XN-F-  cex4card   -
28.0014      CEX8P  EP11-Coproc online       0       0     14     08 -----XN-F-  cex4queue  unbound

AP queues that are available for binding are marked unbound.

To bind an AP queue to the guest, issue a command of the following form:
```
[secguest]: chzcrypt --se-bind <aa.dddd>
```
where <aa> is the adapter ID of the cryptographic device and <dddd> is the domain.
For example, to bind the unbound AP queue 28.0014 to the secure-execution guest, issue:
```
[secguest]: chzcrypt --se-bind 28.0014
```

Optionally confirm that the AP queue is now bound and usable.

Use the lszcrypt command again to check that the status of the AP queue is now bound.

For example:

[secguest]# lszcrypt -V
CARD.DOMAIN  TYPE   MODE        STATUS  REQ... PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER     SESTAT
--------------------------------------------------------------------------------------------------------
28           CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4card   -
28.0014      CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4queue  bound

Create an add-secret request.
On a trusted Linux instance, issue a pvsecret create command to create the request for adding a 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 <string> 
```
The command uses the following parameters:
- The -k parameter 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 parameter specifies the IBM Secure Execution header of the secure image, or the IBM Secure Execution image itself.
- The -o parameter specifies the output file for the request. Use the association parameter for a phrase that names the secret. The command creates these output files:
  - The request.
  - A .yaml file with a secret ID.
- Two --crt parameters specify the IBM Z signing key and the CA certificate to establish the chain of trust.
For example, to use a host-key document z16.crt, a guest header se.hdr, a CA certificate DigiCert.crt, and an IBM signing key ibm-sign.crt, issue the following command on a trusted system:
```
# pvsecret create -k z16.crt --se-hdr se.hdr -o addSecretReq \
--crt DigiCertCA.crt --crt ibm-sign.crt association "my secret"
```
The command creates:
- An add-secret request and writes it to addSecretReq.
- An identifier for the request, consisting of a hash of the given string my secret, and writes it to addSecretReq.
For details about the pvsecret create command, see pvsecret create.
Optional: Verify the add-secret request. If you did not create the request yourself, you might want to verify it.
Assuming that you want to accept only signed add-secret requests, you must verify that the add-secret request is signed by a valid origin, represented by the origin's certificate. For example, to verify that the request addSecretReq was signed with the private key that corresponds to the certificate myCert.pem, issue:
```
[secguest]# pvsecret verify --user-cert myCert.pem -o user_data_out addSecretReq
```
Add the secret to the ultravisor only if the verification is successful.
Add the secret to the ultravisor.
Assume that you created an add-secret request with the pvsecret create command, and the request was saved to addSecretReq
On the guest, issue the following command:
```
[secguest]# pvsecret add addSecretReq
```
List the secrets in the ultravisor to find the index of the secret you want.
Use pvsecret list to list the secrets.
For example:
```
[secguest]# pvsecret list
Total number of secrets: 1

0 Ap-Association:
  546869732069732061207665727920736563726574207365637265742069642e  
```
The secret that was added has index 0. You can add more secrets to associate up to 12 AP queues with the guest.
Verify the master key verification patterns (MKVP) of the AP queue.
Check whether the APQN is configured with the expected MKVP. Check the MKVP by reading the mkvps sysfs attribute of a domain:
```
# cat /sys/bus/ap/devices/<aa.dddd>/mkvps
```
Use the chzcrypt --se-associate command to associate one AP queue with one secret.
Issue a command of the following form:
```
# chzcrypt --se-associate <secret_index> <aa.dddd>
```
For example, to associate the secret with index 0 and AP queue 28.0014:
```
[secguest]: chzcrypt --se-associate 0 28.0014
```
The chzcrypt --se-associate command might take a small amount of time to complete.

Optionally confirm that the AP queue is now usable with the lszcrypt command.

For example:

[secguest]: lszcrypt -V
CARD.DOMAIN  TYPE   MODE        STATUS  REQ... PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER     SESTAT
--------------------------------------------------------------------------------------------------------
28           CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4card   -
28.0014      CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4queue  usable

Results

After successfully binding and associating an AP queue, you can use it to send requests and receive replies for secure key cryptography. The AP queue is now exclusively available to the secure guest. Other operating systems, including that of the KVM host, cannot access the AP queue. However, the KVM host can, when needed, reset the cryptographic resource. As a result, the AP queue is unbound in the secure guest, which leads to failures of further cryptographic requests from the secure guest.

What to do next

You can disassociate and unbind an AP queue from a guest by using the chzcrypt command with the --se-unbind option.

For example:

[secguest]: chzcrypt --se-unbind 0 28.0014

The command results in the AP queue being unbound, which you can see by displaying it's SESTAT attribute with the lszcrypt command:

[secguest]: lszcrypt -V
CARD.DOMAIN  TYPE   MODE        STATUS  REQ... PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER     SESTAT
--------------------------------------------------------------------------------------------------------
28           CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4card   -
28.0014      CEX8A  Accelerator online       0       0     14     08 -----XN-F-  cex4queue  unbound