s390-tools/zconf/zcrypt/lszcrypt.8

.\" lszcrypt.8
.\"
.\" Copyright 2019 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.\" use
.\"   groff -man -Tutf8 lszcrypt.8
.\" or
.\"   nroff -man lszcrypt.8
.\" to process this source
.\"
.TH LSZCRYPT 8 "OCT 2020" "s390-tools"
.SH NAME
lszcrypt \- display zcrypt device and configuration information
.SH SYNOPSIS
.TP 9
.B lszcrypt
.RB "[ " -V " ] "
[
.I <device-id>
[...]]
.TP
.B lszcrypt
.B -c
<card-id>
.TP
.B lszcrypt -b
.TP
.B lszcrypt -d
.TP
.B lszcrypt -h
.TP
.B lszcrypt -v
.SH DESCRIPTION
The
.B lszcrypt
command is used to display information about cryptographic devices managed by
zcrypt and the AP bus attributes of zcrypt. Displayed information depends on the
kernel version.
.B lszcrypt
requires that sysfs is mounted.
.P
The following information can be displayed for each cryptographic
device: card ID, domain ID, card type (symbolic), mode, online status,
hardware card type (numeric), installed function facilities, card capability,
hardware queue depth, request count, number of requests in hardware queue, and
the number of outstanding requests.
The following AP bus attributes can be displayed: AP domain, Max AP domain,
configuration timer, poll thread status, poll timeout, and AP interrupt
status.
.SH OPTIONS
.TP 8
.B -V, --verbose
The verbose level for cryptographic device information.
With this verbose level additional information like hardware card type,
hardware queue depth, pending requests count, installed function
facilities and driver binding is displayed.
.TP 8
.B <device-id>
Specifies a cryptographic device to display. A cryptographic device can be
either a card device or a queue device. If no devices are specified information
about all available devices is displayed.
Please note that the card device representation and the queue device
are both in hexadecimal notation.
.TP 8
.B -b, --bus
Displays the AP bus attributes and exits.
.TP 8
.B -c, --capability <card-id>
Shows the capabilities of a cryptographic card device of hardware type 6 or
higher. The card device id value may be given as decimal or hex value (with
a leading 0x). The capabilities of a cryptographic card device depend on
the card type and the installed function facilities.  A cryptographic card
device can provide one or more of the following capabilities:
.RS
.IP "o" 3
RSA 2K Clear Key
.IP "o"
RSA 4K Clear Key
.IP "o"
CCA Secure Key
.IP "o"
EP11 Secure Key
.IP "o"
Long RNG
.RE

