lszcrypt - Display cryptographic devices

6.10 LPAR mode z/VM guest KVM guest

Use the lszcrypt command to display information about cryptographic devices that are managed by zcrypt and its AP bus attributes.

The following information can be displayed for each cryptographic device:

The card type
The status
- online: The card is online to Linux®.
- offline: The card is configured at the LPAR level, but set offline within Linux.
- deconfigured: The card is available to the LPAR, but not configured at the LPAR level. The card is also offline within Linux.
The hardware card type
The card capability
The hardware queue depth
The request count
The zcrypt submodule or alternative device driver that handles the device
For information about alternative device drivers, see Freeing AP queues for KVM guests.

The following AP bus attributes can be displayed:

The default AP domain
The configuration timer
The poll thread status
The poll timeout
The AP interrupt status

lszcrypt syntax

Where:

<device_ID>

specifies a cryptographic device to display. A cryptographic device can be either an adapter ID or an AP queue device. If no devices are specified, information about all available devices is displayed. Both the adapter ID representation and the AP queue device representation are hexadecimal.

-b or --bus

displays the AP bus attributes.

A list of AP bus features might be shown as four-letter abbreviations:

APSC - Extended TAPQ (Test AP Queue) support.
APXA - Support for more than 16 domains per card.
QACT - QACT support for toleration of new unknown crypto cards.
RC8A - Firmware reports 0x8A instead of 0x42 on some error conditions.
APSB - AP pass-through support for guests running in secure-execution mode.

-c <device_ID> or --capability <device_ID>

shows the capabilities of a cryptographic adapter. The capabilities depend on the card type and the installed function facilities. A cryptographic device can provide one or more of the following capabilities:

RSA 2K Clear Key
RSA 4K Clear Key
CCA Secure Key (full function set)
CCA Secure Key (restricted function set)
EP11 Secure Key
Long RNG

The restricted function set for CCA Secure Key applies to shared adapters for z/VM® guests.

For a card in EP11 mode, the state and verification pattern of the master wrapping key is shown.
For a card in CCA mode, the states and verification patterns of the AES, APKA and ASYM master keys are shown.
For KVM guests running in secure-execution mode, the AP queue bind and association state is shown.

-d or --domains

shows the usage and control domains of the cryptographic device. The displayed domains of the cryptographic device depends on the initial cryptographic configuration.

C indicates a control domain
U indicates a usage domain
B indicates both (control and usage domain)

-V or --verbose

enables the verbose level for cryptographic device information. It displays card type, online status, hardware card type, hardware queue depth, request count, pending request queue count, outstanding request queue count, and installed function facilities.

The installed functions are shown, as a sequence of letters, in the FUNCTION column of the verbose output mode, with the following meaning:

S: APSC facility available
M and C: RSA 4096 bit support
D: CCA Coprocessor function available
A: Accelerator function available
X: EP11 Coprocessor function available
N: APXA facility available
H: Hardware support for stateless filtering available
F: Full function set available
R: Restricted function set (only stateless)
Depending on the hypervisor configuration, the hypervisor might filter cryptographic requests to allow only a subset of functions within the virtual runtime environment. For example, a shared CCA Coprocessor can be restricted by the hypervisor to allow only clear-key operations within the guests.

--accelonly

limits the output to cryptographic adapters in accelerator mode.

--cardonly

limits the output to adapters only.

--ccaonly

limits the output to cryptographic adapters in CCA-Coprocessor mode.

--ep11only

limits the output to cryptographic adapters in EP11-Coprocessor mode.

--queueonly

limits the output to AP queues only.

-s or --serial

displays the serial numbers of CCA and EP11 cryptographic adapters.

-h or --help

displays help information for the command. To view the man page, enter man lszcrypt.

-v or --version

displays version information.

Examples

These examples illustrate common uses for lszcrypt.

To display information about all available cryptographic devices and AP queues:

# lszcrypt

