ZKEY(1)

🌸 NAME 🌸

zkey — Manage secure AES or HMAC keys. And yes bestie, this page is from the General Commands Manual; we're just making it cute.

✨ SYNOPSIS ✨

The whole shape of it is:

zkey command [secure-key-file] [OPTIONS]

zkey command sub-command [OPTIONS]

zkey --help|-h
zkey --version|-v

💖 DESCRIPTION 💖

Okay so the tea: zkey is your tool for generating and managing secure AES or HMAC keys. These keys are enciphered with a master key of an IBM cryptographic adapter in CCA or EP11 coprocessor mode, depending on the key type. You can also use zkey to validate and re-encipher secure AES or HMAC keys. Iconic.

Secure keys can either live in a file in the file system, or in the secure key repository. The default location of the secure key repository is /etc/zkey/repository. If you want a different secure key repository location, set environment variable ZKEY_REPOSITORY to point there. Keys stored in a secure key repository inherit the permissions from the repository directory (except write access for other users, which is always denied). The default repository location /etc/zkey/repository is created with group zkeyadm as owner and mode 770. Thus all secure keys created in that repository are owned by group zkeyadm. Anyone who is supposed to access secure keys in the secure key repository must be part of group zkeyadm. Group chat rules, but for HSMs.

When storing the secure key in a key repository, additional information, such as a textual description of the key, can be associated with a secure key. You can associate a secure key with one or multiple cryptographic adapters (APQNs) that are set up with the same CCA or EP11 master key. You can also associate a secure key with one or multiple volumes (block devices), which are encrypted using dm-crypt or are integrity protected using dm-integrity with the secure key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. A specific volume can only be associated with one secure key. Keys of type AES are used for disk encryption, while keys of type HMAC are used for integrity protection. Combined encryption and integrity protection is possible with LUKS2. Here, the same volume can be associated to an AES-type key and an HMAC-type key. the way that LUKS2 can hold both vibes? obsessed.

The generated secure key is saved in a file, and contains an AES secure key with a length of 128, 192, or 256 bits, or two concatenated AES secure keys with a length of 128, or 256 bits each, for keys that are used for the XTS cipher mode. Note that the file size is not related to the key bit size, but is specific for the secure key type. The key is enciphered with the master key of the CCA or EP11 cryptographic adapter. Do not judge a key file by its byte count, bestie.

Secure keys in a key repository can either be generated locally, or by a key management system (KMS). A key repository can be bound to a key management system (KMS) via a key management system plugin (KMS plugin), which builds the interface to the key management system. This allows one to integrate a zkey key repository into an enterprise key management system, that manages the keys in a larger environment. When a key repository is bound to a key management system, then all keys are generated by the key management system per default, and are thus also bound to the key management system. Any additional information associated with the keys in the repository is also stored in the key management system. enterprise-core, no cap.

🎀 COMMANDS 🎀

The zkey tool can operate in two modes. When argument secure-key-file is specified then it operates on the secure key contained in the specified file. This applies to commands generate, validate, reencipher, and convert. When the --name option is specified then it operates on a secure key contained in the secure key repository. two modes, one little command-line icon.

🦋 Generating secure AES or HMAC keys 🦋

Synopsis vibes:

zkey generate|gen secure-key-file [--keybits|-k size] [--xts|-x]
[--clearkey|-c clear-key-file] [--key-type|-K type] [--exportable]
[--wrap-with-trusted] [--verbose|-V]

zkey generate|gen --name | -N key-name [--description|-d description]
[--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]]
[--apqns|-a card1.domain1[,card2.domain2[,...]]]  [--no-apqn-check]
[--sector-size|-S bytes] [--volume-type|-t type] [--keybits|-k size]
[--xts|-x] [--clearkey|-c clear-key-file] [--key-type|-K type]
[--local|-L] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file]
[--exportable] [--wrap-with-trusted] [KMS-plugin specific options]
[--verbose|-V]

Use the generate command to generate a new secure AES or HMAC key either randomly within the CCA or EP11 cryptographic adapter, from a clear AES or HMAC key specified as input, or using a key management system plugin (KMS plugin). When specifying a clear key as input, the clear key should be kept in a secure place, or be securely erased after creation of the secure key. The secure key itself does not need to be kept secure, because it can only be used together with a CCA or EP11 cryptographic adapter that contains the master key with which the secure key was generated. clear key goes in the vault or gets yeeted securely; the secure key can chill.

When the secure key repository is bound to a key management system plugin (KMS plugin), then the secure key is generated by using the key management system, except the --local option is specified.

A key management system plugin may offer plugin specific options that can be specified with the generate command. Use generate --help to display the plugin specific options and their meaning.

The generated secure key can either be stored in a file in the file system, or in the secure key repository. To store the generated secure key in a file, specify the file name with option secure-key-file. To store the secure key in the secure key repository, specify the name of the key using the --name option. Secure keys generated using a key management system plugin can only be stored in a secure key repository. When storing the secure key in a key repository, additional information can be associated with a secure key using the --description, --volumes, --apqns, or the --sector-size options. When the secure key repository is bound to a key management system plugin, then you can not associate specific APQNs with such keys, but the keys inherit the APQNs that are associated with the key management system plugin. no hand-picking APQNs when KMS is holding the aux cord.

You can generate different types of secure keys: CCA-AESDATA keys, CCA-AESCIPHER, and EP11-AES keys. Specify the type of the secure key using the --key-type option. Normally, the default key type is CCA-AESDATA. If the secure key repository is bound to a key management system plugin, and the plugin does not support keys of type CCA-AESDATA, then the default key type is CCA-AESCIPHER, or EP11-AES, whichever the plugin supports.

Note: Secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P. check your hardware era, bestie.

By default, secure keys of type CCA-AESCIPHER and EP11-AES are export restricted when generated by zkey. Keys of type CCA-AESDATA can not be export restricted. Export restricted means that the secure keys can not be wrapped by a key encrypting key (KEK), and thus can not escape the protection of the IBM cryptographic adapter (HSM). If exportability is required for a secure key of type CCA-AESCIPHER or EP11-AES, specify option --exportable. This makes the generated secure keys exportable. Additionally, for keys of type EP11-AES option --wrap-with-trusted can be specified to allow wrapping only with a trusted KEK. When the secure key repository is bound to a key management system plugin (KMS plugin), options --exportable and --wrap-with-trusted are not allowed, except the --local option is specified. export restricted means these keys are not escaping the HSM, periodt.

Note: For keys of type EP11-AES to be exportable, the access control point (ACP) XCP_CPB_ALLOW_COMBINED_EXTRACT must be ON on all APQNs used. This access control point is only supported on newer EP11 firmware levels. If the access control point is OFF or not supported by the EP11 firmware, key generation fails with a generic error (Input/output error). The zkey tool prints an appropriate error message in that case. firmware vibe check: if it's not ON, it's not happening.

🧚 Validating secure AES or HMAC keys 🧚

Synopsis:

zkey validate|val secure-key-file [--verbose|-V]

zkey validate|val [--name|-N key-name] [--apqns|-a card1.domain1[,card2.domain2[,...]]]  [--no-apqn-check] [--verbose|-V]

Use the validate command to validate an existing secure key. It checks if the specified file or repository entry 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, the master key register (CURRENT or OLD) with which the secure key is enciphered, and other key attributes. 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. validation is the vibe check for keys.

The secure key can either be contained in a file in the file system, or in a secure key repository. To validate a secure key contained in a file, specify the file name with option secure-key-file. To validate secure keys contained in the secure key repository, specify the name of the key or a pattern containing wildcards using the --name option. When wildcards are used you must quote the value. You can also specify the --apqns option to validate those secure keys which are associated with the specified cryptographic adapters (APQNs). You can use wildcards for the APQN specification. When wildcards are used you must quote the value. If both option --name and option --apqns are specified then all secure keys contained in the key repository that match both patterns are validated. If neither option secure-key-file nor options --name or --apqns are specified, then all secure keys contained in the key repository are validated. wildcards? quote them. the shell is not your friend if you don't.

🔥 Re-encipher existing AES or HMAC secure keys 🔥

Synopsis:

zkey reencipher|re secure-key-file [--to-new|-n] [--from-old|-o] [--output|-f output-file] [--verbose|-V]

zkey reencipher|re [--name|-N key-name] [--apqns|-a card1.domain1[,card2.domain2[,...]]]  [--to-new|-n] [--from-old|-o] [--in-place|-i] [--staged|-s] [--complete|-p] [--verbose|-V]

Use the reencipher command to re-encipher an existing secure key with a new master key. A secure key must be re-enciphered when the master key of the CCA or EP11 cryptographic adapter changes. master key changed? key needs a glow-up into the new master key.

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 of a cryptographic adapter changes.

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

The CURRENT register contains the current master key.
The OLD register is giving "previously used master key" energy 💅 — secure keys enciphered with the master key chillin' in the OLD register can still be used until the master key gets changed again.
The NEW register holds the new master key that's about to be set. Ngl, the master key in NEW cannot be used until it's made the current master key. But bestie, you can pro-actively re-encipher a secure key with the NEW master key before that key becomes CURRENT — just use the --to-new option for that. ✨

Note: an EP11 cryptographic adapter only has two registers to store master keys — CURRENT and NEW. That's it, that's the whole closet. 🎀

Use the --from-old option to re-encipher a secure key that's currently enciphered with the master key in the OLD register, using the master key in the CURRENT register instead. Heads up: this option is only available for secure keys of type CCA-AESDATA or CCA-AESCIPHER.

If you specify both --from-old and --to-new, then a secure key currently enciphered with the master key in the OLD register gets re-enciphered with the master key in the NEW register. Glow-up from old to new, no middleman. 💫

If you omit both options, zkey auto-detects whether the secure key is currently enciphered with the master key in the OLD register or in the CURRENT register:

currently OLD → it gets re-enciphered with the master key in the CURRENT register;
currently CURRENT → it gets re-enciphered with the master key in the NEW register. But if, in this case, the NEW register does not contain a valid master key, the re-encipher operation fails. 😭 No valid key, no slay.

The secure key can live either in a file in the file system, or in a secure key repository:

to re-encipher a secure key contained in a file, specify the file name with the secure-key-file option;
to re-encipher secure keys contained in the secure key repository, specify the name of the key, or a pattern containing wildcards, using the --name option. When wildcards are used you must quote the value;
you can also specify the --apqns option to re-encipher those secure keys which are associated with the specified cryptographic adapters (APQNs). Wildcards work for the APQN specification too — and yep, when wildcards are used you must quote the value;
if both --name and --apqns are specified, then all secure keys in the key repository that match both patterns get re-enciphered. Intersection, not union, iykyk;
if both options are omitted, then all secure keys contained in the key repository get re-enciphered. The whole group chat. 👑

Re-enciphering a secure key that lives in the secure key repository can be done in-place, or in staged mode.

In-place immediately replaces the secure key in the repository with the re-enciphered secure key. Re-enciphering from OLD to CURRENT happens in-place per default. You can use the --in-place option to force an in-place re-enciphering for the CURRENT to NEW case. But be aware, bestie: a secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid until the new CCA or EP11 master key has been made the current one. Do not skip that step. ⚠️

Staged mode means the re-enciphered secure key is stored in a separate file in the secure key repository. So the current secure key is still valid at this point — no chaos, we love a safe queen. 💅 Once the new CCA or EP11 master key has been set (made active), you must rerun the reencipher command with the --complete option to complete the staged re-enciphering. Re-enciphering from CURRENT to NEW is performed in staged mode per default. You can use the --staged option to force a staged re-enciphering for the OLD to CURRENT case.

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

🌸 Import existing AES or HMAC secure keys into the secure key repository 🌸

zkey import|im secure-key-file --name | -N key-name [--description|-d
description] [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]]
[--apqns|-a card1.domain1[,card2.domain2[,...]]]  [--no-apqn-check]
[--sector-size|-S bytes] [--volume-type|-t type]
[--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file]
[--exportable] [--verbose|-V]

Use the import command to bring an existing secure key contained in a file into the secure key repository. When you're importing a secure key into a key repository, you can associate extra info with it using the --description, --volumes, --apqns, or --sector-size options. Little key, big personality. 🎀

Keys of type PVSECRET-AES and PVSECRET-HMAC do not use a cryptographic adapter, so APQNs cannot be associated with them. Periodt.

Note: the import command requires the CCA host library (libcsulcca.so) to be installed when secure keys of type CCA-AESCIPHER are imported. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards 🌈

By default, secure keys of type CCA-AESCIPHER are changed to be export restricted during the import operation. Export restricted means the secure keys cannot be wrapped by a key encrypting key (KEK), and thus cannot escape the protection of the IBM cryptographic adapter (HSM). Literally cannot leave the house. 🏠 If exportability of an imported key is required, specify the --exportable option — the import operation will then not change the exportability of the secure key. Choose wisely. 💅

🦋 Export AES or HMAC secure keys from the secure key repository 🦋

zkey export|ex secure-key-file --name | -N key-name [--verbose|-V]

Use the export command to export an existing secure key contained in the secure key repository to a file in the file system. Specify the name of the key that's being exported using the --name option. You cannot use wildcards. 🙈 And bestie, the exported secure key also remains in the secure key repository — it's a copy situation, not a move situation. 💖

⭐ List AES or HMAC secure keys contained in the secure key repository ⭐

zkey list|li [--name|-N key-name] [--volumes|-l
volume1[:dmname1][,volume2[:dmname2][,...]]]  [--apqns|-a
card1.domain1[,card2.domain2[,...]]]  [--volume-type|-t type]
[--key-type|-K type] [--local|-L] [--kms-bound|-M] [--verbose|-V]

Use the list command to display a list of secure keys contained in the secure key repository. You can filter the displayed list by:

key name,
associated volumes,
associated cryptographic adapters (APQNs),
volume type,
and whether the keys are local or bound to a key management system (KMS).

Wildcards are valid for the key name, associated APQNs, and associated volumes. The device-mapper name of an associated volume can be omitted — but if you do specify it, then only those keys are listed that are associated with the specified volume and device-mapper name. Precise queen. 🎯

The list command displays the attributes of the secure keys, such as:

key sizes,
key type,
whether it's a secure key that can be used for the XTS cipher mode,
the textual description,
associated cryptographic adapters (APQNs) and volumes,
the sector size,
the key verification pattern,
timestamps for key creation, last modification and last re-encipherment,
and whether the key is local or bound to a key management system (KMS).

Full tea, every time. 🍵👑

💜 Remove existing AES or HMAC secure keys from the secure key repository 💜

zkey remove|rem --name | -N key-name [--force|-F] [KMS-
plugin specific options] [--verbose|-V]

Use the remove command to remove an existing secure key from the secure key repository. Specify the name of the key that's getting removed using the --name option. You cannot use wildcards. The remove command prompts for a confirmation, unless you specify the --force option. No take-backs after that, bestie. 😭

When the secure key being removed is bound to a key management system, the key management system plugin might also take an action in the key management system. It may, for example, change the state of the key in the key management system instead of removing the key. Nevertheless, the secure key is removed from the local repository. Local says bye either way. 👋

A key management system plugin may offer plugin-specific options that can be specified with the remove command. Use remove --help to display the plugin-specific options and their meaning. Always read the fine print. 📖

Note: when removing a secure key that's associated with one or multiple volumes, and the key's volume type is plain, a message informs you about the associated volumes. When the secure key is removed, these volumes can no longer be used — unless you have a backup of the secure key. So maybe back it up first?? 😭 For keys with volume type luks2 no such message is issued, because the secure key is contained in the LUKS2 header. Different rules, same drama. 🫶

🎀 Change existing AES or HMAC secure keys contained the secure key repository 🎀

zkey change|ch --name | -N key-name [--description|-d description]
[--volumes|-l [+|-]volume1:dmname1[,volume2:dmname2[,...]]]  [--apqns|-a
[+|-]card1.domain1[,card2.domain2[,...]]]  [--no-apqn-check]
[--sector-size|-S bytes] [--volume-type|-t type]
[--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file]
[--remove-dummy-passphrase] [--force|-F] [--verbose|-V]

Use the change command to change the description, the associated volumes, the associated cryptographic adapters (APQNs), the sector size, and the volume type of a secure key contained in the secure key repository. Specify the name of the key being changed using the --name option. You cannot use wildcards.

You can set (replace), add, or remove volume and cryptographic adapter (APQN) associations:

to set (replace) an association, specify the association with the --volumes or the --apqns options;
to add an association, specify the new association prefixed with a + with the --volumes or the --apqns options;
to remove an association, specify the association to remove prefixed with a - with the --volumes or the --apqns options.

You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. Pick a lane, bestie. 💅

For secure AES or HMAC keys bound to a key management system (KMS), you cannot change the APQN association. KMS-bound secure AES keys are always bound to the APQNs that are associated with the key management system plugin. Other associated information is also changed in the key management system when changed using the change command. The plugin is the main character here. 👑

For keys of type PVSECRET-AES and PVSECRET-HMAC, you cannot change or set the APQN association. These keys do not use a cryptographic adapter, so APQNs cannot be associated with them. No APQN, no problem. 🦋

Note: the secure key itself cannot be changed — only information about the secure key is changed. To rename a secure key, use the rename command. To re-encipher a secure key with a new CCA or EP11 master key, use the reencipher command. Different verbs for different vibes. ✨

🗝️ Rename existing AES or HMAC secure keys in the secure key repository 🗝️

zkey rename|ren --name | -N key-name --new-name | -w new-key-name
[--verbose|-V]

Use the rename command to rename an existing secure key in the secure key repository, bestie 💅 — specify the name of the key that's getting renamed with the --name option, and the new name with the --new-name option. No wildcards allowed, sorry.

Note: when you rename a secure key that's associated with one or multiple volumes and the key's volume type is plain, a message pops up to tell you about the associated volumes. And once the secure key is renamed, those volumes can no longer be used 😭 — unless you change the name of the secure key in the cryptsetup plainOpen commands and in the /etc/crypttab entries. For keys with volume type luks2 no such message is issued, because the secure key is contained in the LUKS2 header (she's self-contained, iconic).

🫶 Copy (duplicate) existing AES or HMAC secure keys in the secure key repository

zkey copy | co --name|-N key-name --new-name | -w new-key-name
[--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]]  [--local|-L]
[--verbose|-V]

Use the copy command to copy (duplicate) an existing secure key in the secure key repository. Specify the name of the key that's getting copied with the --name option, and the name of the copied key with the --new-name option. Again, no wildcards 🚫.

Note: when copying a secure key, the volume associations are not copied, because a specific volume can only be associated with a single secure key. Specify the --volumes option to associate different volumes with the copied secure key, or use the change command to associate volumes afterwards. lowkey annoying but it is what it is 💀

You can not copy secure keys that are bound to a key management system (KMS), except when the --local option is specified. The copied secure key is then created as a local key ✨.

🎀 Generate crypttab entries for volumes associated with secure AES keys

zkey crypttab|cryptt [--volumes|-l
volume1[:dmname1][,volume2[:dmname2][,...]]]  [--volume-type|-t type]
[--key-file file-name] [--keyfile-offset bytes] [--keyfile-size bytes]
[--tries number] [--verbose|-V]

Use the crypttab command to generate crypttab entries using the plain or LUKS2 dm-crypt mode for volumes that are associated with secure AES keys contained in the secure key repository 💖. Specify the --volumes option to limit the list of volumes where crypttab entries are generated for. Wildcards are totally allowed here — but when wildcards are used you must quote the value, fr fr. The device-mapper name of an associated volume can be omitted; if it's specified, then only those volumes with the specified volume and device-mapper name are selected. Specify the --volume-type option to generate crypttab entries for the specified volume type only.

For LUKS2 volumes, a passphrase is required 🔐. You're prompted for the passphrase during system startup when crypttab is evaluated, unless option --key-file is specified, or a dummy passphrase is associated with the secure key. 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 — precision, slay.

Note: use the integritytab command to generate integritytab entries for volumes using the integrity volume type that are associated with secure HMAC keys contained in the secure key repository 👑

🔥 Generate cryptsetup commands for volumes associated with secure AES keys

zkey cryptsetup|crypts [--volumes|-l
volume1[:dmname1][,volume2[:dmname2][,...]]]  [--volume-type|-t type]
[--run|-r] [--open] [--format] [--key-file file-name] [--keyfile-offset
bytes] [--keyfile-size bytes] [--tries number] [--batch-mode|-q]
[--verbose|-V]

