ZKEY(1)

NAME
zkey - Generates, re-enciphers, and validates secure AES keys

SYNOPSIS
zkey generate|gen secure-key-file [--keybits|-k size] [--xts|-x] [--clearkey|-c clear-key-file] [--verbose|-V]
zkey validate|val secure-key-file [--verbose|-V]
zkey reencipher|re secure-key-file [--to-new|-n] [--from-old|-o] [--output|-f output-file] [--verbose|-V]

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

DESCRIPTION
Use the zkey command to generate 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 command to validate and re-encipher secure AES keys.

The generated secure key is saved in a file with a size of 64 or 128 bytes. The file contains an AES key of 128, 192, or 256 bits 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, because XTS requires two concatenated secure keys.

USAGE

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

  Validating secure AES keys
Use the validate command to validate an existing secure key. It checks if the specified file 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, and the master key register with which the secure key is enciphered.

  Re-encipher existing AES secure keys
Use the reencipher command to re-encipher an existing secure key with a new master key. A secure key have to be re-enciphered, when the master key of the CCA cryptographic adapter is being changed.

The CCA cryptographic adapter has 3 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 canstill 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. Note that a secure key can be proactively re-enciphered with the master key in the NEW register before the new master key is made the current one.

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.

Use the --to-new option to proactively re-encipher a secure key that is currently enciphered with the master key in the CURRENT register with the master key in the NEW register.

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

Note: The reencipher command requires the IBM CCA Host Library (libcsulcca.so) to be installed.

OPTIONS

  Options for the generate command

-k, --keybits size
    Specifies the size of the AES key to be generated in bits. Valid sizes are 128, 192, and 256 bits. 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. A secure AES key for the XTS cipher mode 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.

  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.

  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 256-bit secure AES key and stores it in file 'seckey.bin'.

zkey generate seckey.bin --keybits 128 --xts
    Generates a 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 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 validate seckey.bin
    Validates the secure key in file 'seckey.bin' and displays its attributes.