.RS 8
The CCA Secure Key capability may be limited by a hypervisor
layer. The remarks 'full function set' or 'restricted function set' may
reflect this. For details about these limitations please check the
hypervisor documentation.
.RE
.TP 8
.B -d, --domains
Shows the usage and control domains of the cryptographic devices.
The displayed domains of the cryptographic device depends on the initial
cryptographic configuration.
.RS
.IP "o" 3
C - indicate a control domain
.IP "o"
U - indicate a usage domain
.IP "o"
B - indicate both (control and usage domain)
.RE
.TP 8
.B -h, --help
Displays help text and exits.
.TP 8
.B -v, --version
Displays version information and exits.
.SH LISTING DETAILS
Here is an explanation of the columns displayed. Please note that some
of the columns show up in verbose mode only.
.TP
.B TYPE and HWTYPE
The HWTYPE is a numeric value showing which type of hardware the zcrypt
device driver presumes that this crypto card is. The currently known values
are 7=CEX3C, 8=CEX3A, 10=CEX4, 11=CEX5, 12=CEX6 and 13=CEX7.
.br
The TYPE is a human readable value showing the hardware type and the basic
function type (A=Accelerator, C=CCA Coprocessor, P=EP11 Coprocessor). So
for example CEX6P means a CEX6 card in EP11 Coprocessor mode.
.TP
.B MODE
A crypto card can be configured to run into one of 3 modes:
.br
Accelerator - Acceleration of clear key RSA (CRT and ME) cryptographic
operations.
.br
CCA Coprocessor - Support CCA secure key cryptographic operations.
.br
EP11 Coprocessor - Support EP11 secure key cryptographic operations.
.TP
.B STATUS
A crypto card and/or a crypto queue may be switched offline to
prohibit it's use. There are two levels of offline state. A software
online/offline state is kept by the zcrypt device driver and can be
switched on or off with the help of the chzcrypt application.
.br
A crypto card can also be 'configured' or 'deconfigured'. This state
may be adjusted on the HMC or SE. The chzcrypt application can also
trigger this state with the --config-on and --config-off options.
.br
lszcrypt shows 'online' when a card or queue is available for
cryptograhic operations. 'offline' is displayed when a card or queue
is switched to (software) offline. If a card is 'deconfigured' via
HMC, SE or chzcrypt the field shows 'deconfig'.
.TP
.B REQUESTS
This is the counter value of successful processed requests on card or queue
level. Successful here means the request was processed without any failure
in the whole processing chain.
.TP
.B PENDING
The underlying firmware and hardware layer usually provide some queuing
space for requests. When this queue is already filled up, the zcrypt device
driver maintains a software queue of pending requests. The sum of these
both values is displayed here and shows the amount of requests waiting for
processing on card or queue level.
.TP
.B FUNCTIONS
This column shows firmware and hardware function details:
.br
S - APSC available: card/queue can handle requests with the special bit
enabled.
.br
M - Accelerator card/queue with support for RSA ME with up to 4k key size.
.br
C - Accelerator card/queue with support for RSA CRT with up to 4k key size.
.br
D - Card/queue is providing CCA functions (this is the CCA Coprocessor mode).
.br
A - Card/queue is providing Accelerator functions (this is the Accelerator mode).
.br
X - Card/queue is providing EP11 functions (this is the EP11 Coprocessor mode).
.br
N - APXA available (ability to address more than 16 crypto cards and domains).
.br
F - Full function support (opposed to restricted function support, see below).
.br
R - Restricted function support. The F and R flag both reflect if a
hypervisor is somehow restricting this crypto resource in a virtual
environment. Dependent on the hypervisor configuration the crypto requests
may be filtered by the hypervisor to allow only a subset of functions
within the virtual runtime environment. For example a shared CCA
Coprocessor may be restricted by the hypervisor to allow only clear key
operations within the guests.
.TP
.B DRIVER
.br
Shows which card or queue device driver currently handles this crypto
resource. Currently known drivers are cex4card/cex4queue (CEX4-CEX7
hardware), cex2card/cex2cqueue (CEX2C and CEX3C hardware),
cex2acard/cex2aqueue (CEX2A and CEX3A hardware) and vfio_ap (queue reserved
for use by kvm hypervisor for kvm guests and not accessible to host
applications). It is also valid to have no driver handling a queue which is
shown as a -no-driver- entry.
.SH EXAMPLES
.TP
.B lszcrypt
Displays the card/domain ID, card type (short name), mode (long name), online
status and request count of all available cryptographic devices.
.TP
.B lszcrypt  1 3 5
Displays the card/domain ID, card type, mode, online status and request count
for cryptographic devices 1, 3, and 5.
.TP
.B lszcrypt -V 3 7 11
Displays the card/domain ID, card type, mode, online status, request count,
number of requests in the hardware queue, number of outstanding requests and
installed function facilities for cryptographic devices 3, 7 and 17 (0x11).
.TP
.B lszcrypt  10.0038
Displays information of the cryptographic device '10.0038' respectively card
id 16 (0x10) with domain 56 (0x38).
.TP
.B lszcrypt  .0038
Displays information of all available queue devices (potentially multiple
adapters) with domain 56 (0x38).
.TP
.B lszcrypt -b
Displays AP bus information.
.TP
.B lszcrypt -c 7
.RS
.br
Coprocessor card07 provides capability for:
.br
CCA Secure Key
.br
RSA 4K Clear Key
.br
Long RNG
.RE
.SH SEE ALSO
\fBchzcrypt\fR(8)