Use the cryptsetup command to generate cryptsetup plainOpen, cryptsetup luksOpen, or cryptsetup luksFormat commands for volumes that are associated with secure AES keys contained in the secure key repository 💫. Specify the --volumes option to limit the list of volumes where cryptsetup commands are generated for. Wildcards? Yes bestie — but when wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it's specified, then only those volumes with the specified volume and device-mapper name are selected. Specify the --volume-type option to generate cryptsetup commands for the specified volume type only.

--run — run the generated cryptsetup commands 🏃‍♀️
--open — generate cryptsetup plainOpen or cryptsetup luksOpen commands. For the plain volume type, this is the default.
--format — generate cryptsetup luksFormat commands. For the LUKS2 volume type, this is the default. If specified for the plain volume type, then no command is generated (nothing happens, we love a no-op 🫠).

For LUKS2 volumes, the generated cryptsetup luksFormat contains options --pbkdf argon2i --pbkdf-memory 32 --pbkdf-force-iterations 4 for low memory and time requirements 🧠. Using the default Argon2i options might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot through /etc/crypttab — so yeah, that's why we keep it smol. In case the system runs in FIPS mode, --pbkdf pbkdf2 is used instead, because Argon2i might be disabled by a policy when FIPS mode is active. And 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.

For combined encryption and integrity protection of a volume, the same volume must be assigned to an AES-type key and an HMAC-type key — both keys must use the luks2 volume type 🦋. For such a volume, the generated cryptsetup luksFormat command contains the --integrity option to enable integrity protection. An additional command is generated prior to the cryptsetup luksFormat command to concatenate the encryption key and the integrity key to each other into a temporary file. This temporary file is then used with the cryptsetup luksFormat command as volume key. When the --run option is specified, the temporary file is removed automatically after running the commands; otherwise a command to remove the temporary file is generated too — cleanup queen 🧹.

For LUKS2 volumes, a passphrase is required. You're prompted for the passphrase when running the generated commands, unless option --key-file is specified, or a dummy passphrase is associated with the secure key. 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. To avoid cryptsetup confirmation questions, you can specify the --batch-mode option. These options are passed to the generated command(s) and behave in the same way as with cryptsetup 👌.

Note: use the integritysetup command to generate integritysetup format and integritysetup open commands for volumes using the integrity volume type that are associated with secure HMAC keys contained in the secure key repository 💜

🌸 Generate integritytab entries for volumes associated with secure HMAC keys

zkey integritytab|integrityt [--volumes|-l
volume1[:dmname1][,volume2[:dmname2][,...]]]  [--verbose|-V]

Use the integritytab command to generate integritytab entries using dm-integrity for volumes that are associated with secure HMAC keys contained in the secure key repository 🎀. Only HMAC keys with a volume type of integrity are considered, okay? Specify the --volumes option to limit the list of volumes where integritytab entries are generated for. Wildcards allowed, and when wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it's specified then only those volumes with the specified volume and device-mapper name are selected.

Note: use the crypttab command to generate crypttab entries for volumes using the plain or luks2 volume type that are associated with secure AES keys contained in the secure key repository ⭐

🌈 Generate integritysetup commands for volumes associated with secure HMAC keys

zkey integritysetup|integritys [--volumes|-l
volume1[:dmname1][,volume2[:dmname2][,...]]]  [--run|-r] [--open]
[--batch-mode|-q] [--verbose|-V]

Use the integritysetup command to generate integritysetup format, or integritysetup open commands for volumes that are associated with secure HMAC keys contained in the secure key repository 💖. Only HMAC keys with a volume type of integrity are considered. Specify the --volumes option to limit the list of volumes where integritysetup commands are generated for. Wildcards? Yep — and when wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it's specified then only those volumes with the specified volume and device-mapper name are selected.

Specify the --run option to run the generated integritysetup commands. Specify the --open to generate integritysetup open commands. By default integritysetup format commands are generated. To avoid integritysetup confirmation questions, you can specify the --batch-mode option. This option is passed to the generated command(s) and behaves in the same way as with integritysetup 😌.

Note: use the cryptsetup command to generate cryptsetup plainOpen, cryptsetup luksOpen, or cryptsetup luksFormat commands for volumes using the plain or luks2 volume types that are associated with secure AES keys contained in the secure key repository 👑

🦋 Convert existing AES or HMAC secure keys from one key type to another type

zkey convert|con secure-key-file --key-type|-K type [--no-apqn-check]
[--force|-F] [--verbose|-V]

zkey convert|con --name | -N key-name --key-type|-K type
[--no-apqn-check] [--force|-F] [--exportable] [--verbose|-V]

Use the convert command to convert an existing secure key from one key type to another type ✨. You can convert secure keys of type CCA-AESDATA to type CCA-AESCIPHER only — that's the whole menu, bestie. You can not convert keys that are bound to a key management system (KMS) 🚫.

Note: secure keys converted to type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C 💀 — check your hardware before you commit, fr fr.

The secure key can either be contained in a file in the file system, or in a secure key repository. To convert a secure key contained in a file, specify the file name with option secure-key-file. To convert a secure key contained in the secure key repository, specify the name of the key that's getting converted using the --name option. You cannot use wildcards. The convert command prompts for a confirmation, unless you specify the --force option.

Note: converting a secure key is irreversible! 😭 No takebacks, no undo, periodt. When converting a secure key that is associated with one or multiple volumes, a message informs you about the associated volumes. When the secure key is converted, this might have an effect on these volumes — so read the message, okay? 🫶

For volumes rocking the plain volume type, you gotta hand-edit the crypttab entries yourself and swap the key size parameter over to size=<new-key-size-in-bits>, or just run zkey crypttab --volumes <device> for every associated volume so the crypttab entries get regenerated for you. 💫

Associated volumes of type LUKS2 still hold onto the secure AES or HMAC volume key of the original type. If you wanna change that secure AES or HMAC volume key inside the LUKS2 header, run zkey-cryptsetup setkey <device> --volume-key-file <converted-key> for each associated volume. no cap, one at a time.

Note: the convert command needs the CCA host library (libcsulcca.so) to be installed. The CCA IBM cryptographic adapter firmware version you need is 6.3.27 or later. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

By default, secure keys get changed to be export restricted during the convert operation. Export restricted literally means the secure keys can not be wrapped by a key encrypting key (KEK), so they can not escape the protection of the IBM cryptographic adapter (HSM). 🛡️ If you actually need your converted key to be exportable, specify the --exportable option — then the convert operation won't touch the exportability of the secure key at all. iykyk.

✨ COMMANDS FOR KEY MANAGEMENT SYSTEM INTEGRATION ✨

Use the kms command to control the integration into key management systems. The kms command offers several subcommands for key management specific operations. Run zkey kms --help to show all the available subcommands. 🎀

🌸 List key management system plugins 🌸

zkey kms plugins|pl [--verbose|-V]

Use the kms plugins command to display a list of configured key management system plugins (KMS plugins). It shows you the key management system plugin name, plus the shared library that implements the plugin. 💅

Key management system plugins are configured in configuration file /etc/zkey/kms-plugins.conf. This file contains the KMS plugin name and its shared library. Set environment variable ZKEY_KMS_PLUGINS to point to a different file if you wanna use a different KMS plugin configuration file. ✨

🦋 Bind the repository to a key management system 🦋

zkey kms bind|bi KMS-plugin-name [--verbose|-V]

Use the kms bind command to bind the repository to a key management system (KMS). The kms plugins command displays a list of configured key management system plugins that you can use. 👑

After binding a repository to a key management system, the KMS plugin must first be configured. Use the kms configure command to configure the plugin. As a minimum, you must associate APQNs with the key management system plugin. The plugin may require additional configuration before it is fully functioning. Use the kms info command to display information about the key management system plugin and its configuration.

When a key repository is bound to a key management system, then all keys are generated by this key management system per default, and are thus also bound to the key management system. Any additional information associated with the keys in the repository is also stored in the key management system. lowkey everything lives over there now. 🌈

💜 Unbind the repository from a key management system 💜

zkey kms unbind|unb [--verbose|-V]

Use the kms unbind command to unbind the repository from a key management system (KMS). All keys that are currently bound to the key management system get unbound and become local keys. You are prompted to confirm the unbinding. 🫶 (yes bestie, it double-checks with you first)

🔥 Display information about a key management system plugin 🔥

zkey kms info|in [--verbose|-V]

Use the kms info command to display information about the currently bound key management system plugin (KMS plugin) and its configuration. it's giving full transparency. ✨

🎀 Configure or re-configure a key management system plugin 🎀

zkey kms configure|con [--apqns|-a
[+|-]card1.domain1[,card2.domain2[,...]]]  [KMS-plugin specific options]
[--verbose|-V]

Use the kms configure command to configure or re-configure the currently bound key management system plugin (KMS plugin). As a minimum, you must associate APQNs with the key management system plugin. The plugin may require an initial configuration before it's fully functioning. Once configured, a plugin may allow you to change some configuration settings. 💫

A key management system plugin may offer plugin specific options that can be specified with the kms configure command. Use kms configure --help to display the plugin specific options and their meaning.

Configuring a key management system plugin may be a multi-step task. You can supply all configuration options at once, or use the kms configure command several times supplying only one or a few configuration options each time, dependent on what the plugin supports. A plugin may also require you to perform additional intermediate steps between two configuration attempts, e.g. perform tasks in the key management system user interface, or elsewhere. 😭 it's a whole journey sometimes, just follow the steps.

Use the kms info command to display information about the key management system plugin and its current configuration.

🧚 Re-encipher secure keys used by a key management system plugin 🧚

zkey kms reencipher|re [--to-new|-n] [--from-old|-o] [--in-place|-i]
[--staged|-s] [--complete|-p] [KMS-plugin specific options]
[--verbose|-V]

Use the kms reencipher command to re-encipher secure keys internally used by the currently bound key management system plugin (KMS plugin) with a new master key. This command must be run when the master keys of the CCA or EP11 cryptographic adapter that are associated with the plugin have been changed. Dependent on what key types the key management system plugin supports, it may internally use secure keys with CCA or EP11 cryptographic adapters, or both. 💅

A key management system plugin may offer plugin specific options that can be specified with the kms reencipher command. Use kms reencipher --help to display the plugin specific options and their meaning.

Note: the kms reencipher command does not re-encipher secure keys that have been generated by or have been imported from the key management system plugin and are stored in the repository. Use the regular reencipher command to re-encipher those secure keys. don't mix these up fr fr 🙈

