ZKEY(1)

NAME
zkey - Manage secure AES keys

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

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

DESCRIPTION
Use the zkey tool to generate and manage secure AES keys that are enciphered with a master key of an IBM cryptographic adapter in CCA coprocessor mode. You can also use the zkey tool to validate and re-encipher secure AES keys.

The secure keys can either be stored 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. Set environment variable ZKEY_REPOSITORY to point to a different location to use a different secure key repository location. 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 that is supposed to access secure keys in the secure key repository must be part of group zkeyadm.

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 master key. You can also associate a secure key with one or multiple volumes (block devices), which are encrypted using dm-crypt with the secure 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 one secure key.

The generated secure key is saved in a file with a size of 64 or 128 bytes. The file contains an AES key with a length of 128, 192, or 256 bits. The key is enciphered with the master key of the CCA cryptographic adapter. Secure keys that are used for the XTS cipher mode can be 128 or 256 bits in size.

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.

  Generating secure AES keys
zkey generate|gen secure-key-file [--keybits|-k size] [--xts|-x] [--clearkey|-c clear-key-file] [--key-type|-K type] [--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] [--verbose|-V]

Use the generate command to generate a new secure AES key either randomly within the CCA cryptographic adapter, or from a clear AES key specified as input. 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 cryptographic adapter that contains the master key with which the secure key was generated.

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

You can generate different types of secure keys: CCA-AESDATA keys, and CCA-AESCIPHER keys. Specify the type of the secure key using the --key-type option. The default key type is CCA-AESDATA.

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.

  Validating secure AES keys
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.

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.

  Re-encipher existing AES secure keys
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|-c] [--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 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 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.

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.

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, zkey automatically detects 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 it is currently enciphered with the master key in the CURRENT register, it is re-enciphered with the master key in the NEW register. If for this case the NEW register does not contain a valid master key, then the re-encipher operation fails.

The secure key can either be contained 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 option secure-key-file. 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). 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 re-enciphered. If both options are omitted, then all secure keys contained in the key repository are re-enciphered.

Re-enciphering a secure key contained in the secure key repository can be performed 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 is performed in-place per default. You can use option --in-place to force an in-place re-enciphering for the CURRENT to NEW case. Be aware that a secure key that was re-enciphered in-place from CURRENT to NEW is no longer valid, until the new CCA master key has been made the current one.

Staged mode means that the re-enciphered secure key is stored in a separate file in the secure key repository. Thus the current secure key is still valid at this point. Once the new CCA 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. You can use option --staged to force a staged re-enciphering for the OLD to CURRENT case.

Note: The reencipher command requires the CCA host library (libcsulcca.so) to be installed. For the supported environments and downloads, see: http://www.ibm.com/security/cryptocards

  Import existing AES 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] [--verbose|-V]

Use the import command to import an existing secure key contained in a file into the the secure key repository. When importing a 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.

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

  Export AES 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 is to be exported using the --name option. You cannot use wildcards. The exported secure key also remains in the secure key repository.

  List AES 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] [--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), and volume type. You can use wildcards for the key name, associated APQNs, 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.

The list command displays the attributes of the secure keys, such as key sizes, key type, whether it is 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, and timestamps for key creation, last modification and last re-encipherment.

  Remove existing AES secure keys from the secure key repository
zkey remove|rem --name | -N key-name [--force|-F] [--verbose|-V]

Use the remove command to remove an existing secure key from the secure key repository. Specify the name of the key that is to be removed using the --name option. You cannot use wildcards. The remove command prompts for a confirmation, unless you specify the --force option.

Note: When removing a secure key that is 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. For keys with volume type luks2 no such message is issued, because the secure key is contained in the LUKS2 header.

  Change existing AES 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] [--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 that is to be changed using the --name option. You cannot use wildcards.

You can set (replace), add, or remove volume and cryptographic adapters (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.

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 master key, use the reencipher command.

  Rename existing AES 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. Specify the name of the key that is to be renamed using the --name option and the new name using the --new-name option. You cannot use wildcards. Note: When renaming a secure key that is 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 renamed, these 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.

  Copy (duplicate) existing AES 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[,...]]] [--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 is to be copied using the --name option and the name of the copied key using the --new-name option. You cannot use 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.

  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 keys contained in the secure key repository. Specify the --volumes option to limit the list of volumes where crypttab entries are generated for. You can use wildcards. When wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it is 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 are prompted for the passphrase during system startup when crypttab is evaluated, unless option --key-file is specified. Option --tries specifies how often a passphrase can be re-entered. When option --key-file is specified, the passphrase is read from the specified file. You can specify options --keyfile-offset and --keyfile-size to control which part of the key file is used as passphrase. These options are passed to the generated crypttab entries and are only available if zkey has been compiled with LUKS2 support enabled.

  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] [--verbose|-V]

