Scroll to navigation

ZKEY-CRYPTSETUP(1) General Commands Manual ZKEY-CRYPTSETUP(1)

NAME

zkey-cryptsetup - Manage secure AES volume keys of volumes encrypted with LUKS2 and the paes cipher

SYNOPSIS

zkey-cryptsetup command device [OPTIONS]

zkey-cryptsetup [command] --help|-h
zkey-cryptsetup --version|-v

DESCRIPTION

Use zkey-cryptsetup to validate and re-encipher secure AES volume keys of volumes encrypted with LUKS2 and the paes cipher. These secure AES volume keys are enciphered with a master key of an IBM cryptographic adapter in CCA or EP11 coprocessor mode.

To encrypt a volume using LUKS2 and the paes cipher, generate a secure AES key using zkey: 'zkey generate luks.key --xts'. Then format the device with cryptsetup using the just generated secure AES key from file luks.key: 'cryptsetup luksFormat <device> --type luks2 --cipher paes-xts-plain64 --volume-key-file luks.key --key-size 1024'. For more details about zkey or cryptsetup see the corresponding man pages.

COMMANDS

Validate secure AES volume keys

zkey-cryptsetup validate|val device [--key-file|-d file-name] [--keyfile-offset|-o bytes] [--keyfile-size|-l bytes] [--tries|-T number] [--verbose|-V] [--debug|-D]

Use the validate command to validate a secure AES volume key of a 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 size, 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. For further information about master key registers, see the reencipher command. Keys of type PVSECRET-AES do not use a cryptographic adapter, thus no master key information is displayed for such keys.

To open a key slot contained in the LUKS2 header of the volume, 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.

Re-encipher secure AES volume keys

zkey-cryptsetup reencipher|re device [--to-new|-N] [--from-old|-O] [--staged|-s] [--in-place|-i] [--complete|-c] [--key-file|-d file-name] [--keyfile-offset|-o bytes] [--keyfile-size|-l bytes] [--tries|-T number] [--batch-mode|-q] [--verbose|-V] [--debug|-D]

Use the reencipher command to re-encipher a secure AES volume key of a volume encrypted with LUKS2 and the paes cipher. A secure AES volume key must be re-enciphered when the master key of the cryptographic adapter in CCA or EP11 coprocessor mode changes.

Volume keys of type PVSECRET-AES can not be re-enciphered. These keys do not use a cryptographic adapter, thus they do not need to be re-enciphered when the master key of a cryptographic adapter changes.

The cryptographic adapter in CCA coprocessor mode has three different registers to store master keys:

  • The CURRENT register contains the current master key.
  • The OLD register contains the previously used master key. Secure keys enciphered with the master key contained in the OLD register can still be used until the master key is changed again.
  • The NEW register contains the new master key to be set. The master key in the NEW register cannot be used until it is made the current master key. You can pro-actively re-encipher a secure key with the NEW master key before this key is made the CURRENT key. Use the --to-new option to do this.

Note: An EP11 cryptographic adapter has only two registers to store master keys, CURRENT and NEW.

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 the --from-old and --to-new options 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.

Re-enciphering a secure volume key of a volume encrypted with LUKS2 and the paes cipher can be performed in-place, or in staged mode.

"In-place" immediately replaces the secure volume key in the LUKS2 header of the encrypted volume with the re-enciphered secure volume key. Re-enciphering from OLD to CURRENT is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. Be aware that an encrypted volume with a secure volume key that was re-enciphered in-place from CURRENT to NEW is no longer usable, until the new CCA or EP11 master key has been made the current one.

Staged mode means that the re-enciphered secure volume key is stored in a separate (unbound) key slot in the LUKS2 header of the encrypted volume. Thus all key slots containing the current secure volume key are still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the reencipher command with option --complete to complete the staged re-enciphering. When completing the staged re-enciphering, the (unbound) key slot containing the re-enciphered secure volume key becomes the active key slot and, optionally, all key slots containing the old secure volume key are removed. Re-enciphering from CURRENT to NEW is performed in staged mode per default. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

To open a key slot contained in the LUKS2 header of the volume, 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.

The reencipher command creates a new key slot with the re-enciphered secure AES volume key. The new key slot uses PBKDF2 as password based key derivation function. LUKS2 volumes typically default to Argon2i as password based key derivation function, but this might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot 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.

Note: The reencipher command requires the CCA host library (libcsulcca.so) for secure volume keys of type CCA-AESDATA or CCA-AESCIPHER, or the IBM Z Enterprise PKCS #11 (EP11) Support Program (EP11 host library) for secure volume keys of type EP11-AES to be installed. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

Set a verification pattern of the secure AES volume key

zkey-cryptsetup setvp|setv device [--key-file|-d file-name] [--keyfile-offset|-o bytes] [--keyfile-size|-l bytes] [--tries|-T number] [--verbose|-V] [--debug|-D]

Use the setvp command to set a verification pattern of the secure AES volume key of a volume encrypted with LUKS2 and the paes cipher. The verification pattern identifies the effective key used to encrypt the volume's data. The verification pattern is stored in a token named paes-verification-pattern in the LUKS2 header.

Note: Set the verification pattern right after formatting the volume using 'cryptsetup luksFormat'.

To open a key slot contained in the LUKS2 header of the volume, 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.