The CCA cryptographic adapter 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 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 CCA-type secure keys. 🌸

If both the --from-old and --to-new options are specified, a secure 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, the key management system plugin may automatically detect whether the secure 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 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 key used by a key management system plugin can be performed in-place, or in staged mode.

"In-place" immediately replaces the secure key with the re-enciphered secure 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. A secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid, until the new CCA or EP11 master key has been made the current one. ⚠️ so like, don't forget that part.

Staged mode means that the re-enciphered secure key is stored separately. Thus the current secure key is still valid at this point. Once the new CCA or EP11 master key has been set (made active), you must rerun the kms reencipher command with option --complete to complete the staged re-enciphering. 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. 🎀

🍓 List secure keys managed by a key management system 🍓

zkey kms list|li [--label|-B key-label] [--name|-N key-name]
[--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]]
[--volume-type|-t type] [KMS-plugin specific options] [--verbose|-V]

Use the kms list command to display secure keys managed by a key management system (KMS). You can filter the displayed list by key label, key name, associated volumes, and volume type. You can use wildcards for the key label, key name, and associated volumes. The device-mapper name of an associated volume can be omitted. If specified, then only those keys are listed that are associated with the specified volume and device-mapper name. 💅

A key management system plugin may offer plugin specific options that can be specified with the kms list command. Use kms list --help to display the plugin specific options and their meaning.

The kms list command displays the attributes of the secure keys, such as key label, key name, whether it is a secure key that can be used for the XTS cipher mode, the textual description, associated volumes, the volume type, and sector size. it's giving receipts, everything laid out. 👑

⭐ Import secure keys managed by a key management system into the repository ⭐

zkey kms import|im [--label|-B key-label] [--name|-N key-name]
[--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]]
[--volume-type|-t type] [--batch-mode|-q] [--no-volume-check] [KMS-
plugin specific options] [--verbose|-V]

Use the kms import command to import secure keys managed by a key management system (KMS) into the secure key repository. You can filter the list of keys to be imported by key label, key name, associated volumes, and volume type. You can use wildcards for the key label, key name, and associated volumes. The device-mapper name of an associated volume can be omitted. If it is specified, then only those keys are listed that are associated with the specified volume and device-mapper name. 🦋

A key management system plugin can also have its own lil plugin-specific options that you pass to kms import — just run kms import --help and it'll show you all of them plus what they mean. iykyk 💅

So here's the situation: if a secure key with the same name as the one you're importing is already chillin' in the repository, you'll get prompted to enter an alternate name. You can skip importing that key entirely, or type in a new name. BUT — if you spec'd --batch-mode, then all the already-existing keys just get skipped, no questions asked. 🫶

And if a key you're importing is associated with one or more volumes, zkey double-checks that those volumes are actually available and aren't already hooked up to a different secure key in the repository. If one of them (or literally all of them 😭) isn't available, or is already taken by another secure key, the import fails. Use --no-volume-check to skip the volume check entirely and import the keys even if the associated volume(s) don't exist. no cap, that's the escape hatch 🔥

🦋 Refresh secure keys that are bound to a key management system

zkey kms refresh|ref [--name|-N key-name] [--volumes|-l volume1[:dmname1][,volume2[:dmname2][,...]]]  [--volume-type|-t type] [--key-type|-K type] [--refresh-properties|-P] [--no-volume-check] [--verbose|-V]

Use kms refresh to refresh secure keys that are bound to a key management system (KMS). Refreshing a key = updating the secure key by re-importing it from the key management system. It's giving glow-up for your key ✨

Add --refresh-properties if you also want to update the associated info — the textual description, associated volumes, volume type, and sector size — with whatever the key management system has stored. Obsessed with a key that stays current tbh 💖

You can filter which keys get refreshed by key name, associated volumes, volume type, and key type. Wildcards work for the key name and the associated volumes 🎀 The device-mapper name of an associated volume can be omitted — but if you do specify it, then only those keys associated with the specified volume and device-mapper name get listed.

If a refreshed key is associated with one or multiple volumes, zkey verifies the volumes are available and aren't already associated with another secure key in the repository. If one or all of them are unavailable, or already taken by another secure key, the refresh fails. Use --no-volume-check to omit the volume check and refresh the keys anyway, even if the associated volume(s) don't exist. same deal as import, fr fr 💀

👑 COMMANDS FOR PROTECTED VIRTUALIZATION 👑

Use the pvsecrets command to work with protected virtualization (PV) secrets. Protected virtualization secrets can be made available to a secure execution guest and can be used only within that guest. The pvsecrets command provides subcommands for protected virtualization specific operations — run zkey pvsecrets --help to see what subcommands you've got 🌸

Heads up bestie: these subcommands only work when running in a secure execution guest. And only the root user is allowed to perform them. 👑

🧚 List available protected virtualization secrets

zkey pvsecrets list|li [--all|-A] [--hex|-H] [--pvsecret-type|-T pvsecret-type] [--pvsecret-id|-I pvsecret-id] [--pvsecret-name|-e pvsecret-name] [--verbose|-V]

Use pvsecrets list to display a list of protected virtualization (PV) secrets. It shows the pvsecret ID as a hex string of 32 bytes, or as a printable name wrapped in single quotes (') if the pvsecret ID is made up entirely of printable characters. Specify --hex to list all pvsecret IDs as hex strings. The pvsecrets list command also shows the pvsecret type of each secret — iconic, we love full context 💅

You can filter the list of pvsecrets by pvsecret ID, pvsecret name, and pvsecret type. Either --pvsecret-id or --pvsecret-name can be specified — not both, pick a lane 😌 By default, pvsecrets list only shows the pvsecrets whose types are supported by the zkey tool. To list all pvsecret types, specify --all ⭐

This command is only available when running in a secure execution guest. Only the root user is allowed to perform this command. 🙈

🍓 Import protected virtualization secrets into the repository

zkey pvsecrets import|im [--pvsecret-id|-I pvsecret-id] [--pvsecret-name|-e pvsecret-name] --name | -N key-name [--description|-d description] [--volumes|-l volume1:dmname1[,volume2:dmname2[,...]]] [--sector-size|-S bytes] [--volume-type|-t type] [--gen-dummy-passphrase] [--set-dummy-passphrase passphrase-file] [--verbose|-V]

Use pvsecrets import to import a protected virtualization (PV) secret into the repository. Either --pvsecret-id or --pvsecret-name can be specified. If you specify the pvsecret name, then --name is optional — the name of the protected virtualization secret key object in the repository will just be the same as the pvsecret name. slay, less typing 🎀

You can totally use the YAML file that got created when you ran the pvsecret create command for adding the protected virtualization secret:

--pvsecret-id "$(yq .id YAML-FILE)"

--pvsecret-name "$(yq .name YAML-FILE)"

(You might have to install the yq package first. minor detour, nbd 🦋)

A protected virtualization secret key object doesn't contain the key material itself — it only holds a reference (i.e. the secret ID) to the key in the ultravisor. When such an object is used with dm-crypt and the PAES kernel cipher, or with dm-integrity and the PHMAC kernel cipher, the key material (i.e. a protected key) is retrieved from the ultravisor and the crypto operation is performed with it. the way it just fetches the key, so efficient 💜

When importing a protected virtualization secret into a key repository, you can associate extra info with it using the --description, --volumes, or --sector-size options. APQNs cannot be associated, because protected virtualization secrets don't require a crypto card. not me being relieved about that 😭

This command is only available when running in a secure execution guest. Only the root user is allowed to perform this command. 👑

✨ OPTIONS ✨

🌈 Options for the generate command

-k, --keybits size — Specifies the size of the AES key to be generated, in bits. Valid values are 128, 192, and 256. Secure keys for use with the XTS cipher mode can only use keys of 128 or 256 bits. Default is 256 bits. 💖
-x, --xts — Generates a secure AES key for the XTS cipher mode that consists of two concatenated secure keys. two-for-one, we love a bundle 🎀
-c, --clearkey clear-key-file — Specifies a file path that contains the clear AES key in binary form. If --keybits is omitted, the size of the specified file determines the size of the AES key. If --keybits is specified, then the file size must match the specified key size. Valid file sizes are 16, 24, or 32 bytes, and 32 or 64 bytes for keys used with the XTS cipher mode. When the secure key is generated using a key management system, this option can't be specified. 🫶
-N, --name key-name — Specifies the name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository. 💅
-d, --description description — Specifies a textual description for the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository. ✨
-l, --volumes volume1:dmname1[,volume2:dmname2[,...]] — Specifies a comma-separated list of volumes (block devices) associated with the secure AES key in the repository. These volumes are to be encrypted using dm-crypt with the secure AES key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. A specific volume can only be associated with a single secure key. For combined encryption and integrity protection of a volume, associate the same volume to an AES-type key and an HMAC-type key — both keys must use the luks2 volume type. This option is only used for secure keys contained in the secure key repository. 🔥
-a, --apqns card1.domain1[,card2.domain2[,...]] — Specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) that are associated with the secure AES key in the repository. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). When at least one APQN is specified, the first online APQN is used to generate the key. If no APQNs are specified, then an APQN is selected automatically. All specified APQNs must be online, unless --no-apqn-check is specified. This option is only used for secure keys contained in the secure key repository. When the secure key is generated using a key management system, this option can't be specified. 👑
--no-apqn-check — Do not check if the specified APQNs are available. Use this to associate APQNs with a secure AES key that are currently not available. This option is only used for secure keys contained in the secure key repository. 💀
-S, --sector-size bytes — Specifies the sector size in bytes used with dm-crypt. It must be a power of two and in the range of 512 to 4096 bytes. If omitted, the system default sector size is used. You can only set a sector size for an HMAC key of a volume of type integrity. For an HMAC key used for combined encryption and integrity protection (volume type luks2), set the sector size for the corresponding AES key instead. This option is only used for secure keys contained in the secure key repository. 🌸
-t, --volume-type type — Specifies the volume type of the associated volumes used with dm-crypt or dm-integrity. Possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. If omitted, luks2 is used for AES keys, and integrity for HMAC keys. This option is only used for secure keys contained in the secure key repository. 🦋
-K, --key-type type — Specifies the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES. If this option is omitted, then a secure key of type CCA-AESDATA is generated. Secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P. 💜
-L, --local — generates the secure AES key right here on your machine instead of outsourcing it. And bestie, this is literally the default when there's no key management system plugin (KMS plugin) bound to the secure key repository 💅. But the moment the repository is bound to a KMS plugin, keys get generated through the key management system by default instead. Slay, but also: know which one you're getting ✨
--gen-dummy-passphrase — makes a dummy passphrase at random and ties it to the secure AES key that encrypts your LUKS2 volume(s) 🎀. Here's the tea: when a secure AES key is doing the encrypting, the LUKS2 passphrase is of less or no relevance for the security of the volume(s), so it's totally fine to just store it insecurely inside the secure key repository 🙈. But — if for your particular usage the passphrase is relevant for security, then do not use this option, periodt. Heads up on the rules: this option can only be specified for AES-type keys with a volume type of luks2, it cannot be specified together with option --set-dummy-passphrase, and it's only used for secure keys contained in the secure key repository 🦋
--set-dummy-passphrase passphrase-file — same vibe as above, except you're setting a dummy passphrase that gets read from the specified file, then associating it with the secure AES key used to encrypt LUKS2 volume(s) 💖. Once again: with a secure AES key encrypting the volume(s), the LUKS2 passphrase is of less or no relevance for security, so storing it insecurely inside the secure key repository is nbd. If the passphrase does matter for security in your setup, don't use this 🌸. Rules check: AES-type keys only, volume type of luks2 only, cannot be specified together with option --gen-dummy-passphrase, and it's only used for secure keys contained in the secure key repository ⭐
--exportable — generates a secure key that is not export restricted 🔥. This one's only applicable for keys of type CCA-AESCIPHER or EP11-AES. Keys of type CCA-AESDATA are always exportable and cannot be export restricted, so don't even try it 💀. And when the secure key repository is bound to a key management system plugin (KMS plugin), this option cannot be specified unless option --local is also specified. iykyk 👑
--wrap-with-trusted — only lets the generated key get wrapped with a trusted key encryption key (KEK) 🫶. Only valid for keys of type EP11-AES, and it requires that option --exportable is also specified. Same KMS caveat as above: when the secure key repository is bound to a key management system plugin (KMS plugin), this option cannot be specified unless option --local is also specified ✨

