zkey-cryptsetup - Managing LUKS2 volume keys

Edit online

Use the zkey-cryptsetup command to validate and re-encipher secure AES keys of volumes encrypted with LUKS2 and the PAES cipher.

These secure AES keys are enciphered with a master key of an IBM® cryptographic coprocessor in CCA coprocessor mode or EP11 coprocessor mode.

Prerequisites

The zkey-cryptsetup reencipher command requires the CCA host library (libcsulcca.so) and tools package to be installed for secure volume keys of type CCA-AESDATA or CCA-AESCIPHER. It requires the Linux® on Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) for secure volume keys of type EP11-AES to be installed.
To download the required packages, go to www.ibm.com/security/cryptocards and proceed to the software download page for your IBM cryptographic coprocessor version.
The zkey-cryptsetup command requires the libcryptsetup library that comes as part of the cryptsetup package. You require cryptsetup version 2.0.3 or newer available from https://gitlab.com/cryptsetup/cryptsetup/.
The zkey-cryptsetup command also requires the pkey kernel module. For more information, see chapter Protected key device driver in Device Drivers, Features, and Commands, SC33-8411 available on the IBM Knowledge Center at www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_lib.html.
You must have at least one IBM Crypto Express adapter configured as a CCA coprocessor or configured as an EP11 coprocessor with an AES master key properly set up.

When you open a key slot contained in the LUKS2 header of the volume using zkey-cryptsetup, a passphrase is required. You are prompted for the passphrase, unless option --key-file is specified. Option --tries specifies how often a passphrase can be re-entered. When option --key-file is specified, the passphrase is read from the specified file. You can specify options --keyfile-offset and --keyfile-size to control which part of the key file is used as passphrase. These options behave in the same way as with cryptsetup.

zkey-cryptsetup syntax

Figure 1. zkey-cryptsetup syntax

where:

val or validate

validates a secure AES key of the specified volume encrypted with LUKS2 and the PAES cipher. It checks if the LUKS2 header of the volume contains a valid secure key. It also displays the attributes of the secure key, such as key sizes, whether it is a secure key that can be used for the XTS cipher mode, and the master key register (CURRENT or OLD) with which the secure key is enciphered.

re or reencipher

re-enciphers an existing secure key of the specified volume with a new master key. A secure key must be re-enciphered when the master key of the CCA CCA coprocessor changes.

-N or --to-new

The NEW register of a cryptographic coprocessor contains a new master key to be set. The master key in the NEW register cannot be used until it is made the current master key. Use the --to-new option to pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key.

-O or --from-old

Use the --from-old option to re-encipher a secure volume key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register. This option is only available for secure keys of type CCA-AESDATA or CCA-AESCIPHER.

If both options --from-old and --to-new are specified, a secure volume key that is currently enciphered with the master key in the OLD register is re-enciphered with the master key in the NEW register.

If both options are omitted, zkey-cryptsetup automatically detects whether the secure volume key is currently enciphered with the master key in the OLD register or with the master key in the CURRENT register. If currently enciphered with the master key in the OLD register, it is re-enciphered with the master key in the CURRENT register. If it is currently enciphered with the master key in the CURRENT register, it is re-enciphered with the master key in the NEW register. If for this case the NEW register does not contain a valid master key, then the re- encipher operation fails.

-i or --in-place

forces an in-place re-enciphering. This is the default for OLD to CURRENT.

-s or --staged

stores the key in a file <key-name>.renc in the repository. The key in <key-name>.skey is still valid. Once a new CCA master key has been set, you need to rerun the reencipher command with option --complete. This copies the file <key-name>.renc to <key-name>.skey and thus completes the staged re-enciphering. Re-enciphering from CURRENT to NEW is by default done in staged mode.

-c or --complete

completes a staged re-enciphering.

setv or setvp

sets a verification pattern of the secure AES key of a volume encrypted with LUKS2 and the PAES cipher. The verification pattern identifies the effective key used to encrypt the data on the volume. The verification pattern is stored in a token in the LUKS2 header.

setk or setkey