Set a new secure AES volume key for a volume

zkey-cryptsetup setkey|setk device --volume-key-file|-m file-name [--key-file|-d file-name] [--keyfile-offset|-o bytes] [--keyfile-size|-l bytes] [--tries|-T number] [--batch-mode|-q] [--verbose|-V] [--debug|-D]

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

You can recover the secure volume key only if you have a copy of the secure key in a file, and this copy was re-enciphered when the CCA or EP11 master key has been changed. Thus, the copy of the secure key must be currently enciphered with the CCA or EP11 master key in the CURRENT or OLD master key register. Specify the secure key file with option --volume-key-file to set this secure key as the new volume key.

In case the LUKS2 header of the volume contains a verification pattern token, it is used to ensure that the new volume key contains the same effective key. If no verification pattern token is available, then you are prompted to confirm that the specified secure key is the correct one. ATTENTION: If you set a wrong secure key you will loose all the data on the encrypted volume!

To open a key slot contained in the LUKS2 header of the volume, 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 the same as with cryptsetup.

The setkey command creates a new key slot with the re-enciphered secure AES volume key. The new key slot uses PBKDF2 as password based key derivation function. LUKS2 volumes typically default to Argon2i as password based key derivation function, but this might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot 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.

Convert a clear-key LUKS2 volume to use a secure AES volume key

zkey-cryptsetup convert|conv device --volume-key-file|-m file-name [--key-file|-d file-name] [--keyfile-offset|-o bytes] [--keyfile-size|-l bytes] [--tries|-T number] [--batch-mode|-q] [--verbose|-V] [--debug|-D]

Use the convert command to convert a clear-key LUKS2 volume to use a secure volume key and the paes cipher. You must provide a secure volume key that uses the exact same effective key as the current volume key. The volume must not be open when a conversion is performed, otherwise it fails.

ATTENTION: It is strongly recommended to take a LUKS header backup using cryptsetup luksHeaderBackup before converting a volume. The volume might not be recoverable after a failing conversion, if you don't have a LUKS header backup.

Specify the secure key file with option --volume-key-file to convert the volume to use this secure key as the new volume key.

To open a key slot contained in the LUKS2 header of the volume, 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 the same as with cryptsetup.

The convert command creates a new key slot with the specified secure AES volume key. The new key slot uses the same password based key derivation function as the key slot that is used to open the volume. LUKS2 volumes typically default to Argon2i as password based key derivation function, but this might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot 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 to convert the key slot(s) to use PBKDF2 as password based key derivation function after the conversion.

OPTIONS

Options for the reencipher command

Re-enciphers a secure volume key in the LUKS2 header that is currently enciphered with the master key in the CURRENT register with the master key in the NEW register.
Re-enciphers a secure volume key in the LUKS2 header that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register.
Forces an in-place re-enciphering of a secure volume key in the LUKS2 header. This option immediately replaces the secure volume key in the LUKS2 header of the encrypted volume with the re-enciphered secure volume key. Re-enciphering from OLD to CURRENT is performed in-place per default.
Forces that the re-enciphering of a secure volume key in the LUKS2 header is performed in staged mode. Staged mode means that the re-enciphered secure volume key is stored in a separate (unbound) key slot in the LUKS2 header of the encrypted volume. Thus all key slots containing the current secure volume key are still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the reencipher command with option --complete to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default.
Completes a staged re-enciphering. Use this option after the new CCA or EP11 master key has been set (made active). When completing the staged re-enciphering, the (unbound) key slot containing the re-enciphered secure volume key becomes the active key slot and, optionally, all key slots containing the old secure volume key are removed.
Suppresses all confirmation questions. Use with care!

Options for the setkey command

Specifies the name of a file containing the secure AES key that is set as the new volume key.
Alias for the --volume-key-file file-name option.
Suppresses all confirmation questions. Use with care!

Options for the convert command

Specifies the name of a file containing the secure AES key that is used as volume key for the converted volume.
Alias for the --volume-key-file file-name option.
Suppresses all confirmation questions. Use with care!

Options for supplying the passphrase

Reads the passphrase from the specified file. If this option is omitted, or if the file-zkey-cryptsetup - (a dash), then you are prompted to enter the passphrase interactively.
Specifies the number of bytes to skip before starting to read in the file specified with option --key-file. If omitted, the file is read from the beginning. When option --key-file is not specified, this option is ignored.
Specifies the number of bytes to be read from the beginning of the file specified with option --key-file. If omitted, the file is read until the end. When --keyfile-offset is also specified, reading starts at the offset. When option --key-file is not specified, this option is ignored.
Specifies how often the interactive input of the passphrase can be re-entered. 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.

General options

Displays additional information messages during processing.
Displays additional debugging messages during processing. This option also implies --verbose.
Displays help text and exits.
Displays version information and exits.

EXAMPLES

Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1.
Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in staged mode.
Completes re-enciphers the secure volume key of the encrypted volume /dev/dasdd1.
Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in in-place mode.
Validates the secure volume key of the encrypted volume /dev/dasdd1 and displays its attributes.
Sets the verification pattern of the secure volume key of the encrypted volume /dev/dasdd1.
Sets the secure key contained in file seckey.key as the new volume key for the encrypted volume /dev/dasdd1.
February 2024 s390-tools