During key generator utility program (KGUP) processing, you store the information you supply and receive in these data sets:

• The cryptographic key data set (CKDS) contains key entries that you have KGUP add, update, rename, or delete.
• The control statement input data set contains the control statements that specify the functions you want KGUP to perform.
• The diagnostics data set contains information you can use to check that the control statement succeeded.
• The key output data set contains information that another system uses to create keys that are complements of keys on your system.
• The control statement data set contains control statements that another system uses to create keys that are complements of keys on your system.

You specify the names of the data sets in the job control language to submit the job.

These topics describe the data sets that KGUP accesses or generates in detail.

Cryptographic Key Data Set (CKDS)

This VSAM key sequenced data set contains the cryptographic keys for a particular KGUP job. It has a fixed logical record length (LRECL) of 252 bytes.

Programming Interface information

The records in the CKDS are in this format:

Key label

(Character length 64 bytes) The key label specified on the control statement.

Key type

(Character length 8 bytes) The key type specified on the control statement.

Creation date

(Character length 8 bytes) The initial date the record was created, in the format YYYYMMDD.

Creation time

(Character length 8 bytes) The initial time the record was created, in the format HHMMSSTH.

Last update date

(Character length 8 bytes) The most recent date the record was updated, in the format YYYYMMDD.

Last update time

(Character length 8 bytes) The most recent time the record was updated, in the format HHMMSSTH.

Key token

(Character length 64 bytes) A key token is composed of the key value and control information. The master key encrypts the key value in this field. For a description of format of a key token, see z/OS Cryptographic Services ICSF System Programmer’s Guide.

CKDS flag bytes

(Bit length 2 bytes) If bit zero is set to one, the key within the token is a partial key. All the other bits are reserved.

Reserved

(Character length 26 bytes) Reserved. This field contains binary zeros.

Installation Data

(Character length 52 bytes) Using the KGUP exit, conversion program exit, or single-record, single-record, read-write exit, you can place information associated with the key entry into this field.

Authentication code

(Character length 4 bytes) The message authentication code computed on the previous fields of the record using a system key that is a MAC generation key. ICSF uses the code to verify the record when the record is updated.

The first record in the CKDS is a header record. The header record in the CKDS is in this format:

Key label

(Character length 64 bytes) Binary zeros. This field is not to be used.

Key type

(Character length 8 bytes) Binary zeros. This field is not to be used.

Creation date

(Character length 8 bytes) The initial date the record was created, in the format YYYYMMDD.

Creation time

(Character length 8 bytes) The initial time the record was created, in the format HHMMSSTH.

Last update date

(Character length 8 bytes) The most recent date the record was updated, in the format YYYYMMDD.

Last update time

(Character length 8 bytes) The most recent time the record was updated, in the format HHMMSSTH.

Sequence number

(Character length 2 bytes) Initially binary zero, incremented each time the data set is processed.

CKDS header flag bytes

(Bit length 2 bytes) If bit zero is set to one, the DES master key verification pattern is valid. If bit one is set to one, the DES master key authentication pattern is valid. If bit two is set to one, the AES master key verification pattern is valid. If bit 8 is set to one, record authentication has been disabled. All the other bits are reserved.

DES master key verification pattern

(Character length 8 bytes) The DES master key verification pattern.

When you initialize the CKDS and master key or change the master key, ICSF calculates a verification pattern and places it into this field. ICSF calculates the verification pattern by using the current master key and the verification algorithm that is described in Algorithm for calculating a verification pattern.

DES master key authentication pattern

(Character length 8 bytes) The DES master key authentication pattern.

When you initialize the CKDS and master key or change the master key, ICSF calculates an authentication pattern and places it into this field. ICSF calculates the authentication pattern by using the current master key and the authentication pattern algorithm that is described in Algorithm for calculating an authentication pattern.

Whenever you start ICSF, ICSF uses the authentication pattern to verify that the current master key is the master key that enciphers the current CKDS. ICSF fails if the authentication pattern that is stored in the CKDS and the authentication pattern that ICSF calculates at startup do not match.

AES master key verification pattern

(Character length 8 bytes) The AES master key verification pattern.

When you initialize the CKDS and AES master key or change the AES master key, ICSF calculates a verification pattern and places it into this field. ICSF calculates the verification pattern by using the current master key and the verification algorithm that is described in Algorithm for calculating an authentication pattern.

Reserved

(Character length 64 bytes) Reserved. This field contains binary zeros.

Installation Data

(Character length 52 bytes) Using the KGUP installation exit, you can place information associated with the key entry into this field.

Authentication code

(Character length 4 bytes) The message authentication code computed on the previous fields of the record using a system key that is a MAC generation key. ICSF creates the code when ICSF creates the system keys at CKDS initialization. ICSF uses the code to verify the CKDS when the CKDS is read.

End of Programming Interface information

In the KGUP job stream, it is defined by the CSFCKDS data definition statement.

Control Statement Input Data Set

This data set contains the control statements that the particular KGUP job processes. For a description of the syntax of these control statements, see Using KGUP control statements.