This command lists all devices grouped by cryptographic device, similar to the following example. Card and domain IDs are hexadecimal values.


CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS
----------------------------------------------
0a          CEX7P EP11-Coproc online      2506
0a.0011     CEX7P EP11-Coproc online      1615
0a.0036     CEX7P EP11-Coproc online       891
0c          CEX7A Accelerator online      3506
0c.0011     CEX7A Accelerator online      1753
0c.0036     CEX7A Accelerator online      1753
0e          CEX7C CCA-Coproc  online      1507
0e.0011     CEX7C CCA-Coproc  online       753
0e.0036     CEX7C CCA-Coproc  online       754

To display AP bus information:

# lszcrypt -b

This command displays output similar to the following example:


features: APSC APXA QACT RC8A APSB
ap_domain=0x11
ap_max_domain_id=0x54
ap_interrupts are enabled
config_time=30 (seconds)
poll_thread is disabled
poll_timeout=250000 (nanoseconds)

To display the capabilities for the cryptographic device with adapter ID 0x0e:
```
# lszcrypt -c 0x0e
```
This command displays output similar to the following example:
```
card0e provides capability for:
RSA 4K Clear Key
CCA Secure Key (full function set)
Long RNG
```

To list the usage and control domains of the cryptographic devices:

# lszcrypt -d

This command displays a table that lists all domains (in hex notation) similar to the following example:


DOMAIN 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
------------------------------------------------------
    00  .  .  .  .  .  .  B  .  .  .  .  .  .  .  .  .
    10  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    20  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    30  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    40  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    50  .  B  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    60  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    70  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    80  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    90  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    a0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    b0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    c0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    d0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    e0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
    f0  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
------------------------------------------------------
C: Control domain 
U: Usage domain
B: Both (Control + Usage domain)

To display detailed information of all available cryptographic devices:

# lszcrypt -V

This example shows a CEX6S cryptographic device in accelerator mode (ID 0x03). It also shows three CEX7S devices, two of them in CCA coprocessor mode (IDs 0x08 and 0x0e) and one in EP11 coprocessor mode (ID 0x0a). The configured domains are 17 (0x0011) and 54 (0x0036). Adapter IDs and domain IDs are hexadecimal values.

# lszcrypt -V
CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS  DRIVER     
--------------------------------------------------------------------------------------------
03          CEX6A Accelerator online      2095       0     12     08 -MC-A-N-F-  cex4card   
03.0011     CEX6A Accelerator online      1047       0     12     08 -MC-A-N-F-  cex4queue  
03.0036     CEX6A Accelerator online      1048       0     12     08 -MC-A-N-F-  cex4queue  
08          CEX7C CCA-Coproc  online         0       0     13     08 S--D--N-F-  cex4card   
08.0011     CEX7C CCA-Coproc  -              0       0     13     08 S--D--N-F-  -no-driver-
08.0036     CEX7C CCA-Coproc  -              0       0     13     08 S--D--N-F-  -no-driver-
0a          CEX7P EP11-Coproc online      2506       0     13     08 -----XN-F-  cex4card   
0a.0011     CEX7P EP11-Coproc online      1615       0     13     08 -----XN-F-  cex4queue  
0a.0036     CEX7P EP11-Coproc online       891       0     13     08 -----XN-F-  cex4queue  
0e          CEX7C CCA-Coproc  online      1507       0     13     08 S--D--N-F-  cex4card   
0e.0011     CEX7C CCA-Coproc  online       753       0     13     08 S--D--N-F-  cex4queue  
0e.0036     CEX7C CCA-Coproc  online       754       0     13     08 S--D--N-F-  cex4queue

-no-driver- in the DRIVER column means that the AP queue has been freed for use by alternative device drivers, but no such device driver is available. In the example, the vfio_ap device driver is not loaded. Otherwise, vfio_ap would be displayed instead of -no-driver-.

