ZCRYPTCTL(8)

🎀 ZCRYPTCTL(8) 🎀

okay bestie, welcome to the System Manager's Manual page for zcryptctl — the command that displays information and administrates zcrypt multiple device nodes. We're keeping every flag, every path, and every ✨ caveat, no cap. 💖

✨ NAME ✨

zcryptctl — display information and administrate zcrypt multiple device nodes. 💅

🦋 SYNOPSIS 🦋

zcryptctl list

zcryptctl create [node-name]
zcryptctl destroy node-name

zcryptctl addap node-name adapter-nr
zcryptctl delap node-name adapter-nr

zcryptctl adddom node-name domain-nr
zcryptctl deldom node-name domain-nr

zcryptctl addctrl node-name domain-nr
zcryptctl delctrl node-name domain-nr

zcryptctl addioctl node-name ioctl-term
zcryptctl delioctl node-name ioctl-term

zcryptctl config config-file

zcryptctl listconfig

🌸 DESCRIPTION 🌸

The zcryptctl command displays information and maintains the multi device node extension for the zcrypt device driver. ✨

With the multi device node extension you can create and configure additional zcrypt device nodes which can be used as alternate device nodes to access the crypto hardware provided by the zcrypt device driver. Each zcrypt device node can be restricted in terms of crypto cards, domains, and available ioctls. Such a device node can be used as a base for container solutions like Docker to control and restrict the access to crypto resources. See the NOTES section below for information on control domains. 🫶

👑 COMMANDS 👑

• zcryptctl list — show all the additional device nodes that are currently active. 👀
• zcryptctl create — create a new zcrypt device node. node-name might be given, and it needs to be unique and not in use. If there is no node name provided, the zcrypt device driver will create a new one with the pattern zcrypt_x, with x being the next free number. Up to 256 additional device nodes can be created. The newly created additional device node appears in /dev and has read and write permissions enabled only for root. By default, all adapters, domains, and ioctls are initially disabled on this new device node. 🎀
• zcryptctl destroy node-name — destroy an additional zcrypt device node. The device node is only marked for disposal and destroyed when it is no longer used. 💀
• zcryptctl addap / zcryptctl delap — update the filter for the specified zcrypt device node and add or delete a crypto adapter to be accessible via this node, using node-name and adapter-nr. The symbol ALL can be used to enable or disable all adapters. 🔥
• zcryptctl adddom / zcryptctl deldom — update the filter for the specified zcrypt device node and add or delete a domain to be accessible through this node, using node-name and domain-nr. The symbol ALL can be used to enable or disable all domains. 🌈
• zcryptctl addctrl / zcryptctl delctrl — update the filter for the specified zcrypt device node and add or delete a control domain to be accessible through this node, using node-name and domain-nr. The symbol ALL can be used to enable or disable all domains. 👑
• zcryptctl addioctl / zcryptctl delioctl — update the filter for the specified zcrypt device node and add or delete an ioctl, using node-name and ioctl-term. The ioctl might be specified as a symbolic string — one of ICARSAMODEXPO, ICARSACRT, ZSECSENDCPRB, ZSENDEP11CPRB, ZCRYPT_DEVICE_STATUS, ZCRYPT_STATUS_MASK, ZCRYPT_QDEPTH_MASK, ZCRYPT_PERDEV_REQCNT — or as a numeric value in the range 0-255, and the symbol ALL can be used to include all ioctls. 🦋
• zcryptctl config config-file — process a config file. The given configuration file is read line by line and the settings are applied. Syntax is simple:

node=<node-name>

aps=<list of ap numbers separated by space, tab or ','>

doms=<list of domain numbers separated by space, tab or ','>

ctrls=<list of control domain numbers separated by space, tab or ','>

ioctls=<list of ioctl as numeric or symbolic number separated by space, tab or ','>

Empty lines are ignored and the # marks the rest of the line as a comment.

The node= line creates a new zcrypt device node, the aps=, doms=, ctrls= and ioctls= lines customize the previously created node. The symbol ALL is also recognized for aps, doms, and ioctls.

Each action must fit into one line, spreading over multiple lines is not supported. But you can use more than one aps=, doms=, ctrls= and ioctls= lines to customize the very same node.

Processing stops when a line cannot be parsed or the current action fails. In this case the exit status is non zero but the successful actions until the failure occurs are not rolled back. 😭

• zcryptctl listconfig — list the current configuration in a form suitable for input to the zcryptctl config command. 📝

🧚 NOTES 🧚

Control domain filtering is only supported for custom device <nodename> if the admask file in sysfs under /sys/class/zcrypt/<nodename>/admask exists. If this file does not exist, the kernel is too old and does not support control command filtering. This is the same effect as setting the control domain mask to ALL. Note that, even though you can allow more than available to the system, you can only send control commands to control domains available to the system. ⚠️

💜 EXIT STATUS 💜

On successful completion of the command the exit status is 0. A non zero return code (and some kind of failure message) is emitted if the processing could not complete successful. 😭

⭐ SEE ALSO ⭐

• lszcrypt(8)

---

mwah 💋 this iconic page comes from s390-tools, dated JAN 2022, and it's the ZCRYPTCTL(8) manual. bye bestie, go restrict some crypto resources responsibly 🫶✨