This data set is a physical sequential data set with a fixed logical record length (LRECL) of 80 bytes.

Note:

If a control statement adds or updates a key, later control statements in the control statement input data set for that KGUP job use the new or updated key.

In the KGUP job stream, the control statement input data set is defined by the CSFIN data definition statement.

Diagnostics Data Set

This data set contains a copy of each input control statement that is followed by one or more diagnostic messages that were generated for that control statement. It is a physical sequential data set with a fixed logical record length (LRECL) of 133 bytes. It should be fixed with ASA codes. Figure 131 shows an example of a diagnostics data set.

Figure 131. Diagnostics Data Set Example

KEY GENERATION DIAGNOSTIC REPORT  DATE:1997/9/14 (YYYY/MM/DD) TIME:12:10:15 PAGE 1



 /* THIS IS A KEY USED TO EXPORT KEYS FROM A TO B */
 ADD TYPE(EXPORTER) TRANSKEY(TK1),
  LABEL(ATOB)
 > > > CSFG0321 STATEMENT SUCCESSFULLY PROCESSED.





 /* THIS IS A KEY USED TO IMPORT KEYS FROM B TO A */
 ADD TYPE(IMPORTER) TRANSKEY(TK1),
  LABEL(BTOA)
 > > > CSFG0321 STATEMENT SUCCESSFULLY PROCESSED.
 > > > CSFG0780 A REFRESH OF THE IN-STORAGE CKDS IS NECESSARY TO ACTIVATE CHANGES MADE BY KGUP.
 > > > CSFG0002 CRYPTOGRAPHIC KEY GENERATION - END OF JOB. RETURN CODE = 0. 

 

In the KGUP job stream, the data set is defined by the CSFDIAG data definition statement.

Key Output Data Set

This data set contains information about each key KGUP generates, except an importer key used to protect a key that is stored with a file. Each entry contains the key value and the complement key type of the key created. Another system can use this information to create a key that is the complement of the key your system created.

This data set is a physical sequential data set with a fixed logical record length (LRECL) of 208 bytes.

To establish key exchange with a system that does not use KGUP control statements, you can send that system information from this data set. The receiving system can then use this information to create the complement of the key you created. You can print or process this data set when KGUP ends.

KGUP only lists a record for the key if the TRANSKEY or CLEAR keyword was in the control statement. If the TRANSKEY keyword was specified in the output key data set, KGUP lists, for the key type, the complement of the control statement key type. KGUP lists, for the key value, the key encrypted under the transport key as specified by the TRANSKEY keyword.

The encrypted key is in the form of an external key token. An external key token contains the encrypted key value and control information about the key. For example, the token contains the control vector for the key type.

If the CLEAR keyword was specified, in the output key data set KGUP lists, for the key type, the complement of the control statement key type. KGUP lists, for the key value, the clear key value of the key. With this information another system could generate keys that are complements of the keys your system generated. This would permit your system and the other system to exchange keys.

When KGUP generates two complementary keys, each encrypted by a different transport key, KGUP lists a record for each key. The first record contains a key that is encrypted under the first transport key variant and the type that is specified on the control statement. The second record contains a key that is encrypted under the second transport key variant and a type that is the complement of the first key.

The records in the key output data set are in this format:

Key label

(Character length 64 bytes) The key label specified on the control statement.

Key type

(Character length 8 bytes) The key type specified on the control statement or the complement of that key type if the TRANSKEY keyword was specified.

TRANSKEY label or CLEAR

(Character length 64 bytes) Either the key label of a transport key which encrypts the key entry or the character string CLEAR (left justified) if the key is unencrypted.

TRANSKEY type

(Character length 8 bytes) The key type of the TRANSKEY, which is always exporter.

Key Token

(Character length 64 bytes) A key token is composed of the key value and control information. The key value in this field is either unencrypted or encrypted under a transport key. For a description of format of a key token, see z/OS Cryptographic Services ICSF System Programmer’s Guide.

In the KGUP job stream, the data set is defined by the CSFKEYS data definition statement.

Control Statement Output Data Set

KGUP produces an output control statement for every key that is generated as a result of an input control statement with the TRANSKEY keyword specified. The output control statement contains the complement key type of the key type that is specified on the input control statement. The value that is output for the KEY keyword is encrypted under the transport key that is specified on the input control statement.

You can edit the output control statements and distribute them to the appropriate sites for input to KGUP at those locations.

The data set is a physical sequential data set with a fixed logical record length (LRECL) of 80 bytes.

One output control statement appears when you have KGUP generate a key value and create an operational and exportable key pair using a transport key.

Two output control statements appear when you have KGUP generate two exportable keys by using two different transport keys. These statements generate complementary keys types. You can send each statement to a different site to establish communication between the two sites.

In the KGUP job stream, the data set is defined by the CSFSTMNT data definition statement. The data set will contain information only when the input control statement contains the TRANSKEY keyword. The TRANSKEY keyword indicates that you will be transporting the key to another system.

The specific name of these types of data sets must appear in the job stream that runs KGUP.