Use the cryptsetup command to generate cryptsetup plainOpen, cryptsetup luksOpen, or cryptsetup luksFormat commands for volumes that are associated with secure keys contained in the secure key repository. Specify the --volumes option to limit the list of volumes where cryptsetup commands are generated for. You can use wildcards. When wildcards are used you must quote the value. The device-mapper name of an associated volume can be omitted; if it is 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. Specify the --run option to run the generated cryptsetup commands. Specify the --open to generate cryptsetup plainOpen or cryptsetup luksOpen commands. For the plain volume type, this is the default. Specify the --format option to 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.

For LUKS2 volumes, the generated cryptsetup luksFormat contains option --pbkdf pbkdf2 to set PBKDF2 as password based key derivation function. LUKS2 volumes typically default to Argon2i as password based key derivation function, but this might cause out-of-memory errors when multiple encrypted volumes are unlocked automatically at boot through /etc/crypttab. Because PAES uses secure AES keys as volume keys, the security of the key derivation function used to encrypt the volume key in the LUKS key slots is of less relevance.

For LUKS2 volumes, a passphrase is required. You are prompted for the passphrase when running the generated commands, unless option --key-file is specified. Option --tries specifies how often a passphrase can be re-entered. When option --key-file is specified, the passphrase is read from the specified file. You can specify options --keyfile-offset and --keyfile-size to control which part of the key file is used as passphrase. These options are only available if zkey has been compiled with LUKS2 support enabled. 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.

  Convert existing AES 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] [--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. 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. 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 is to be 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! 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.

For volumes with volume type plain, you must adapt the crypttab entries and change the key size parameter to size=<new-key-size-in-bits> or run command zkey crypttab --volumes <device> for each associated volume to re-generate the crypttab entries.

Associated volumes of type UKS2 still contain the secure AES volume key of the original type. To change the secure AES volume key in the LUKS2 header, run command zkey-cryptsetup setkey <device> --master-key-file <converted-key> for each associated volume.

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

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. The default is 256 bits.

-x, --xts
    Generates a secure AES key for the XTS cipher mode that consist of two concatenated secure keys.

-c, --clearkey clear-key-file
    Specifies a file path that contains the clear AES key in binary form. If option --keybits is omitted, the size of the specified file determines the size of the AES key. If option --keybits is specified, the size of the specified file must match the specified key size. Valid file sizes are of 16, 24, or 32 bytes, and of 32 or 64 bytes for keys to be used with the XTS cipher mode.

-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) that are 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. 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 coprocessor mode (APQN) which 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, then 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 the --no-apqn-check option 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 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. 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. If omitted, luks2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is plain. 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 and CCA-AESCIPHER. 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.

  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. 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 coprocessor mode (APQNs). You can use wildcards in the APQN specification. All secure keys contained in the secure key repository which are associated with the specified APQNs are 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
    Do not check if 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 key that is currently enciphered with the master key in the CURRENT register with the master key in the NEW register.

-o, --from-old
    Re-enciphers a secure AES key that is currently enciphered with the master key in the OLD register with the master key in the CURRENT register.

-f, --output output-file
    Specifies the name of the output file to which the re-enciphered secure key is written. If this option is omitted, 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. You can use wildcards to select multiple secure keys in the secure key repository. 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 coprocessor mode (APQNs). You can use wildcards 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 key contained in the secure key repository. "In-place" immediately replaces the secure key in the repository with the re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed in-place per default. This option is only used for secure keys contained in the secure key repository.

-s, --staged
    Forces that the re-enciphering of a secure AES key contained in the secure key repository is performed in staged mode. Staged mode means that the re-enciphered secure key is stored in a separate file in the secure key repository. Thus the current secure key is still valid at this point. Once the new CCA 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 is 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 master key has been set (made active). This option replaces the secure key by its re-enciphered version in the secure key repository. This option is 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
    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) which are 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. 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 coprocessor mode (APQN) which 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). 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
    Do not check if the specified APQNs are available. Use this option 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. 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. If omitted, luks2 is used. This option is only available if zkey has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled, the default volume type is plain. 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. 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. 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) which are associated with the secure AES key in the repository. 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. 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 coprocessor mode (APQN) which are associated with the secure AES key in the repository. Only those keys are listed, which 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. Possible values are plain and luks2. Only keys with the specified volume type are listed. This option is only available if zkey has been compiled with LUKS2 support enabled. 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 and CCA-AESCIPHER. Only keys with the specified key type are listed. This option is only used for secure keys contained in the secure key repository.

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

  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) which are 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. 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. 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 coprocessor mode (APQN) which 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). 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 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. Specify 0 to set the sector size to the system default. 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. This option is only available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.

  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. 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. 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[,...]]
    Volume associations are not copied, because a volume can only be associated with a single secure key. To associate different volumes with the copied secure AES key, specify a comma-separated list of volumes (block devices). 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. This option is only used for secure keys contained in the secure key repository.

  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. 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 available if zkey has been compiled with LUKS2 support enabled. 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, then you are prompted to enter the passphrase interactively during system startup. This option is passed to the generated crypttab entries for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.

