LSZCRYPT(8)

📦 version 2.44.1, in opensuse-leap 16.0

💅 LSZCRYPT(8) — display zcrypt device and configuration information

Manual name for the group chat: lszcrypt, section 8, from the System Manager's Manual. Bestie, this is the page that shows you what zcrypt is doing with your cryptographic devices. 💖

✨ NAME ✨

lszcrypt — display zcrypt device and configuration information. 🎀

🛠️ SYNOPSIS 🛠️

lszcrypt [<filteroptions>] [-V] [ <device-id> [...]]

lszcrypt -c <device-id>

lszcrypt -b

lszcrypt -d

lszcrypt -h

lszcrypt -s

lszcrypt -v

<filteroptions>
         [--accelonly|--ccaonly|--ep11only] [--cardonly|--queueonly]

🌸 DESCRIPTION 🌸

Okay so the lszcrypt command is literally your little window into info about cryptographic devices managed by zcrypt, plus the AP bus attributes of zcrypt. The info it shows depends on your kernel version. Also, lszcrypt requires that sysfs is mounted — no sysfs, no slay. 🫶

For each cryptographic device, it can display:

  • 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
  • number of outstanding requests

And for the AP bus, it can display:

  • AP domain
  • Max AP domain
  • configuration timer
  • poll thread status
  • poll timeout
  • AP interrupt status

🎀 OPTIONS 🎀

  • -V, --verbose — the verbose level for cryptographic device information. With this verbose level, you get extra info like hardware card type, hardware queue depth, pending requests count, installed function facilities, and driver binding. It’s giving “tell me everything” energy. 👑
  • <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. 🔢
  • -b, --bus — displays the AP bus attributes and exits.

There is also a list of AP bus features shown here:

  • 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 bus has Secure Execution AP pass-through support.
  • -c, --capability <device-id> — shows the capabilities of a cryptographic card or queue device of hardware type 6 or higher. A card device id value may be given as decimal or hex value (with a leading 0x), a queue device needs to be given as xy.abcd (as it is displayed by lszcrypt). 🦋

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:

  • RSA 2K Clear Key
  • RSA 4K Clear Key
  • CCA Secure Key
  • EP11 Secure Key
  • Long RNG

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. 👀

The capabilities of a cryptographic queue device may vary depending on some state or environment. However if a queue device is given here, and the runtime environment is a KVM guest in Secure Execution mode with AP pass-through support, then the AP queue bind state and AP queue association state is shown here. Furthermore the state(s) and mkvp(s) (Master Key Verification Pattern) of the current master WK (Wrapping Key - EP11 mode) or current master AES, APKA and ASYM (CCA mode) are shown here.

  • -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.
    • C — indicate a control domain.
    • U — indicate a usage domain.
    • B — indicate both (control and usage domain).
  • -h, --help — displays help text and exits. The classic “help me help you” moment. 🙈
  • -s, --serial — shows the serial numbers for CCA and EP11 crypto cards. 🍓
  • -v, --version — displays version information and exits. 💅
  • --accelonly — show only information for cards/queues in Accelerator mode. 🔥
  • --ccaonly — show only information for cards/queues in CCA-Coprocessor mode.
  • --ep11only — show only information for cards/queues in EP11-Coprocessor mode.
  • --cardonly — show only information for cards but no queue info.
  • --queueonly — show only information for queues but no card info.

🔍 LISTING DETAILS 🔍

Here is an explanation of the columns displayed. Please note that some of the columns show up in verbose mode only. ✨

💠 CARD.DOM

The crypto card number in hexadecimal for a crypto card line, or the crypto card number and the domain id both in hex separated by a single dot for a queue line.

🦋 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, 13=CEX7 and 14=CEX8.

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.

🌈 MODE

A crypto card can be configured to run into one of 3 modes:

  • Accelerator — Acceleration of clear key RSA (CRT and ME) cryptographic operations.
  • CCA Coprocessor — Support CCA secure key cryptographic operations.
  • EP11 Coprocessor — Support EP11 secure key cryptographic operations.

⭐ STATUS

A crypto card and/or a crypto queue may be switched offline to prohibit its 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.

