zcryptctl - Control access to AP queues and functions

Edit online

7.1 LPAR mode z/VM guest KVM guest

Use the zcryptctl command to control access to AP queues and functions.

For more information about cryptographic device nodes, see Creating customized device nodes.

zcryptctl syntax

Where:

list

lists all zcrypt device nodes.

create <node_name>

creates a new zcrypt device node. The <device_name> is optional and must be unique. If no node name is provided, the zcrypt device driver creates one with a name of the form: zcrypt_<n>, where <n> is the next free number. By default no adapter, domain, or IOCTL is allowed on the new device.

By default the device node file is created with permissions 0600 and might need adjustments to be usable by non-root users.

destroy <device_name>

destroys a zcrypt device. Marks the given zcrypt device as disposable. The device is removed when the use counter is zero.

addap <device_name> <adapter>

adds a cryptographic adapter to be accessible through this device. The adapter argument is a number in the range 0 - 255. Specify ALL to enable all adapters.

delap <device_name> <adapter>

deletes the adapter from the specified device. The adapter argument is a number in the range 0 - 255. Specify ALL to remove all adapters.

adddom <device_name> <domain_nr>

adds a usage domain to be accessible through the specified device. The domain argument is a number in the range 0 - 255. Specify ALL to enable all domains.

deldom <device_name> <domain_nr>

deletes a usage domain from the specified device. Specify ALL to delete all domains.

addctrl <device_name> <domain_nr>

adds a control domain to be accessible through the specified device. The domain argument is a number in the range 0 - 255. Specify ALL to add all domains as control domains.

delctrl <device_name> <domain_nr>

deletes a control domain from the specified device. Specify ALL to delete all control domains.

addioctl<device_name> <ioctl_exp>

adds an IOCTL to the functions supported by the specified device. Specify the IOCTL by its name or the corresponding numeric value in the range 0 - 255. Specify ALL to include all IOCTLs. The IOCTL macros, to be used as name, and their numbers are listed in arch/s390/include/uapi/asm/zcrypt.h.

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

delioctl <device_name> <ioctl_exp>

deletes the specified IOCTL from the functions supported by the specified device. Specify the IOCTL by its name or the corresponding numeric value in the range 0 - 255. Specify ALL to delete all IOCTLs.

config <config_file>

processes a configuration file.

listconfig

lists the current configuration in a format suitable for the config command.

Tip: Use listconfig to generate a configuration file that can be used as input to the config command.

Examples

These examples illustrate common uses for zcryptctl.

To set up a zcrypt device with access to secure key operations on two CCA adapters, 7 and 10 for domain 81, which is accessible as both a usage and a control domain.
```
# zcryptctl new zcrypt_0
# zcryptctl addap zcrypt_0 7
# zcryptctl addap zcrypt_0 10
# zcryptctl adddom zcrypt_0 81
# zcryptctl addctrl zcrypt_0 81
# zcryptctl addioctl zcrypt_0 ZSECSENDCPRB
```
You might have to change the access rights to the device before a container can use it.

To list the currently defined devices and their attributes:

# zcryptctl list
zcdn node name: zcrypt_2
   device node: /dev/zcrypt_2
   major:minor: 250:2
   ioctls: ICARSAMODEXPO,ICARSACRT,ZSECSENDCPRB
   adapter: 4,8,9
   domains: 6,11,81
   control domains:
zcdn node name: zcrypt_0
   device node: /dev/zcrypt_0
   major:minor: 250:0
   ioctls: ZSECSENDCPRB
   adapter: 7,10
   domains: 81
   control domains: 81
zcdn node name: zcrypt_1
   device node: /dev/zcrypt_1
   major:minor: 250:1
   ioctls: ZSECSENDCPRB
   adapter: 6,11
   domains: 11
   control domains:

To remove an obsolete device.
```
# zcryptctl destroy zcrypt_0
```

Creating a configuration file

The given configuration file is read line by line and the actions are executed. The syntax is as follows:

A node=<node_name> line creates a new device node with the given name. The subsequent actions act on this node until another node= line encountered. For example, to create a device node called zcdn_node_1:
```
node = zcdn_node_1
```
The aps=<list_of_ap_numbers> action adds allowed adapters to the node configuration. The adapters must be separated by space, tab, or commas. For example, to add adapters 1,2,5, and 7:
```
aps = 1, 2, 5, 7
```
The doms=<list_of_domain_numbers> action adds allowed domains to the node configuration. The domains must be separated by space, tab, or commas. For example, to allow domain 6:
```
doms = 6
```
The ctrls=<list_of_control_domain_numbers> action adds allowed control domains to the node configuration. The control domains must be separated by space, tab, or commas. For example, to allow domain 6 as a control domain:
```
crtls = 6
```
The ioctls=<list_of_ioctl_as_number_or_symbolic_name> adds allowed IOCTLs to the node configuration. The IOCTLs must be separated by space, tab, or commas. For example, to allow ZSECSENDCPRB:
```
ioctls = ZSECSENDCPRB
```
The IOCTL macros, to be used as name, and their numbers are listed in arch/s390/include/uapi/asm/zcrypt.h.

The symbol ALL is also recognized for the aps, doms and ioctls actions.

Empty lines are ignored and the number sign (#) marks the rest of the line as a comment. Each action must fit on one line, multiple lines is not supported. You can use more than one aps, doms, or ioctls line to customize the same node.

Example configuration file

##########################################
# Sample zcrypt device node configuration
##########################################
# node 1 for CCA requests on domain 6
node = zcdn_node_1
aps = 1, 2, 5, 7
doms = 6
crtls = 6
ioctls = ZSECSENDCPRB

# node 2 for CCA requests on domain 11
node = zcdn_node_2
aps = 1, 2, 5, 7
doms = 11
ioctls = ZSECSENDCPRB

# node 3 for EP11 on domain 6 and 11
node = zcdn_node_3
aps = 3, 6, 11
doms = 6, 11
ioctls = ZSENDEP11CPRB

# node 4 for clear key on everything
node = zcdn_node_4
aps = ALL
doms = ALL
ioctls = ICARSAMODEXPO, ICARSACRT, ZSECSENDCPRB

# node 5 special EP11 on adapter 10, any domain
node = zcdn_node_5
aps = 0x0a
doms = ALL
ioctls = ZSENDEP11CPRB

# node 6 special CCA only on adapter 7, domain 81
node = zcdn_node_6
aps = 7
doms = 0x51
ioctls = ZSECSENDCPRB

# node 7 for management of all HSM domains of CCA HSM 1
node = zcdn_node_7
aps = 1
doms = 1
ctrls = ALL
ioctls = ZSECSENDCPRB

Node 1 of the example can manage its usage domain, 6. Node 7 is an administrative node that can manage all domains that are available to the Linux® instance. Node 7 could use any domain as the required usage domain. The example uses domain 1.