Troubleshooting problems in your environment

Debugging zkey problems

If the zkey utility encounters an error, you can use the --verbose option of the utility to show additional messages.

Especially for the reencipher command of zkey, the --verbose option displays the CCA return and reason codes of the CSNBKTC (Key Token Change) verb used by zkey. CCA return and reason codes are documented in Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294.

For problems when working with EP11 AES secure keys, refer to Exploiting Enterprise PKCS #11 using openCryptoki.

Debugging zkey-cryptsetup problems

If the zkey-cryptsetup utility encounters an error, you can use the --verbose option or the --debug option of the utility to show additional messages. The --debug option also causes debug messages from libcryptsetup to be issued. The zkey-cryptsetup command uses the functions provided by cryptsetup.

Especially for the reencipher command of zkey-cryptsetup, the --verbose option displays the CCA return and reason codes of the CSNBKTC (Key Token Change) verb used by zkey-cryptsetup. CCA return and reason codes are documented in Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294.

For problems when working with EP11 AES secure keys, refer to Exploiting Enterprise PKCS #11 using openCryptoki.

Debugging cryptsetup problems

In case cryptsetup encounters an error, check the syslog for additional messages from the device mapper and dm-crypt.

In addition, use option --debug to see additional debugging messages. These messages show you where the error occurred and help you to find the reason of the failure.

The same debugging procedure is valid for problems with the cryptsetup-reencrypt command.

Debugging the pkey kernel module

The pkey driver uses the s390 debug feature. Usually the debugfs file system is mounted at /sys/kernel/debug and the cryptsetup driver appears as own directory at /sys/kernel/debug/s390dbf/pkey. By default the dbf level is set to 3 and all error messages within the driver are valued to 3 also. Thus any error message can be extracted as ASCII text by reading from the sprintf pseudo file:

# cat /sys/kernel/debug/s390dbf/pkey/sprintf 

In order to get debug messages, too, you can set the dbf level to 6:

# echo 6 >/sys/kernel/debug/s390dbf/pkey/level

Out-of-memory errors when opening a LUKS2 volume

You might encounter an out-of-memory error when opening a LUKS2 volume either during manual opening or during automated opening via /etc/crypttab at system startup. This is most probably caused by the fact that the LUKS2 format by default uses the Argon2i key derivation function, which is a so-called memory-hard function. It requires a certain amount of physical memory to make dictionary attacks more costly. To reduce the required amount of memory, the following steps can be helpful:

• Use LUKS2 with PBKDF2 instead of Argon2i as the key derivation function. Add the --pbkdf pbkdf2 option when using the luksFormat or luksAddKey commands.
• Decrease the amount of memory for Argon2i functions. For example, to use up to 256 KB, add the --pbkdf-memory 256 option to the luksFormat or luksAddKey commands.

Since the infrastructure for protected volume encryption uses secure keys as volume keys, the security of the key derivation function used to derive the key to encrypt the volume key in the LUKS key slots is of less relevance.

In order to check which key derivation function is used by an encrypted disk, use cryptsetup luksDump. It displays the key derivation function for each key slot. To change the key derivation function for an existing key slot, use cryptsetup luksConvertKey. Refer to the cryptsetup man page for more details.