In the example, all domains for adapter 0x08 have been freed from control by zcrypt. AP queues that are not handled by the zcrypt device driver are omitted from the non-verbose listing.

# lszcrypt
CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS
----------------------------------------------
03          CEX6A Accelerator online      2095
03.0011     CEX6A Accelerator online      1047
03.0036     CEX6A Accelerator online      1048
08          CEX7C CCA-Coproc  online         0
0a          CEX7P EP11-Coproc online      2506
0a.0011     CEX7P EP11-Coproc online      1615
0a.0036     CEX7P EP11-Coproc online       891
0e          CEX7C CCA-Coproc  online      1507
0e.0011     CEX7C CCA-Coproc  online       753
0e.0036     CEX7C CCA-Coproc  online       754

To limit the scope of the lszcrypt -V command, specify one or more device IDs as arguments to the command.

# lszcrypt -V 0x0a
CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER     
--------------------------------------------------------------------------------------------
0a          CEX7P EP11-Coproc online      2506        0     13     08 -----XN-F-  cex4card   
0a.0011     CEX7P EP11-Coproc online      1615        0     13     08 -----XN-F-  cex4queue  
0a.0036     CEX7P EP11-Coproc online       891        0     13     08 -----XN-F-  cex4queue

Tip: In the device specification, you can also use one-digit hexadecimal or decimal notation. The following specifications are all equivalent:

0x0 0x2 0xb
0x00 0x02 0x0b
0 2 11

To filter the output by adapter mode, for example, to list only adapters in CCA-Coprocessor mode, issue lszcrypt --ccaonly:

# lszcrypt --ccaonly
CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS
----------------------------------------------
04          CEX7A CCA-Coproc  online      2095
04.0016     CEX7A CCA-Coproc  online      1047
05          CEX7A CCA-Coproc  online      1048

To list only the adapters, issue lszcrypt -V --cardonly:

# lszcrypt -V --cardonly
CARD.DOMAIN TYPE  MODE         STATUS   REQUESTS   PENDING HWTYPE QDEPTH FUNCTIONS   DRIVER
---------------------------------------------------------------------------------------------
00          CEX7A Accelerator  online          0         0     13     08 -MC-A-N-F-  cex4card
01          CEX7A Accelerator  online          0         0     13     08 -MC-A-N-F-  cex4card
04          CEX7C CCA-Coproc   online          4         0     13     08 S--D--N-F-  cex4card
05          CEX7C CCA-Coproc   online          2         0     13     08 S--D--N-F-  cex4card
06          CEX7P EP11-Coproc  online          0         0     13     08 -----XN-F-  cex4card
07          CEX7P EP11-Coproc  online          0         0     13     08 -----XN-F-  cex4card
09          CEX7C CCA-Coproc   online          2         0     13     08 S--D--N-F-  cex4card

To list the AP queues, issue lszcrypt -V --queueonly:

# lszcrypt -V 0x0a
CARD.DOMAIN TYPE  MODE        STATUS  REQUESTS  PENDING HWTYPE QDEPTH FUNCTIONS  DRIVER     
--------------------------------------------------------------------------------------------
0a.0011     CEX7P EP11-Coproc online      1615        0     13     08 -----XNF-  cex4queue  
0a.0036     CEX7P EP11-Coproc online       891        0     13     08 -----XNF-  cex4queue

To display the serial number of adapters:

# lszcrypt --serial
CARD.DOM TYPE MODE         STATUS     SERIALNR
----------------------------------------------
04       CEX8C CCA-Coproc  online     93AADHR3
05       CEX8C CCA-Coproc  online     93AADHZV
06       CEX8P EP11-Coproc online     93AADFK7
0c       CEX7C CCA-Coproc  deconfig   -
0d       CEX7C CCA-Coproc  online     93AADEY1
0f       CEX7C CCA-Coproc  online     93AADEVV
17       CEX8P EP11-Coproc online     93AADH0C
1a       CEX7P EP11-Coproc online     93AADFAD