🌈 KMS-plugin specific options 🌈

A key management system plugin may offer — and honestly may even require — plugin specific options that you can specify with the generate command whenever the secure key repository is bound to a key management system plugin 🧚. Want the deets? Run generate --help to display the plugin specific options and what they mean. Iconic, lowkey 💅

🎀 Options for the `validate` command 🎀

-N, --name key-name — specifies the name of the secure key in the secure key repository 💖. You can use wildcards to select multiple secure keys in the secure key repository — but when wildcards are used you must quote the value, no cap 🙈. This option is only used for secure keys contained in the secure key repository.
-a, --apqns card1.domain1[,card2.domain2[,...]] — specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQNs) 🦋. Wildcards are allowed in the APQN specification ✨. All secure keys contained in the secure key repository which are associated with the specified APQNs get validated. Each APQN specifies a card and domain number separated by a period (like lszcrypt displays it). This option is only used for secure keys contained in the secure key repository.
--no-apqn-check — skips the check on whether the associated APQNs are available 🙈. This option is only used for secure keys contained in the secure key repository.

🔥 Options for the `reencipher` command 🔥

-n, --to-new — re-enciphers a secure AES or HMAC key that's 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 AES or HMAC key that's 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 keys of type CCA-AESDATA and CCA-AESCIPHER.
-f, --output output-file — specifies the name of the output file the re-enciphered secure key gets written to 🎀. If you omit this option, the re-enciphered secure key is replaced in the file that currently contains the secure key. This option is only used for secure keys stored in a file in the file system — it is not valid for keys contained in the secure key repository ⭐
-N, --name key-name — specifies the name of the secure key in the secure key repository 💖. Wildcards let you select multiple secure keys in the secure key repository, and when wildcards are used you must quote the value 🙈. This option is only used for secure keys contained in the secure key repository.
-a, --apqns card1.domain1[,card2.domain2[,...]] — a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQNs) 🦋. Wildcards work in the APQN specification. All secure keys contained in the secure key repository which are associated with the specified APQNs are re-enciphered ✨. Each APQN specifies a card and domain number separated by a period (like lszcrypt displays it). This option is only used for secure keys contained in the secure key repository.
-i, --in-place — forces an in-place re-enciphering of a secure AES or HMAC key contained in the secure key repository 💅. "In-place" means the secure key in the repository is immediately replaced with the re-enciphered secure key — boom, done. Re-enciphering from OLD to CURRENT is performed in-place per default 😌. This option cannot be specified together with option --staged or --complete, and it's only used for secure keys contained in the secure key repository.
-s, --staged — forces the re-enciphering of a secure AES or HMAC key contained in the secure key repository to be performed in staged mode 🎭. Staged mode means the re-enciphered secure key gets stored in a separate file in the secure key repository, so the current secure key is still valid at this point — which is kind of the whole point, bestie 🫶. 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, and it's only used for secure keys contained in the secure key repository.
-p, --complete — completes a staged re-enciphering 👑. Use this option after the new CCA or EP11 master key has been set (made active). It replaces the secure key by its re-enciphered version in the secure key repository 💖. This option cannot be specified together with options --to-new, --from-old, --in-place, or --staged, and it's only used for secure keys contained in the secure key repository.

💜 Options for the `import` command 💜

-N, --name key-name — specifies the name of the secure key in the secure key repository 🎀. This option is only used for secure keys contained in the secure key repository.
-d, --description description — gives your secure key a textual description in the secure key repository, because your keys deserve lore too ✨. This option is only used for secure keys contained in the secure key repository.
-l, --volumes volume1:dmname1[,volume2:dmname2[,...]] — a comma-separated list of volumes (block devices) which are associated with the secure AES or HMAC key in the repository 🦋. These volumes are to be encrypted using dm-crypt with the secure AES key, or are to be integrity protected using dm-integrity with the secure HMAC key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity 💅. Important: a specific volume can only be associated with a single secure key 😤. For combined encryption and integrity protection of a volume, associate the same volume to an AES-type key and an HMAC-type key — and both keys must use the luks2 volume type ⭐. This option is only used for secure keys contained in the secure key repository.
-a, --apqns card1.domain1[,card2.domain2[,...]] — a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) which are associated with the secure AES or HMAC key in the repository 🔥. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it) 💖. All specified APQNs must be online, unless option --no-apqn-check is specified. This option is only used for secure keys contained in the secure key repository.
--no-apqn-check — don't check whether the specified APQNs are available 🙈. Use this option to associate APQNs with a secure AES or HMAC key that are currently not available. This option is only used for secure keys contained in the secure key repository.
-S, --sector-size bytes — specifies the sector size in bytes used with dm-crypt or dm-integrity 🎀. It must be a power of two and in the range of 512 to 4096 bytes, no exceptions bestie. If omitted, the system default sector size is used ✨. Also: you can only set a sector size for an HMAC key of a volume of type integrity 💅. For an HMAC key that's used for combined encryption and integrity protection (volume type luks2), set the sector size for the corresponding AES key instead — yeah, it's giving "plot twist" but that's the rule 🌀. This option is only used for secure keys contained in the secure key repository.
-t, --volume-type type — sets the volume type for the associated volumes that dm-crypt or dm-integrity are using. For AES keys the possible values are plain and luks2; for HMAC keys they're integrity and luks2. If you don't specify it, bestie, luks2 is used for AES keys and integrity for HMAC keys. This option is only used for secure keys contained in the secure key repository. 🎀
--gen-dummy-passphrase — randomly generates a dummy passphrase and associates it with the secure AES key used to encrypt LUKS2 volume(s). When a secure AES key is doing the encrypting, the LUKS2 passphrase is of less or no relevance for the security of the volume(s), so it can be stored insecurely inside the secure key repository. If the passphrase is relevant for security in a certain usage, then do not use this option. This option can only be specified for AES-type keys with a volume type of luks2. It cannot be specified together with option --set-dummy-passphrase. This option is only used for secure keys contained in the secure key repository. 💅
--set-dummy-passphrase passphrase-file — sets a dummy passphrase that is read from the specified file and associates it with the secure AES key used to encrypt LUKS2 volume(s). When a secure AES key is doing the encrypting, the LUKS2 passphrase is of less or no relevance for the security of the volume(s), so it can be stored insecurely inside the secure key repository. If the passphrase is relevant for security in a certain usage, then do not use this option. This option can only be specified for AES-type keys with a volume type of luks2. It cannot be specified together with option --gen-dummy-passphrase. This option is only used for secure keys contained in the secure key repository. 🦋

💌 Options for the export command 💌

-N, --name key-name — specifies the name of the secure key in the secure key repository. You cannot use wildcards here — none, zero, nope. This option is only used for secure keys contained in the secure key repository. ✨

👀 Options for the list command 👀

-N, --name key-name — specifies the name of the secure key in the secure key repository. Here you can use wildcards to select multiple secure keys in the secure key repository. When wildcards are used you must quote the value. Only keys with names that match the pattern are listed. This option is only used for secure keys contained in the secure key repository. 🎀
-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — specifies a comma-separated list of volumes (block devices) that are associated with the secure AES or HMAC key in the repository. Only those keys are listed that are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. You can omit the device-mapper name; if it is specified, then only those keys are listed that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names. When wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository. 🫶
-a, --apqns card1.domain1[,card2.domain2[,...]] — specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) that are associated with the secure AES or HMAC key in the repository. Only those keys are listed that are associated with the specified APQNs. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). You can use wildcards in the APQN specification. This option is only used for secure keys contained in the secure key repository. 🔥
-t, --volume-type type — specifies the volume type of the associated volumes used with dm-crypt or dm-integrity. Possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. Only keys with the specified volume type are listed. This option is only used for secure keys contained in the secure key repository. 🌸
-K, --key-type type — specifies the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, EP11-AES, PVSECRET-AES, and PVSECRET-HMAC. Only keys with the specified key type are listed. This option is only used for secure keys contained in the secure key repository. 👑
-L, --local — lists only local keys. Local keys are not bound to a key management system (KMS). This option is only used for secure keys contained in the secure key repository, and can not be specified together with the --kms-bound option. ⭐
-M, --kms-bound — lists only keys that are bound to a key management system (KMS). This option is only used for secure keys contained in the secure key repository, and can not be specified together with the --local option. 🌈

