Creating customized device nodes

6.18 LPAR mode z/VM guest KVM guest

The cryptographic device driver can provide and maintain multiple zcrypt device nodes. These nodes can be restricted in terms of cryptographic adapters, usage domains, control domains, and available IOCTLs.

About this task

You can create device nodes with access to a subset of the AP queues that are available to the Linux® instance and that can perform a subset of the functions. Such a device node can be used for access control to cryptographic resources:

Selective assignment of device nodes to Linux containers.
Linux file permissions for the device nodes can be used to restrict the access for users and groups.

Procedure

Create a new device node by issuing a zcryptctl command of this form:
```
# zcryptctl create <name>
```
where <name> is a unique device name. A device node /dev/<name> and a device directory /sys/devices/virtual/zcrypt/<name> are created in sysfs.
Example:
```
# zcryptctl create node_1
```
The example creates a device node /dev/node_1 and a device directory /sys/devices/virtual/zcrypt/node_1 in sysfs.
Set the adapters for the new device node. Issue a zcryptctl command of this form:
```
# zcryptctl addap <name> <adapter_id_1>,<adapter_id_2>,<adapter_id_3>,...
```
where <adapter_id_n> specifies an adapter to which you want this node to have access. You can use the hexadecimal adapter IDs or their equivalent decimal values. Hexadecimal specifications must be prefixed with 0x.
Example:
```
# zcryptctl addap node_1 0x05,0x06,0x07,0x0a
```
Using decimal notation this command would be:
```
# zcryptctl addap node_1 5,6,7,10
```
Set the usage domains for the new device node. Issue a zcryptctl command of this form:
```
# zcryptctl adddom <name> <dom_1>,<dom_2>,<dom_3>,...
```
where <dom_n> is a domain to which you want this node to have access as a usage domain. You can use the hexadecimal domain IDs or their equivalent decimal values. Hexadecimal specifications must be prefixed with 0x.
To process cryptographic requests or to manage control domains, a device node needs at least one usage domain.
Example:
```
# zcryptctl addcrtl node_1 0x0006
```
Set the control domains for the new device node. Issue a zcryptctl command of this form:
```
# zcryptctl addcrtl <name> <ctrl_1>,<ctrl_2>,<ctrl_3>,...
```
where <ctrl_n> is a domain to which you want this node to have access as a control domain. You can use the hexadecimal domain IDs or their equivalent decimal values. Hexadecimal specifications must be prefixed with 0x.
Interface change: As of kernel 5.18, only domains that are explicitly configured as control domains can be managed through the device node.
Example:
```
# zcryptctl addctrl node_1 0x0006
```

Set the IOCTLs for the new device node. Issue a zcryptctl command of this form:

# zcryptctl addioctl <name> <ioctl_1>,<ioctl_2>,<ioctl_3>,...

Set IOCTLs according to the functions you want to support. The following table lists the IOCTLs that are required by the CCA, EP11, and libica library.

Table 1. IOCTLs required by cryptographic libraries
Library	Functions	Required IOCTLs
CCA	Secure key cryptographic functions on CCA coprocessors.	ZSECSENDCPRB
EP11	Secure key cryptographic functions on EP11 coprocessors.	ZSENDEP11CPRB
libica	Clear key cryptographic functions.	ICARSAMODEXPO, ICARSACRT, ZSECSENDCPRB

The available IOCTLs are listed in arch/s390/include/uapi/asm/zcrypt.h in the Linux source tree.

Example:

# zcryptctl addioctl node_1 ZSECSENDCPRB

Optional: Secure the device node through suitable settings for the file owner and group, and through access permissions for user, group, and others.

Results

Changes to the masks are instantly applied and affect all applications with an open file descriptor for this zcrypt node immediately.

Example

The following command and configuration file examples create and define a zcrypt device node for CCA requests on adapters 0x05, 0x06, 0x07, 0x0a with domain 0x0006 as both a usage and control domain.

Using the zcryptctl command:

# zcryptctl create node_1
# zcryptctl addap node_1 0x05,0x06,0x07,0x0a
# zcryptctl adddom node_1 0x0006
# zcryptctl addcrtl node_1 0x0006
# zcryptctl adioctl node_1 ZSECSENDCPRB

It is equivalent to using the zcryptctl config command with the following configuration file entry:

# node 1 for CCA requests on domain 6 - hexadecimal notation
node = node_1
aps = 0x05,0x06,0x07,0x0a
doms = 0x0006
crtls = 0x0006
ioctls = ZSECSENDCPRB

The following equivalent configuration file uses decimal notation for adapters and domains:

# node 1 for CCA requests on domain 6 - decimal notation
node = node_1
aps = 5,6,7,10
doms = 6
crtls = 6
ioctls = ZSECSENDCPRB

Alternatively, you can use sysfs attributes to obtain the same results:

# echo node_1 > /sys/class/zcrypt/create
# echo +0x05,+0x06,+0x07,+0x0a > /sys/devices/virtual/zcrypt/node_1/apmask
# echo +0x0006 > /sys/devices/virtual/zcrypt/node_1/aqmask
# echo +0x0006 > /sys/devices/virtual/zcrypt/node_1/admask
# echo +0x81 > /sys/devices/virtual/zcrypt/node_1/ioctlmask

The apmask, aqmask, and admask attributes in the node directory follow the same syntax as the apmask and aqmask attributes at /sys/bus/ap (see Freeing AP queues for KVM guests). The admask attribute, which specifies the control domains for the device node, does not have an equivalent at /sys/bus/ap.

Relative values require a plus (+) or minus (-) prefix, can use decimal or hexadecimal notation, and can address individual bits or ranges. You can also specify the complete hexadecimal mask as an absolute value. The sysfs interface requires numeric values for the IOCTLs as listed in arch/s390/include/uapi/asm/zcrypt.h.

What to do next

You can delete the device node with zcryptctl destroy <name>.