zcryptctl - Control access to AP queues and functions
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>
- removes the adapter from the allowed adapters list. The adapter argument is a number in the
range 0 - 255. Specify
ALL
to remove all adapters. - adddom <device_name> <domain_nr>
- adds a 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 domain from the specified device. Specify
ALL
to delete all domains. - addioctl<device_name> <ioctl_exp>
- adds an IOCTL. Specify the IOCTL as a symbolic string or the corresponding numeric value in the
range 0 - 255. Specify
ALL
to include all IOCTLs. The IOCTLs 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. Specify the IOCTL as a symbolic string or a 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 domain 81 of two
CCA adapters, 7 and
10.
You might have to change the access rights to the device before a container can use it.# zcryptctl new zcrypt_0 # zcryptctl addap zcrypt_0 7 # zcryptctl addap zcrypt_0 10 # zcryptctl adddom zcrypt_0 81 # zcryptctl addioctl zcrypt_0 ZSECSENDCPRB
- 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 zcdn node name: zcrypt_0 device node: /dev/zcrypt_0 major:minor: 250:0 ioctls: ZSECSENDCPRB adapter: 7,10 domains: 81 zcdn node name: zcrypt_1 device node: /dev/zcrypt_1 major:minor: 250:1 ioctls: ZSENDEP11CPRB adapter: 6,11 domains: 11
- 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 anothernode=
line encountered. For example, to create a device node calledzcdn_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
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:
The IOCTL macros, to be used as name, and their numbers are listed in arch/s390/include/uapi/asm/zcrypt.h.ioctls = ZSECSENDCPRB
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
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