Managing Cryptographic Keys Using the Key Generator Utility Program

The key generator utility program (KGUP) generates and maintains keys in the cryptographic key data set (CKDS). The CKDS stores symmetric keys: both CCA key tokens and X9.143 (TR-31) key blocks. All formats of the CKDS are supported by KGUP.
Notes:
  • Support for TR-31 key blocks is available with CCA release 8.1 or later licensed internal code in a CEX8 or later adapter on a z16 or later server.
  • The large common record format (KDSRL) of the CKDS is required to store TR-31 key blocks in the CKDS. The large common record format (KDSRL) CKDS requires z/OS V2R5 ICSF (FMID HCR77D2).
You use KGUP to perform these tasks:
  • Generate or enter CCA key tokens. TR-31 key blocks are not supported.
  • Maintain CKDS entries by deleting or renaming the entries.
  • Load completed operational CCA key tokens into the CKDS that were entered from a TKE workstation. TR-31 key blocks are not supported.

When KGUP generates or receives a key value, the program either adds a new record or updates an existing record in the CKDS. For information about how KGUP generates and receives keys to establish key exchange with other systems, see Using KGUP for key exchange.

Each key that KGUP generates (except clear DES and AES data-encrypting keys) exists in the CKDS enciphered under your system's master key.

You use control statements to specify the functions for KGUP to perform. The control statement specifies the task you want KGUP to perform and information about the CKDS entry that is affected. For example, to have KGUP generate a CIPHER data-encrypting key, you use a control statement like:
ADD LABEL(KEY1) TYPE(CIPHER)

When KGUP processes the control statement, the program generates a key value and encrypts the value under a master key variant for an importer key-encrypting key. KGUP places the key in a CKDS record labeled KEY1. The key type field of the entry specifies CIPHER. For a description of the fields in a CKDS entry, see Specifying KGUP data sets.

When your system is using clear keys only (CLRDES and CLRAES) and has no coprocessors, random number can be generated to create clear DES and AES keys.

You store the control statements in a data set. You must also specify other data sets that KGUP uses when the program processes control statements. You submit a batch job stream to run KGUP. In the job control statements, you specify the names of the data sets that KGUP uses.

KGUP changes a disk copy of the CKDS according to the functions you specify with the control statements. When KGUP changes the disk copy of the CKDS, you can replace the in-storage copy of the CKDS with the disk copy using the ICSF panels. This operation should be performed on all systems sharing the updated CKDS. The Coordinated CKDS Refresh utility preforms the refresh of all systems when sysplex-wide consistency enabled.

To use KGUP, you must perform these tasks:
  • Create control statements.
  • Specify data sets.
  • Submit a job stream.

You may also want to refresh the CKDS with the disk copy of the CKDS that KGUP updated. You can use the KGUP panels to help you perform these tasks. However, you can also use KGUP without accessing the panels. This topic first describes each of the tasks to run KGUP and then describes how to use the panels to perform the tasks.

System requirements

To run KGUP, ICSF must be active. On systems with cryptographic coprocessors, the master keys must be loaded on the cryptographic coprocessors.

The CKDS to be updated must be initialized.