--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, and is only available if zkey has been compiled with LUKS2 support enabled. 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, and is only available if zkey has been compiled with LUKS2 support enabled. 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, and is only available if zkey has been compiled with LUKS2 support enabled.

  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. 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 available if zkey has been compiled with LUKS2 support enabled. This option is only used for secure keys contained in the secure key repository.

-r, --run
    Runs the generated cryptsetup commands. When one of the cryptsetup command 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, and is only available if zkey has been compiled with LUKS2 support enabled.

--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. This option can not be specified together with the --open option, and is only available if zkey has been compiled with LUKS2 support enabled.

--key-file file-name
    Reads the passphrase from the specified file. If this option is omitted, or if the file-name is - (a dash), then you are prompted to enter the passphrase interactively. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.

--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, and is only available if zkey has been compiled with LUKS2 support enabled.

--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, and is only available if zkey has been compiled with LUKS2 support enabled.

--tries number
    Specifies how often the interactive input of the passphrase can be re-entered. The default is 3 times. When option --key-file is specified, this option is ignored, and the passphrase is read only once from the file. This option is passed to the generated command(s) for LUKS2 volumes, and is only available if zkey has been compiled with LUKS2 support enabled.

-q, --batch-mode
    Suppress cryptsetup confirmation questions. This option is passed to the generated cryptsetup command(s).

  Options for the convert 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.

-K, --key-type type
    Specifies the key type to which the secure key shall be converted to. Possible values are CCA-AESCIPHER. 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
    Do not check if 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
    The user is prompted to confirm the convertion of a secure key. Use this option to convert a secure key without prompting for a confirmation.

  General options

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

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

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

EXAMPLES

zkey generate seckey.bin
    Generates a random 256-bit secure AES key and stores it in file 'seckey.bin'.

zkey generate seckey.bin --keybits 128 --xts
    Generates a random 128-bit secure AES key for the XTS cipher mode and stores it in file 'seckey.bin'.

zkey generate seckey.bin --clearkey clearkey.bin
    Generates a secure AES key from the clear key in file 'clearkey.bin' and stores it in file 'seckey.bin'.

zkey generate --name seckey
    Generates a random 256-bit secure AES key and stores it in the secure key repository using the name 'seckey'.

zkey generate --name seckey --volumes /dev/dasdc1:encvol --apqns 03.004c
    Generates a random 256-bit secure AES key and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol', and APQN '03.004c'.

zkey generate --name seckey --volumes /dev/dasdc1:encvol --volume-type luks2
    Generates a random 256-bit secure AES key and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol', and a volume type of luks2.

zkey reencipher seckey.bin --from-old
    Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered with the master key in the OLD register with the master key in the CURRENT register, and replaces the secure key in file 'seckey.bin' with the re-enciphered key.

zkey reencipher seckey.bin --to-new --output seckey2.bin
    Re-enciphers the secure key in 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 file 'seckey2.bin'.

zkey reencipher --name seckey
    Re-enciphers the secure key 'seckey' in the secure key repository.

zkey reencipher --apqns 03.004c
    Re-enciphers all secure keys contained in the secure key repository that are associated with APQN '03.004c'.

zkey validate seckey.bin
    Validates the secure key in file 'seckey.bin' and displays its attributes.

zkey validate --name seckey
    Validates the secure key 'seckey' in the secure key repository and displays its attributes.

zkey list
    Lists all secure keys in the secure key repository and displays its attributes.

zkey list --name '*key'
    Lists all secure keys in the secure key repository with names ending with 'key' and displays its attributes.

zkey change --name seckey --volumes +/dev/dasdc2:encvol2
    Changes the secure key 'seckey' in the secure key repository and adds volume '/dev/dasdc2' with device-mapper name 'encvol2' to the list of associated volumes of this secure key.

zkey change --name seckey --apqns -03.004c
    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.

zkey crypttab --volumes '/dev/dasdc*'
    Generates crypttab entries for all volumes that match the pattern '/dev/dasdc*'.

zkey cryptsetup --volumes '*:enc_dasd'
    Generates cryptsetup commands for the volumes that uses the device-mapper name 'enc_dasd'.

zkey cryptsetup --volume-type luks2
    Generates cryptsetup commands for all volumes of type luks2.

ENVIRONMENT

ZKEY_REPOSITORY
    If $ZKEY_REPOSITORY is set, it specifies the location of the secure key repository. If it is not set, then the the default location of the secure key repository is /etc/zkey/repository.