🗑️ Options for the remove command 🗑️

-N, --name key-name — specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository. 💀
-F, --force — normally the user is prompted to confirm the removal of a secure key from the secure key repository. Use this option to remove a secure key without prompting for a confirmation. This option is only used for secure keys contained in the secure key repository. 🙈

🧩 KMS-plugin specific options 🧩

A key management system plugin may offer and even require plugin-specific options that can be specified with the remove command when the secure key repository is bound to a key management system plugin. Use remove --help to display the plugin-specific options and their meaning. 🧚

✏️ Options for the change command ✏️

-N, --name key-name — specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository. 🎀
-d, --description description — specifies a textual description for the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository. 💖
-l, --volumes [+|-]volume1:dmname1[,volume2:dmname2[,...]] — specifies a comma-separated list of volumes (block devices) that are associated with the secure AES or HMAC key in the repository. These volumes are to be encrypted using dm-crypt with the secure AES key, or are to be integrity protected using dm-integrity with the secure HMAC key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. To add a volume to the associated volumes, prefix the volume with a +. To remove a volume from the associated volumes, prefix the volume with a -. To set (replace) the volume association, do not specify a prefix. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. A specific volume can only be associated with a single secure key. For combined encryption and integrity protection of a volume, associate the same volume to an AES-type key and an HMAC-type key. Both keys must use the luks2 volume type. This option is only used for secure keys contained in the secure key repository. 🦋
-a, --apqns [+|-]card1.domain1[,card2.domain2[,...]] — specifies a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) that are associated with the secure AES or HMAC key in the repository. Each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). To add an APQN to the associated APQNs, prefix the APQN with a +. To remove an APQN from the associated APQNs, prefix the APQN with a -. To set (replace) the APQN association, do not specify a prefix. You cannot mix + and - in one specification. You can either add or remove (or set) the associations with one command. All APQNs being added or set (replaced) must be online, unless option --no-apqn-check is specified. This option is only used for secure keys contained in the secure key repository. 🔥
--no-apqn-check — do not check if the specified APQNs are available. Use this option to associate APQNs with a secure AES or HMAC key that are currently not available. This option is only used for secure keys contained in the secure key repository. ⭐
-S, --sector-size bytes — specifies the sector size in bytes used with dm-crypt or dm-integrity. It must be a power of two and in the range of 512 to 4096 bytes. Specify 0 to set the sector size to the system default. You can only set a sector size for an HMAC key of a volume of type integrity. For an HMAC key that is used for combined encryption and integrity protection (volume type luks2), set the sector size for the corresponding AES key instead. This option is only used for secure keys contained in the secure key repository. 🌟
-t, --volume-type type — specifies the volume type of the associated volumes used with dm-crypt or dm-integrity. Possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. This option is only used for secure keys contained in the secure key repository. 💜
--gen-dummy-passphrase — bestie, this one just makes up a dummy passphrase for you, totally random ✨, and associates it with the secure AES key that's encrypting your LUKS2 volume(s). Why would you want that? Because when a secure AES key is doing the encryption, the LUKS2 passphrase is of less or no relevance for the security of the volume(s) — so it's totally fine to store it insecurely inside the secure key repository. 🫶 BUT — if for a certain usage that passphrase is of relevance for security, then do not use this option, okay? no cap. This option can only be specified for AES-type keys with a volume type of luks2. And listen — if there's already a dummy passphrase associated with the key, you must first remove it with --remove-dummy-passphrase before you can associate a new one. Also this option cannot be specified together with --set-dummy-passphrase. It's only used for secure keys contained in the secure key repository. 💅
--set-dummy-passphrase passphrase-file — same energy as above but you're the one supplying the vibe: it sets a dummy passphrase read from the specified file and associates it with the secure AES key used to encrypt LUKS2 volume(s). Again: when a secure AES key is used to encrypt the volume(s), the LUKS2 passphrase is of less or no relevance for the security of them, so it can live insecurely inside the secure key repository. And again — if for a certain usage the passphrase is of relevance for security, don't use this option! 🚨 This option can only be specified for AES-type keys with a volume type of luks2. If there's already a dummy passphrase associated with the key, remove it first with --remove-dummy-passphrase before associating a new one. This option cannot be specified together with --gen-dummy-passphrase. Only used for secure keys contained in the secure key repository, iykyk. 🎀
--remove-dummy-passphrase — yeets the associated dummy passphrase used with LUKS2 volume(s) 🗑️. The user is prompted to confirm the removal of the associated dummy passphrase (safety vibes ✋). Use the --force option to remove the associated dummy passphrase without prompting for a confirmation. This option is only used for secure keys contained in the secure key repository.
-F, --force — okay so normally the user is prompted to confirm the removal of the associated dummy passphrase, and this option is how you skip that — use it to remove the associated dummy passphrase without prompting for a confirmation 😌. This option is only used for secure keys contained in the secure key repository, and can only be specified together with option --remove-dummy-passphrase.

✨ Options for the rename command ✨

-N, --name key-name — specifies the name of the secure key in the secure key repository. You cannot use wildcards. This option is only used for secure keys contained in the secure key repository. 💖
-w, --new-name new-key-name — specifies the new name of the secure key in the secure key repository. Yep, that's the glow-up name 💅. This option is only used for secure keys contained in the secure key repository.

🌸 Options for the copy command 🌸

-N, --name key-name — specifies the name of the secure key to be copied in the secure key repository. You cannot use wildcards (fr, no wildcards). This option is only used for secure keys contained in the secure key repository.
-w, --new-name new-key-name — specifies the new name of the secure key in the secure key repository. This option is only used for secure keys contained in the secure key repository.
-l, --volumes volume1:dmname1,volume2:dmname2[,...]] — okay important: volume associations are not copied, because a volume can only be associated with a single secure key 😭 that's the rule. So to associate different volumes with the copied secure AES or HMAC key, specify a comma-separated list of volumes (block devices). These volumes are to be encrypted using dm-crypt with the secure AES key, or are to be integrity protected using dm-integrity with the secure HMAC key. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. This option is only used for secure keys contained in the secure key repository. 🦋
-L, --local — copies the secure key to a local key. This is the default when no key management system plugin (KMS plugin) is bound to the secure key repository. But if the repository is bound to a key management system plugin, then the keys are bound to the KMS per default, and KMS-bound keys can only be copied to local keys. 👑

🎀 Options for the crypttab command 🎀

-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — specifies a comma-separated list of volumes (block devices) which are associated with secure AES keys in the repository. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are selected that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names — when wildcards are used you must quote the value (don't forget or it's giving chaos 🙈). This option is only used for secure keys contained in the secure key repository.
-t, --volume-type type — specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are selected to generate crypttab entries for. This option is only used for secure keys contained in the secure key repository. ⭐
--key-file file-name — reads the passphrase from the specified file. If this option is omitted, and no dummy passphrase is associated with the secure key, then you are prompted to enter the passphrase interactively during system startup. This option is passed to the generated crypttab entries for LUKS2 volumes.
--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. This option is passed to the generated crypttab entries for LUKS2 volumes. Not all distributions support the keyfile-offset option in crypttab entries. 💀
--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. This option is passed to the generated crypttab entries for LUKS2 volumes. Again: not all distributions support the keyfile-size option in crypttab entries. 😭
--tries number — specifies how often the interactive input of the passphrase can be re-entered during system startup. 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. This option is passed to the generated crypttab entries for LUKS2 volumes. 🍓

🦋 Options for the cryptsetup command 🦋

-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — specifies a comma-separated list of volumes (block devices) which are associated with secure AES keys in the repository. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt. You can omit the device-mapper name; if it is specified then only those keys are selected that are associated with the specified volume and device-mapper name. You can use wildcards to specify the volumes and device-mapper names — and yup, when wildcards are used you must quote the value. This option is only used for secure keys contained in the secure key repository. 🌈
-t, --volume-type type — specifies the volume type of the associated volumes used with dm-crypt. Possible values are plain and luks2. Only keys with the specified volume type are selected to generate cryptsetup commands for. This option is only used for secure keys contained in the secure key repository. 🧚
-r, --run — actually runs the generated cryptsetup commands 🏃‍♀️💨. When one of the cryptsetup commands fail, no further cryptsetup commands are run, and zkey ends with an error. This option is only used for secure keys contained in the secure key repository.
--open — generates cryptsetup luksOpen or cryptsetup plainOpen commands. For a plain volume type, this is the default. This option can not be specified together with the --format option. 🚫
--format — generates cryptsetup luksFormat commands. For a LUKS2 volume type, this is the default. If specified for a plain volume type, then no command is generated (yeah, nothing, sorry 💀). This option can not be specified together with the --open option.
--key-file file-name — reads the passphrase from the specified file. If this option is omitted, and no dummy passphrase is associated with the secure key, or if the file-name is - (a dash), then you are prompted to enter the passphrase interactively. This option is passed to the generated command(s) for LUKS2 volumes. 💖
--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. This option is passed to the generated command(s) for LUKS2 volumes. ✨
--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. This option is passed to the generated command(s) for LUKS2 volumes. 🫶
--tries number — okay so this one controls how many times the interactive passphrase prompt can be re-entered 💅 default is 3 times, no cap. BUT plot twist: if --key-file is in play, this option is just ignored entirely and the passphrase gets read only once from the file. Also, this option is passed to the generated command(s) for LUKS2 volumes ✨
-q, --batch-mode — suppresses the cryptsetup confirmation questions 🙈 so no one's asking you "are you sure?" mid-script. This option is passed to the generated cryptsetup command(s) 🫶

🎀 Options for the integritytab command 🎀

-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — gives a comma-separated list of volumes (block devices) that are associated with secure HMAC keys in the repository 🔥 only HMAC keys with a volume type of integrity are considered, bestie. The volume association also carries the device-mapper name, separated by a colon, used with dm-integrity. You can omit the device-mapper name — but if you do specify it, then only those keys get selected that are associated with the specified volume and device-mapper name 👑. Wildcards work for both the volumes and the device-mapper names, and when you use wildcards you must quote the value ⚠️ this option is only used for secure keys contained in the secure key repository 🦋

🌸 Options for the integritysetup command 🌸

