ZKEY-CRYPTSETUP(1)

💅 zkey-cryptsetup(1) 💅

🌸 NAME 🌸

zkey-cryptsetup — from the General Commands Manual, bestie — manages secure AES or HMAC volume keys of volumes encrypted with LUKS2 and the paes cipher, and optionally integrity protected with the phmac cipher. iconic key-management energy. 🔐✨

✨ SYNOPSIS ✨

zkey-cryptsetup command device [OPTIONS]

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

💖 DESCRIPTION 💖

okay so zkey-cryptsetup is your girl for validating and re-enciphering secure AES or HMAC volume keys. These are the secure 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. crypto adapter lore, but make it useful. 💅

To encrypt a volume using LUKS2 and the paes cipher, generate a secure AES key using zkey with 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 validate 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 applies 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. no adapter, no master-key tea to spill. ☕

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

--key-file|-d file-name — read the passphrase from this file instead of prompting you.
--keyfile-offset|-o bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--keyfile-size|-l bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--tries|-T number — how often a passphrase can be re-entered.
--verbose|-V — listed in the synopsis; this page doesn't add extra prose for it, so no invented details here.
--debug|-D — same vibe: it's in the synopsis, and this page gives no extra description for it.

🔁 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 reencipher 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. master key changed? bestie, that key needs a glow-up. 💅

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. they're chilling, no adapter involved. 🧚

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. two registers, not three — important. 👑

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. auto-detect is cute until the NEW register has no valid master key — then it's a fail. 😭

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. this is the “don't rawdog the CURRENT-to-NEW in-place case” warning, bestie. 💀

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

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. KDF tea: PBKDF2 here, Argon2i typical elsewhere, and PAES/PHMAC make the KDF security less relevant. 🍓

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 host library prerequisites, no skipping. ✨

--to-new|-N — re-encipher a secure key with the NEW master key before this key is made the CURRENT key.
--from-old|-O — re-encipher a secure volume key from the OLD register to the CURRENT register; only available for secure keys of type CCA-AESDATA or CCA-AESCIPHER.
--staged|-s — force a staged re-enciphering for the OLD to CURRENT case.
--in-place|-i — force an in-place re-enciphering for the CURRENT to NEW case.
--complete|-c — complete a staged re-enciphering after the new CCA or EP11 master key has been set; 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.
--key-file|-d file-name — read the passphrase from this file instead of prompting you.
--keyfile-offset|-o bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--keyfile-size|-l bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--tries|-T number — how often a passphrase can be re-entered.
--batch-mode|-q — listed in the synopsis for this command; this page doesn't add extra prose for it, so no invented behavior.
--verbose|-V — in the synopsis, no extra description on this page.
--debug|-D — also in the synopsis, also no extra description here.

🎀 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 setvp 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. verification pattern = the key's little ID bracelet in the LUKS2 header. 💅

Note: Set the verification pattern right after formatting the volume using cryptsetup luksFormat. right after formatting, bestie, not three business days later. ⏰

--key-file|-d file-name — read the passphrase from this file instead of prompting you.
--keyfile-offset|-o bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--keyfile-size|-l bytes — control which part of the key file is used as passphrase; behaves the same way as with cryptsetup.
--tries|-T number — how often a passphrase can be re-entered.
--verbose|-V — listed in the synopsis; this page doesn't add extra prose for it.
--debug|-D — in the synopsis too; no extra description here.

🌈 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 setkey 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. that's the “master key changed and nobody re-enciphered” recovery scenario. 😭

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. no copy in a file that was re-enciphered? then recovery is not happening, bestie. 💅

--volume-key-file|-m file-name — specify the secure key file and set this secure key as the new volume key.
--key-file|-d file-name — listed in the synopsis for this command; the page doesn't add extra prose for it here.
--keyfile-offset|-o bytes — listed in the synopsis for this command; no extra description on this page.
--keyfile-size|-l bytes — listed in the synopsis for this command; no extra description on this page.
--tries|-T number — listed in the synopsis for this command; no extra description on this page.
--batch-mode|-q — listed in the synopsis; this page doesn't spell out extra behavior for it.
--verbose|-V — in the synopsis, no extra description here.
--debug|-D — also in the synopsis, also no extra description here.

In case the LUKS2 header of the volume has a verification pattern token chillin' in it, that token gets used to make sure your new volume key actually contains the same effective key 💖. And if there's no verification pattern token available? Then you get prompted to confirm that the secure key you specified is the right one. ATTENTION: If you set a wrong secure key you will lose all the data on the encrypted volume! 😭 Like, literally all of it. No cap.

So to open a key slot inside the LUKS2 header of the volume, you need a passphrase — that's just how it is 🎀. You'll be prompted for it, unless you pass option --key-file. Option --tries controls how often a passphrase can be re-entered. When --key-file is specified, the passphrase gets read from the file you named 📄. You can also specify options --keyfile-offset and --keyfile-size to control exactly which part of the key file gets used as the passphrase. These options behave in the same way as with cryptsetup — iykyk 🫶.

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

🌈 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 so it uses 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, fr fr. Also the volume must not be open when a conversion is performed, otherwise it just 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 🙈. Like, please back it up bestie.

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 the volume key. You must then also specify the size of the secure HMAC key in bytes using the --integrity-key-size option. This then converts 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 — again, same energy 💅. You're 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 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, using 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, using the master key in the CURRENT register. Heads up: this option is only available for secure volume keys of type CCA-AESDATA or CCA-AESCIPHER 🫶.
-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. This option cannot be specified together with option --staged or --complete 💀.
-s, --staged — Forces the re-enciphering of a secure volume key in the LUKS2 header to be performed in staged mode. Staged mode means the re-enciphered secure volume key is stored in a separate (unbound) key slot in the LUKS2 header of the encrypted volume 🎀. So 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. This option cannot be specified together with option --in-place or --complete.
-c, --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 🧹. This option cannot be specified together with options --to-new, --from-old, --in-place, or --staged.
-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. Same vibe, different name 💅.
-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 the volume key for the converted volume 🔐.
--master-key-file file-name — Alias for the --volume-key-file file-name option. Again. Iconic of it 💖.
-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-name is - (a dash), then you're 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 🔑.

Okay so that's the whole page bestie, you made it to the end 🎉💖 big slay. This lil' beauty lives in s390-tools, dated February 2024, and it's the ZKEY-CRYPTSETUP(1) manual page — go forth and encipher responsibly ✨🫶

📦 where this page comes from

opensuse-leap 16.0: s390-tools 2.44.1-160000.1.1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

ZKEY-CRYPTSETUP(1)