Creating customized device nodes

Red Hat Enterprise Linux 9.2 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, 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 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. You can use the hexadecimal domain IDs or their equivalent decimal values. Hexadecimal specifications must be prefixed with 0x.
Example:
```
# zcryptctl adddom 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

To create and define a zcrypt device node for CCA requests on adapters 0x05, 0x06, 0x07, 0x0a and domain 0x0006 using the zcryptctl command:

# zcryptctl create node_1
# zcryptctl addap node_1 0x05,0x06,0x07,0x0a
# zcryptctl adddom 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
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
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 +0x81 > /sys/devices/virtual/zcrypt/node_1/ioctlmask

The apmask and aqmask 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). 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>.