-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — a comma-separated list of volumes (block devices) associated with secure HMAC keys in the repository 💖 same deal as above: only HMAC keys with a volume type of integrity are considered. The association also contains the device-mapper name, colon-separated, used with dm-integrity. Omit the device-mapper name if you want; specify it and only keys associated with that volume and that device-mapper name get picked 💅 wildcards? yes bestie, for both volumes and device-mapper names — and quote the value when you use them 🌈 this option is only used for secure keys contained in the secure key repository ✨
-r, --run — actually runs the generated integritysetup commands 🔥 and if one of them fails, no further integritysetup commands are run and zkey ends with an error 💀 this option is only used for secure keys contained in the secure key repository.
--open — generates integritysetup open commands 🎀 by default it's integritysetup format commands that get generated, so this is the switch that flips it.
-q, --batch-mode — suppresses integritysetup confirmation questions 🙈 passed straight to the generated integritysetup command(s) 🫶

⭐ Options for the convert command ⭐

-N, --name key-name — the name of the secure key in the secure key repository 💜 wildcards are not allowed here, so no funny business. This option is only used for secure keys contained in the secure key repository.
-K, --key-type type — tells you which key type the secure key shall be converted to 🔄 possible values are CCA-AESCIPHER. Heads up: secure keys of type CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C 🖥️✨
--no-apqn-check — skips the check on whether the associated APQNs are available and capable of converting the secure key to type CCA-AESCIPHER 🙈 this option is only used for secure keys contained in the secure key repository.
-F, --force — normally the user is prompted to confirm the conversion of a secure key — use this to convert one without the confirmation prompt ⚡ (yes it just goes for it, be aware).

🦋 Options for the kms configure command 🦋

-a, --apqns [+|-]card1.domain1[,card2.domain2[,...]] — a comma-separated list of cryptographic adapters in CCA or EP11 coprocessor mode (APQN) associated with the key management system plugin 👑 each APQN association specifies a card and domain number separated by a period (like lszcrypt displays it). Now the prefixes, listen up 📢 to add an APQN to the associated APQNs, prefix it with a +. To remove an APQN from the associated APQNs, prefix it with a -. To set (replace) the APQN association, don't specify a prefix at all 💅 you cannot mix + and - in one specification — you can either add or remove (or set) the associations with one command, pick a lane bestie. And all APQNs being added or set (replaced) must be online ⚠️

💜 KMS-plugin specific options 💜

A key management system plugin may offer plugin specific options that can be specified with the kms configure command ✨ use kms configure --help to display the plugin specific options and their meaning — iykyk, always check the help first 🎀

🔥 Options for the kms reencipher command 🔥

-n, --to-new — re-enciphers key management system plugin internal secure keys that are currently enciphered with the master key in the CURRENT register with the master key in the NEW register 🔄
-o, --from-old — re-enciphers key management system plugin internal secure keys that are currently enciphered with the master key in the OLD register with the master key in the CURRENT register 🌸 this option is only available for CCA-type secure keys.
-i, --in-place — forces an in-place re-enciphering of key management system plugin internal secure keys ⚡ "in-place" immediately replaces the secure key with the re-enciphered secure key. Fun fact: 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 key management system plugin internal secure keys to be performed in staged mode 🎀 staged mode means the re-enciphered secure keys are stored separately, so the current secure keys are still valid at this point. Once the new CCA or EP11 master keys have been set (made active), you must rerun the kms reencipher command with option --complete to complete the staged re-enciphering ✅ also: 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 🚫
-p, --complete — completes a staged re-enciphering 💖 use this option after the new CCA or EP11 master keys have been set (made active). This option replaces the secure keys by their re-enciphered versions. It cannot be specified together with options --to-new, --from-old, --in-place, or --staged 🚫

💜 KMS-plugin specific options 💜

A key management system plugin may offer plugin specific options that can be specified with the kms reencipher command 🌈 use kms reencipher --help to display the plugin specific options and their meaning ✨

🌈 Options for the kms list command 🌈

-B, --label key-label — the label of the secure key in the key management system (KMS) 🏷️ wildcards work to select multiple secure keys, and when you use wildcards you must quote the value ⚠️ only keys with labels that match the pattern are listed 💅
-N, --name key-name — the name of the secure key in the key management system (KMS) 💜 wildcards work to select multiple secure keys — quote the value when you use them ⚠️ only keys with names that match the pattern are listed. This option is only used for secure keys contained in the secure key repository 🦋
-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — a comma-separated list of volumes (block devices) associated with the secure AES or HMAC key in the key management system (KMS) 🎀 only those keys are listed which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. You can omit the device-mapper name; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name 👑 wildcards for volumes and device-mapper names? yes — and quote the value when you use them ⚠️
-t, --volume-type type — the volume type of the associated volumes used with dm-crypt or dm-integrity 🔍 possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. Only keys with the specified volume type are listed ✨

🍓 Options for the kms import command 🍓

-B, --label key-label — the label of the secure key in the key management system (KMS) 🏷️ wildcards select multiple secure keys — quote the value when you use wildcards ⚠️ only keys with labels that match the pattern are imported 💅
-N, --name key-name — the name of the secure key in the key management system (KMS) 💜 wildcards select multiple secure keys, and you must quote the value when you use them ⚠️ only keys with names that match the pattern are imported 🌸
-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — a comma-separated list of volumes (block devices) associated with the secure AES or HMAC key in the key management system (KMS) 🎀 only those keys are imported which are associated with the specified volumes. The volume association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. Omit the device-mapper name if you like; if it is specified then only those keys are listed that are associated with the specified volume and device-mapper name 👑 wildcards work for volumes and device-mapper names — quote the value when you use them ⚠️
-t, --volume-type type — the volume type of the associated volumes used with dm-crypt or dm-integrity 🔍 possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. Only keys with the specified volume type are imported ✨
-q, --batch-mode — suppresses the prompts to skip or to enter an alternate name, if a secure key with the same name as the secure key to be imported already exists in the repository 🙈 when this option is specified, then keys with an existing name are skipped — no questions, just vibes 💅
--no-volume-check — skips the check on whether the volume(s) associated with the to be imported secure key(s) are available, or are already associated with other secure keys in the repository ⚠️ like it literally just doesn't ask, so maybe know what you're doing before you flip this one 🫶

🫶 Options for the `kms refresh` command

-N, --name key-name — names the secure key you want inside the secure key repository. Bestie, you can use wildcards here to grab, like, multiple secure keys at once — but if you do use wildcards you have to quote the value. Only keys whose names match the pattern get refreshed. No cap.
-l, --volumes volume1[:dmname1][,volume2[:dmname2][,...]] — gives a comma-separated list of volumes (block devices) that are associated with the secure AES or HMAC key in the repository. Only the keys associated with the volumes you list get refreshed. The volume association also carries the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. You can totally omit the device-mapper name; but if you do specify it, then only those keys are listed that are associated with the specified volume and device-mapper name. Wildcards work for the volumes and the device-mapper names — and again, when wildcards are used you must quote the value. 💅
-t, --volume-type type — sets the volume type of the associated volumes used with dm-crypt or dm-integrity. Possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. Only keys with the specified volume type are refreshed. Slay.
-K, --key-type type — sets the key type of the secure key. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES. Only keys with the specified key type are refreshed. ✨
-P, --refresh-properties — also updates the associated information — think the textual description, associated volumes, volume type, and sector size — with the information stored in the key management system. Iconic little overachiever.
--no-volume-check — skips the check on whether the volume(s) associated with the secure key(s) being refreshed are available, or are already associated with other secure keys in the repository. Heads up though: this option only does anything when it's specified together with --refresh-properties. 💀

🦋 Options for the `pvsecrets list` command

-A, --all — lists all protected virtualization (PV) secret types, not just the ones that can be used with zkey. FOMO who?
-H, --hex — shows all protected virtualization (PV) secret IDs in hex, even if the ID is made of only printable characters. Hex girl summer 🔥
-T, --pvsecret-type pvsecret-type — the type of the protected virtualization (PV) secret to list. If you omit it, all secret types get listed. Possible values are: PLAIN-TEXT, AES-128, AES-192, AES-256, AES-XTS-128, AES-XTS-256, HMAC-SHA-256, HMAC-SHA-512, ECDSA-P256, ECDSA-P384, ECDSA-P521, EDDSA-ED25519, and EDDSA-ED448.
-I, --pvsecret-id pvsecret-id — the ID of the protected virtualization (PV) secret to list. The pvsecret ID is a 32 byte hex string, optionally prefixed by 0x. You can pull it straight out of the YAML file that was created when you used the pvsecret create command, like this:

--pvsecret-id "$(yq .id YAML-FILE)"

You might have to install the yq package first, btw. Also: either the --pvsecret-id option or the --pvsecret-name option can be specified, but not both. Pick a lane 🎀

-e, --pvsecret-name pvsecret-name — the name of the protected virtualization (PV) secret to list. Same YAML-file trick as above:

--pvsecret-name "$(yq .name YAML-FILE)"

Again, you might have to install the yq package first. And again: either --pvsecret-id or --pvsecret-name can be specified, but not both. 💜

🌈 Options for the `pvsecrets import` command

-I, --pvsecret-id pvsecret-id — the ID of the protected virtualization (PV) secret to import. The pvsecret ID is a 32 byte hex string, optionally prefixed by 0x. Grab it from the YAML file the pvsecret create command made:

--pvsecret-id "$(yq .id YAML-FILE)"

You might have to install the yq package first. And yes — either --pvsecret-id or --pvsecret-name can be specified, but not both. 🫶

-e, --pvsecret-name pvsecret-name — the name of the protected virtualization (PV) secret to import. YAML file of it all:

--pvsecret-name "$(yq .name YAML-FILE)"

Might need the yq package, soz. Either --pvsecret-id or --pvsecret-name can be specified, but not both. Extra important bit: if the --pvsecret-name option is specified, then the --name option can be omitted — and the name of the protected virtualization secret key object in the repository will then be the same as the pvsecret name. Obsessed with the convenience tbh ✨