sets a new secure AES key for a volume encrypted with LUKS2 and the PAES cipher. Use this command to recover from an invalid secure AES key contained in the LUKS2 header. A secure AES key contained in the LUKS2 header can become invalid when the CCA master key is changed without re-enciphering the secure volume key.

convert or conv device

converts a clear-key LUKS2 volume to use a secure volume key or a retrievable secret key and the PAES cipher.

You must provide a secure volume key or a retrievable secret key that uses exactly the same effective key as the current volume key. The volume must not be open when a conversion is performed, otherwise the conversion fails.

The convert subcommand creates a new key slot with the specified secure AES volume key or retrievable secret key. The new key slot uses the same password-based key derivation function (PBKDF) as the key slot that is used to open the volume. LUKS2 volumes typically default to Argon2i as PBKDF, but this may cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot time through /etc/crypttab. Because PAES uses secure AES keys as volume keys, the security of the key derivation function used to encrypt the volume key in the LUKS key slots is of less relevance.

Use cryptsetup luksConvertKey -pbkdf pbkdf2 or --pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4 to convert the key slot(s) and to use the specified function as password-based key derivation function after the conversion.

--volume-key-file <secure_key_file> | --master-key-file <secure_key_file> | -m <secure_key_file>

Specifies the name of a file containing the secure AES key or retrievable secret key that is set as the new volume key.

--key-file or -d

Optional. To open a key slot contained in the LUKS2 header of the volume, a passphrase is required. This option reads the passphrase from the file specified with parameter key_file_name. If this option is omitted, no passphrase is set, or if this parameter contains a - (a dash) as input, you are prompted to enter the passphrase interactively.

-q or --batch-mode

Optional. This option is passed to the generated commands. It suppresses all confirmation questions. These are assumed to be answered with YES. This enables a better automation of zkey-cryptsetup commands.

-o <bytes> or --keyfile-offset <bytes>

Optional. Specifies the number of bytes to skip in the file specified with the --key-file option. When not specified, the file is read from the beginning. If the --key-file option is not specified, this option is ignored.

-l <bytes> or --keyfile-size <bytes>

Optional. Specifies the number of bytes to read from the file specified with option --key-file. When not specified, the file is read until the end. When option --key-file is not specified, this option is ignored.

-T <number> or --tries <number>

Optional. Specifies how often the interactive input of the passphrase can be retried. The default is 3 times. When option --key-file is specified, this option is ignored, and the passphrase is read only once from the file.

-D or --debug

Displays additional debugging messages during processing. This option implies --verbose.

-V or --verbose

Displays additional information during processing.

Examples

To re-encipher the secure key of the encrypted volume /dev/mapper/disk1 :
```
zkey-cryptsetup reencipher /dev/mapper/disk1
```
To re-encipher the secure key of the encrypted volume /dev/mapper/disk1 in staged mode:
```
zkey-cryptsetup reencipher /dev/mapper/disk1 --staged
```
To complete re-enciphering the secure key of the encrypted volume /dev/mapper/disk1:
```
zkey-cryptsetup reencipher /dev/mapper/disk1 --complete
```
To re-encipher the secure key of the encrypted volume /dev/mapper/disk1 in in-place mode:
```
zkey-cryptsetup reencipher /dev/mapper/disk1 --in-place
 
```
To re-encipher the secure key of the encrypted volume /dev/mapper/disk1 that is currently enciphered with the master key in the OLD register with the master key in the NEW register:
```
zkey-cryptsetup reencipher /dev/mapper/disk1 --from-old --to-new
 
```
To validate the secure key of the encrypted volume /dev/mapper/disk1 and display its attributes:
```
zkey-cryptsetup validate /dev/mapper/disk1
```
To set the verification pattern of the secure key of the encrypted volume /dev/mapper/disk1:
```
zkey-cryptsetup setvp /dev/mapper/disk1
```
To set the secure key contained in file seckey.key as the new key for the encrypted volume /dev/mapper/disk1:
```
zkey-cryptsetup setkey /dev/mapper/disk1 --master-key-file  seckey.key 
 
```