Dynamically adding and removing cryptographic adapters

6.10 LPAR mode z/VM guest KVM guest

You can add or remove cryptographic adapters from a running Linux® instance.

Before you begin

For z/VM® or KVM guests, your hypervisor version must support dynamic adding and removing of cryptographic adapters.

About this task

By default, the device driver scans the cryptographic configuration every 30 seconds. Newly detected cryptographic adapters are set online. If an adapter has disappeared, its associated cryptographic device is removed. Read or modify the expiration time of this rescan interval with the lszcrypt and chzcrypt commands.

Adding or removing of cryptographic adapters to or from an LPAR is transparent to applications that use clear key functions. If a cryptographic adapter is removed while cryptographic requests are being processed, zcrypt automatically resubmits lost requests to the remaining adapters. Special handling is required for secure key.

Secure key requests are submitted to a dedicated cryptographic coprocessor. If this coprocessor is removed or lost, new requests cannot be submitted to a different coprocessor. Therefore, dynamically adding and removing adapters with a secure key application requires support within the application. For more information about secure key cryptography, see Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294. You can obtain this book at https://www.ibm.com/docs/linuxonibm/liaaf/lnz_r_ccacnt.html.

Alternatively, you can read or set the configuration timer through the config_time sysfs attribute. This read-write attribute can be found at the AP bus level. Valid values for the config_time sysfs attribute are in the range 5 - 120 seconds.

For the secure key cryptographic functions on EP11 coprocessors, see Exploiting Enterprise PKCS #11 using openCryptoki, SC34-2713. You can obtain it at ibm.com/docs/en/linux-on-systems?topic=overview-exploiting-enterprise-pkcs-11-using-opencryptoki.

Procedure

You can work with cryptographic adapters in the following ways:

Add or remove cryptographic adapters by using the SE or HMC.
After the configuration timer expires, the cryptographic adapter is added to or removed from Linux, and the corresponding sysfs entries are created or deleted.
Enable or disable a cryptographic adapter by using the chzcrypt command.
The cryptographic adapter is only set online or offline in sysfs. The sysfs entries for the cryptographic adapter are retained. Use the lszcrypt command to check the results of the chzcrypt command.

Examples

To use the lszcrypt and chzcrypt commands to find out the current configuration timer setting, issue:
```
# lszcrypt -b
...
config_time=30 (seconds)
...
```
In the example, the timer is set to 30 seconds.
To set the configuration timer to 60 seconds, issue:
```
# chzcrypt -c 60
```

To use sysfs to find out the current configuration timer setting, issue:

To read the configuration timer setting, issue:
```
# cat  /sys/bus/ap/config_time
```
To set the configuration timer to 60 seconds, issue:
```
# echo 60 > /sys/bus/ap/config_time
```