-N, --name key-name — specifies the name of the protected virtualization secret key object in the key repository. If the --pvsecret-name option is specified, then the --name option can be omitted, and the name of the protected virtualization secret in the repository will then be the same as the pvsecret name. Same deal, spelled out again 💅
-d, --description description — a textual description for the protected virtualization secret in the key repository. Give it lore.
-l, --volumes volume1:dmname1[,volume2:dmname2[,...]] — a comma-separated list of volumes (block devices) associated with the protected virtualization secret in the repository. These volumes are to be encrypted using dm-crypt with the protected virtualization secret, or integrity protected using dm-integrity with the protected virtualization secret. The association also contains the device-mapper name, separated by a colon, used with dm-crypt or dm-integrity. Key rules, listen up: a specific volume can only be associated with a single key. And for combined encryption + integrity protection of a volume, associate the same volume to an AES-type key and an HMAC-type key — and both keys must use the luks2 volume type. No shortcuts. 🧚
-S, --sector-size bytes — the sector size in bytes used with dm-crypt or dm-integrity. It must be a power of two and in the range of 512 to 4096 bytes. If omitted, the system default sector size is used. Also: you can only set a sector size for an HMAC key of a volume of type integrity. For an HMAC key used for combined encryption and integrity protection (volume type luks2), set the sector size for the corresponding AES key instead. The way that's such a specific rule 😭
-t, --volume-type type — the volume type of the associated volumes used with dm-crypt or dm-integrity. Possible values for AES keys are plain and luks2, and integrity and luks2 for HMAC keys. If omitted, luks2 is used for AES keys, and integrity for HMAC keys. If omitted, luks2 is used. (Yes bestie, the page says it twice — I'm not the one who wrote it, I'm just the messenger 💀)
--gen-dummy-passphrase — generates a dummy passphrase randomly and associates it with the protected virtualization secret used to encrypt LUKS2 volume(s). Real talk: the LUKS2 passphrase is of less or no relevance for the security of the volume(s) when a protected virtualization secret is used to encrypt them, and can therefore be stored insecurely inside the key repository. But if for a certain usage the passphrase is of relevance for security, then do not use this option. Also it can only be specified for AES-type keys with a volume type of luks2. 🙈
--set-dummy-passphrase passphrase-file — sets a dummy passphrase read from the specified file and associates it with the protected virtualization secret used to encrypt LUKS2 volume(s). Same energy as above: the LUKS2 passphrase is of less or no relevance for the security of the volume(s) when a protected virtualization secret is used to encrypt them, and can therefore be stored insecurely inside the key repository. And if, for a certain usage, the passphrase is of relevance for security, then do not use this option. Same limit too — only for AES-type keys with a volume type of luks2. 🍓

👑 General options

-V, --verbose — displays additional information messages during processing. Main character chatter ✨
-h, --help — displays help text and exits. The classic.
-v, --version — displays version information and exits. 💖

💖 EXAMPLES 💖

okay bestie, this is the part where it all clicks — real commands, copy-paste ready, no cap. every single one of these is straight from the source, so you can literally run them and go ✨

a whole random key, in a file — makes a random 256-bit secure AES key and stores it in the file seckey.bin:

zkey generate seckey.bin

a smaller key, XTS flavored — makes a random 128-bit secure AES key for the XTS cipher mode and stores it in the file seckey.bin:

zkey generate seckey.bin --keybits 128 --xts

secure key out of a clear key — makes a secure AES key from the clear key in the file clearkey.bin and stores it in the file seckey.bin:

zkey generate seckey.bin --clearkey clearkey.bin

key, but in the repository this time — makes a random 256-bit secure AES key and stores it in the secure key repository under the name seckey:

zkey generate --name seckey

key + volume + APQN, the full fit — makes a random 256-bit secure AES key, stores it in the secure key repository under the name seckey, associates it with the block device /dev/dasdc1 and device-mapper name encvol, and APQN 03.004c:

zkey generate --name seckey --volumes /dev/dasdc1:encvol --apqns 03.004c

same vibe, luks2 edition — makes a random 256-bit secure AES key, stores it in the secure key repository under the name seckey, associates it with the block device /dev/dasdc1 and device-mapper name encvol, and a volume type of luks2:

zkey generate --name seckey --volumes /dev/dasdc1:encvol --volume-type luks2

moving a key out of the OLD register — re-enciphers the secure key in the file seckey.bin, which is currently enciphered with the master key in the OLD register, with the master key in the CURRENT register, then replaces the secure key in the file seckey.bin with the re-enciphered key:

zkey reencipher seckey.bin --from-old

moving a key into the NEW register (and keeping both) — re-enciphers the secure key in the file seckey.bin, which is currently enciphered with the master key in the CURRENT register, with the master key in the NEW register, and saves the re-enciphered secure key to the file seckey2.bin:

zkey reencipher seckey.bin --to-new --output seckey2.bin

re-encipher a repo key by name — re-enciphers the secure key seckey in the secure key repository:

zkey reencipher --name seckey

re-encipher everything tied to an APQN — re-enciphers all secure keys in the secure key repository that are associated with APQN 03.004c:

zkey reencipher --apqns 03.004c

vibe check a key file — validates the secure key in the file seckey.bin and displays its attributes:

zkey validate seckey.bin

vibe check a repo key — validates the secure key seckey in the secure key repository and displays its attributes:

zkey validate --name seckey

show me everything — lists all secure keys in the secure key repository and displays its attributes:

zkey list

show me just the *key girlies — lists all secure keys in the secure key repository whose names end with key and displays its attributes:

zkey list --name '*key'

adding a volume to a key — changes the secure key seckey in the secure key repository and adds the volume /dev/dasdc2 with device-mapper name encvol2 to the list of associated volumes of this secure key (that + is doing the work, iykyk):

zkey change --name seckey --volumes +/dev/dasdc2:encvol2

removing an APQN from a key — changes the secure key seckey in the secure key repository and removes APQN 03.004c from the list of associated APQNs of this secure key (and yeah, the - is the removal, periodt):

zkey change --name seckey --apqns -03.004c

crypttab entries, wildcard edition — generates crypttab entries for all volumes that match the pattern /dev/dasdc*:

zkey crypttab --volumes '/dev/dasdc*'

cryptsetup commands by device-mapper name — generates cryptsetup commands for the volumes that use the device-mapper name enc_dasd:

zkey cryptsetup --volumes '*:enc_dasd'

cryptsetup commands by volume type — generates cryptsetup commands for all volumes of type luks2:

zkey cryptsetup --volume-type luks2

🌈 ENVIRONMENT 🌈

the environment variables that whisper to zkey, bestie. two of them. that's it. that's the whole section 🫶

ZKEY_REPOSITORY — if $ZKEY_REPOSITORY is set, it specifies the location of the secure key repository. if it's not set, then the default location of the secure key repository is /etc/zkey/repository.
ZKEY_KMS_PLUGINS — if $ZKEY_KMS_PLUGINS is set, it specifies the name of the KMS plugin configuration file. if it's not set, then the default KMS plugin configuration file /etc/zkey/kms-plugins.conf is used.

ngl, forgetting to set these and then wondering where your keys went is a whole character arc. the defaults are right there in the text — remember them 💅

and that's the whole page, bestie!! 🎀 you made it to the very end, iconic behavior honestly 👑

this little masterpiece comes to you from s390-tools, dated February 2024 — go forth and encipher responsibly, mwah 💋✨

📦 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(1)

🌸 NAME 🌸

✨ SYNOPSIS ✨

💖 DESCRIPTION 💖

🎀 COMMANDS 🎀

🦋 Generating secure AES or HMAC keys 🦋

🧚 Validating secure AES or HMAC keys 🧚

🔥 Re-encipher existing AES or HMAC secure keys 🔥

🌸 Import existing AES or HMAC secure keys into the secure key repository 🌸

🦋 Export AES or HMAC secure keys from the secure key repository 🦋

⭐ List AES or HMAC secure keys contained in the secure key repository ⭐

💜 Remove existing AES or HMAC secure keys from the secure key repository 💜

🎀 Change existing AES or HMAC secure keys contained the secure key repository 🎀

🗝️ Rename existing AES or HMAC secure keys in the secure key repository 🗝️

🫶 Copy (duplicate) existing AES or HMAC secure keys in the secure key repository

🎀 Generate crypttab entries for volumes associated with secure AES keys

🔥 Generate cryptsetup commands for volumes associated with secure AES keys

🌸 Generate integritytab entries for volumes associated with secure HMAC keys

🌈 Generate integritysetup commands for volumes associated with secure HMAC keys

🦋 Convert existing AES or HMAC secure keys from one key type to another type

✨ COMMANDS FOR KEY MANAGEMENT SYSTEM INTEGRATION ✨

🌸 List key management system plugins 🌸

🦋 Bind the repository to a key management system 🦋

💜 Unbind the repository from a key management system 💜

🔥 Display information about a key management system plugin 🔥

🎀 Configure or re-configure a key management system plugin 🎀

🧚 Re-encipher secure keys used by a key management system plugin 🧚

🍓 List secure keys managed by a key management system 🍓

⭐ Import secure keys managed by a key management system into the repository ⭐

🦋 Refresh secure keys that are bound to a key management system

👑 COMMANDS FOR PROTECTED VIRTUALIZATION 👑

🧚 List available protected virtualization secrets

🍓 Import protected virtualization secrets into the repository

✨ OPTIONS ✨

🌈 Options for the generate command

🌈 KMS-plugin specific options 🌈

🎀 Options for the validate command 🎀

🔥 Options for the reencipher command 🔥

💜 Options for the import command 💜

💌 Options for the export command 💌

👀 Options for the list command 👀

🗑️ Options for the remove command 🗑️

🧩 KMS-plugin specific options 🧩

✏️ Options for the change command ✏️

✨ Options for the rename command ✨

🌸 Options for the copy command 🌸

🎀 Options for the crypttab command 🎀

🦋 Options for the cryptsetup command 🦋

🎀 Options for the integritytab command 🎀

🌸 Options for the integritysetup command 🌸

⭐ Options for the convert command ⭐

🦋 Options for the kms configure command 🦋

💜 KMS-plugin specific options 💜

🔥 Options for the kms reencipher command 🔥

💜 KMS-plugin specific options 💜

🌈 Options for the kms list command 🌈

🍓 Options for the kms import command 🍓

🫶 Options for the kms refresh command

🦋 Options for the pvsecrets list command

🌈 Options for the pvsecrets import command

👑 General options

💖 EXAMPLES 💖

🌈 ENVIRONMENT 🌈

🎀 Options for the `validate` command 🎀

🔥 Options for the `reencipher` command 🔥

💜 Options for the `import` command 💜

🫶 Options for the `kms refresh` command

🦋 Options for the `pvsecrets list` command

🌈 Options for the `pvsecrets import` command