ZKEY-CRYPTSETUP(1)

NAME
zkey-cryptsetup - Manage secure AES or HMAC volume keys of volumes encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac 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 or HMAC volume keys of volumes encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac cipher. These secure AES or HMAC 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 or HMAC 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 or HMAC volume key of a volume encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac 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. The same appplies to a secure integrity key, if present. For further information about master key registers, see the reencipher command. Keys of type PVSECRET-AES and PVSECRET-HMAC 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 or HMAC 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 or HMAC volume key of a volume encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac cipher. A secure AES or HMAC 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 and PVSECRET-HMAC 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, and optionally integrity protected with the phmac 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 or HMAC 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 and PHMAC uses secure AES or HMAC 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 or HMAC 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 or HMAC volume key of a volume encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac cipher. The verification pattern identifies the effective key used to encrypt or integrity protect 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 or HMAC 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, and optionally integrity protected with the phmac cipher. Use this command to recover from an invalid secure AES or HMAC volume key contained in the LUKS2 header. A secure AES or HMAC 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 or HMAC volume key
zkey-cryptsetup convert|conv device --volume-key-file|-m file-name [--integrity-key-size|-I bytes] [--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, optionally integrity protected with the phmac 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. When the volume uses integrity protection, and you want to also use a secure integrity key, then concatenate the secure AES encryption key and the secure HMAC key, and specify the result as volume key. You must then also specify the size of the secure HMAC key in bytes using the --integrity-key-size option. This will then convert the integrity algorithm to use the phmac cipher.

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

-N, --to-new
    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.

-O, --from-old
    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.

-i, --in-place
    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.

-s, --staged
    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.

-p, --complete
    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.

-q, --batch-mode
    Suppresses all confirmation questions. Use with care!

  Options for the setkey command

-m, --volume-key-file file-name
    Specifies the name of a file containing the secure AES key (and optionally a secure HMAC key) that is set as the new volume key.

--master-key-file file-name
    Alias for the --volume-key-file file-name option.

-q, --batch-mode
    Suppresses all confirmation questions. Use with care!

  Options for the convert command

-m, --volume-key-file file-name
    Specifies the name of a file containing the secure AES key that is used as volume key for the converted volume.

--master-key-file file-name
    Alias for the --volume-key-file file-name option.

-I, --integrity-key-size bytes
    Specifies the size of the secure HMAC key part in bytes.

-q, --batch-mode
    Suppresses all confirmation questions. Use with care!

  Options for supplying the passphrase

-d, --key-file file-name
    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.

-o, --keyfile-offset bytes
    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.

-l, --keyfile-size bytes
    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.

-T, --tries number
    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

-V, --verbose
    Displays additional information messages during processing.

-D, --debug
    Displays additional debugging messages during processing. This option also implies --verbose.

-h, --help
    Displays help text and exits.

-v, --version
    Displays version information and exits.

EXAMPLES

zkey-cryptsetup reencipher /dev/dasdd1
    Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1.

zkey-cryptsetup reencipher /dev/dasdd1 --staged
    Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in staged mode.

zkey-cryptsetup reencipher /dev/dasdd1 --complete
    Completes re-enciphers the secure volume key of the encrypted volume /dev/dasdd1.

zkey-cryptsetup reencipher /dev/dasdd1 --in-place
    Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in in-place mode.

zkey-cryptsetup validate /dev/dasdd1
    Validates the secure volume key of the encrypted volume /dev/dasdd1 and displays its attributes.

zkey-cryptsetup setvp /dev/dasdd1
    Sets the verification pattern of the secure volume key of the encrypted volume /dev/dasdd1.

zkey-cryptsetup setkey /dev/dasdd1 --volume-key-file seckey.key
    Sets the secure key contained in file seckey.key as the new volume key for the encrypted volume /dev/dasdd1.