A crypto card can also be 'configured' or 'deconfigured'. This state may be adjusted on the HMC. The chzcrypt application can also trigger this state with the --config-on and --config-off options.

lszcrypt shows 'online' when a card or queue is available for cryptographic operations. 'offline' is displayed when a card or queue is switched to (software) offline. If a card is 'deconfigured' via HMC or chzcrypt the field shows 'deconfig'. A crypto card may also reach a 'checkstopped' state. lszcrypt shows this as 'chkstop'.

If a queue is not bound to a device driver there is no detailed information available and thus the status shows only '-'. If a queue is bound to the vfio-ap device driver it is up to this driver to give some status information and what exactly this means. So lszcrypt shows the text retrieved from the underlying sysfs attribute here.

🧚 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.

💜 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.

🔥 FUNCTIONS

This column shows firmware and hardware function details:

  • S — APSC available: card/queue can handle requests with the special bit enabled.
  • M — Accelerator card/queue with support for RSA ME with up to 4k key size.
  • C — Accelerator card/queue with support for RSA CRT with up to 4k key size.
  • D — Card/queue is providing CCA functions (this is the CCA Coprocessor mode).
  • A — Card/queue is providing Accelerator functions (this is the Accelerator mode).
  • X — Card/queue is providing EP11 functions (this is the EP11 Coprocessor mode).
  • N — APXA available (ability to address more than 16 crypto cards and domains).
  • H — Hardware support for stateless filtering available.
  • F — Full function support (opposed to restricted function support, see below).
  • 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.

👑 DRIVER

Shows which card or queue device driver currently handles this crypto resource. Currently known drivers are cex4card/cex4queue (CEX4-CEX8 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.

🫶 SESTAT

Shows the state of the BS bits associated with every AP queue within a Secure Execution guest when AP Pass-through support is available:

  • usable — AP queue is usable for crypto load.
  • bound — AP queue is bound but not yet associated.
  • unbound — AP queue is unbound and needs to get bound to this Secure Execution guest.
  • illicit — AP queue is not available for this Secure Execution guest.

📝 NOTES 📝

Use only one of the mode filtering options --accelonly, --ccaonly, --ep11only. Same with card/queue filtering: Use only one of --cardonly, --queueonly. However, one of the mode filtering options and one of the card/queue filtering can be combined. No cap, that’s the rule. 💅

🌸 EXAMPLES 🌸

Okay bestie, this is the part where it all comes together — here's how you actually use this thing 💅

  • lszcrypt — just the command, no args, no drama. It shows you the card/domain ID, the card type (that's the short name), the mode (that's the long name), the online status, and the request count for all the cryptographic devices that are available. Iconic little overview, honestly.
  • lszcrypt 1 3 5 — same info as above (card/domain ID, card type, mode, online status, request count) but only for cryptographic devices 1, 3, and 5. Picky and I respect it.
  • lszcrypt -V 3 7 11 — the extra-detailed vibe check ✨ This one gives you the card/domain ID, card type, mode, online status, request count, plus the number of requests in the hardware queue, the number of outstanding requests, and the installed function facilities — for cryptographic devices 3, 7 and 17 (0x11). Yes, 11 is 0x11, don't come for me, that's literally what the page says 🫶
  • lszcrypt 10.0038 — shows you info for the cryptographic device '10.0038', which is card id 16 (0x10) with domain 56 (0x38). The dot is doing the heavy lifting here, iykyk.
  • lszcrypt .0038 — the dot-first move 🎀 This one shows info for all the available queue devices (so potentially multiple adapters) that have domain 56 (0x38). More is more, lowkey.
  • lszcrypt -b — displays AP bus information. That's it, that's the whole thing.
  • lszcrypt -c 7 — and this one shows you what coprocessor card07 has going on, capability-wise:
CCA Secure Key
RSA 4K Clear Key
Long RNG

Look at card07 go 👑 three whole capabilities, we love a main character.

🦋 SEE ALSO 🦋

  • chzcrypt(8) — go say hi to its sibling, bestie 💖

That's the whole page, no crumbs left 🌈 — this beauty comes from the s390-tools crew, dated MAY 2023, and it lives at LSZCRYPT(8). Now go list some crypto devices, you absolute icon 💅✨

📦 where this page comes from