Verifying your configuration

Edit online

You can use several commands for verifying certain aspects of your pervasive encryption configuration.

Checking required kernel modules

Secure key volume encryption requires the pkey and paes_s390 kernel modules (see also Prerequisites).

For newer kernels, the monolithic pkey module is split into multiple sub modules.

To check if these kernel modules are loaded, use the lsmod command to see loaded modules, for example:

# lsmod | grep pkey
pkey_uv                16384  0
pkey_ep11              20480  0
pkey_cca               20480  0
pkey_pckmo             16384  0
zcrypt                135168  6 pkey_ep11,pkey_cca,zcrypt_cex4
pkey                   45056  6 pkey_pckmo,pkey_ep11,paes_s390,pkey_uv,pkey_cca

# lsmod | grep paes
paes_s390              36864  0
pkey                   45056  6 pkey_pckmo,pkey_ep11,paes_s390,pkey_uv,pkey_cca

For kernels before the split, you see only one pkey mode in the output. The individual pkey sub modules are normally automatically loaded as needed. Not all of them are required for all environments or use cases.

If the modules are not loaded, use the modprobe to load them, for example:

# modprobe pkey
# modprobe paes_s390

As the paes_s390 module requires the pkey module, pkey is also loaded together with the paes_s390 module by the shown command.

For more information, refer to Loading the device driver modules.

Checking available cryptographic coprocessors

Secure key volume encryption requires IBM® Crypto Express5S or Crypto Express6S adapters in CCA coprocessor mode (CEX5C or CEX6C) or Crypto Express7S adapters in EP11 mode (CEX7P).

Use the lszcrypt command to list the available cryptographic coprocessors:

# lszcrypt
CARD.DOMAIN TYPE  MODE        STATUS  REQUEST_CNT
-------------------------------------------------
02          CEX5A Accelerator online            0
02.004c     CEX5A Accelerator online            0
03          CEX5C CCA-Coproc  online        13000
03.004c     CEX5C CCA-Coproc  online        13000
05          CEX5P EP11-Coproc online        81213
05.004c     CEX5P EP11-Coproc online        81213

For more details, refer to chapter Generic cryptographic device driver in Device Drivers, Features, and Commands, SC33-8411.

Checking the default domain setting

Use the lszcrypt -b command to check that the ap_domain setting points to an existing domain, that is, the so-called default domain. If it is not pointing to an existing domain, use the chzcrypt --default-domain <domain> command to change it.

The default domain may be wrong if a system was booted with one or multiple APQNs available, and if then the default domain was detached or made unavailable by other means. The device driver keeps the default domain setting as is, even if the default domain is no longer existing. A system administrator must then change the default domain setting manually to point to an existing domain.

This can for example happen, when the cryptographic coprocessors of a z/VM® guest have been attached using the APVIRT operand and are now changed to be attached using the APDED operand. Cryptographic coprocessors attached using APVIRT appear as domain 0 in the z/VM guest while coprocessors attached using APDED appear as the original domain. As the original domain is typically different to domain 0, a domain change occurs and causes this situation. See Device Drivers, Features, and Commands for more information on how to change default domains.

Running with a default domain setting pointing to a non-existing domain will cause various errors. The ivp.e utility, which is part of the CCA package, will report 
!! no CEX*C found !!
The panel.exe utility, which is also part of the CCA package, may report 
FAIL: cannot get Serial Number [Error 12/338]

Obtaining the serial number from /sys/bus/ap/devices/card<num>/serialnr shows an empty serial number. Furthermore, cryptographic operations performed by the zkey utility may fail in various ways.