Binding an accelerator AP queue using the chzcrypt command

Edit online

To use a Crypto Express adapter in accelerator mode, you must bind an AP queue to the secure-execution guest. You can use the chzcrypt command with the --se-bind option to bind an accelerator AP queue to a secure-execution guest.

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

About this task

This example uses the chzcrypt and lszcrypt commands to bind 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
------------------------------------------------------------------------------------------------------
0f           CEX8A  Accelerator online        0       0     14     08 -MC-A-NF-   cex4card  -
0f.0014      CEX8A  Accelerator online        0       0     14     08 -MC-A-NF-   cex4queue unbound
```
AP queues that are available for binding are marked unbound.
SESTAT can show the following states:
- usable - the AP queue can be used for cryptographic requests.
- bound - the AP queue is bound but not associated.
- unbound - the AP queue is unbound and must be bound to this secure-execution guest to use it.
- illicit - the AP queue is not available for this secure-execution guest.
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 0f.0014 to the secure-execution guest, issue:
```
[secguest]: chzcrypt --se-bind 0f.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 usable.

For example:

[secguest]: lszcrypt -V
CARD.DOMAIN  TYPE   MODE        STATUS   REQ... PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER    SESTAT
--------------------------------------------------------------------------------------------------------
0f           CEX8A  Accelerator online        0       0     14     08 -MC-A-N-F-  cex4card  -
0f.0014      CEX8A  Accelerator online        0       0     14     08 -MC-A-N-F-  cex4queue usable

Results

After successfully binding an accelerator AP queue, you can use it to send requests and receive replies for clear 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 unbind the AP queue from the guest by using the chzcrypt command with the --se-unbind option.

For example, to unbind AP queue 0f.0014, issue:

[secguest]: chzcrypt --se-unbind 0f.0014