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 --master-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.

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.

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 --master-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 --master-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.

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, --master-key-file file-name
    Specifies the name of a file containing the secure AES key that is set as the new volume key.

-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-name is - (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 --master-key-file seckey.key
    Sets the secure key contained in file seckey.key as the new volume key for the encrypted volume /dev/dasdd1.