The ADD and UPDATE control statements use the same keywords. The ADD control statement adds new keys to the CKDS. UPDATE changes existing key entries. Use the ADD or UPDATE control statement to specify that KGUP generate a key value or import a key value that you provide.

Refer to Figure 126 for the syntax of the ADD and UPDATE control statements.

 {ADD | UPDATE}


   {LABEL(label1[,...,label64]) | RANGE(start-label,end-label)}

   TYPE(key-type)

   ALGORITHM(DES|AES) 

   [OUTTYPE(key-type)]

   [TRANSKEY(key-label1[,key-label2]) | CLEAR]

   [NOCV]

   [LENGTH(n) | SINGLE]

   [KEY(key-value[,ikey-value])]

LABEL (label1[,...,label64])

This keyword defines the names of the key entries for KGUP to process within the CKDS. KGUP processes a separate entry for each label. If you specify more than one label on an ADD or UPDATE control statement, the program uses identical key values in each entry.

You must specify at least one key label, and you can specify up to 64 labels with the LABEL keyword. For the general rules about key label conventions and uniqueness, see General Rules for CKDS Records.

On a KGUP control statement, you must specify either the LABEL or RANGE keyword. When you supply a key value on the control statement with the KEY keyword, you must specify the LABEL keyword.

RANGE (start-label, end-label)

This keyword defines the range of the multiple labels that you want KGUP to create or maintain within the CKDS.

The label consists of between 2 and 64 characters that are divided as follows:

• The first 1 to 63 characters are the label base. These characters must be identical on both the start-label and end-label and are repeated for each label in the range. For the general rules about key label conventions and uniqueness, see General Rules for CKDS Records.
• The last 1 to 4 characters form the suffix. The number of digits in the start-label and end-label must be the same, and the characters must all be numeric. These numeric characters establish the range of labels KGUP creates. The start-label numeric value must be less than the end-label numeric value.

KGUP creates a separate CKDS entry for each label including the start and end labels. The program generates a different key value for each entry it creates.

You cannot use the RANGE keyword when you supply a key value to KGUP. Only use RANGE to generate a key value. The RANGE and KEY keywords are mutually exclusive.

On a KGUP control statement, you must specify either the LABEL or RANGE keyword.

TYPE (key-type)

This keyword specifies the type of key you want KGUP to process. You can specify only one key type for each control statement. For CLRAES, CLRDES, DATA, DATAXLAT, MAC, MACVER, DATAM, DATAMV, and NULL key types, KGUP allows only one key per label. For all other key types, you can have keys with the same labels but different key types.

You can specify any of these key types:

CLRAES

Clear Encryption/decryption key for AES

CLRDES

Clear Encryption/decryption key

DATA

Encryption/decryption key

DATAXLAT

Cipher text translate key – DATAXLAT is only supported on the IBM zSeries 900.

DATAM

Double-length MAC generation key

DATAMV

Double-length MAC verification key

EXPORTER

Exporter key-encrypting key

IMPORTER

Importer key-encrypting key

IPINENC

Input PIN encryption key

MAC

Single-length MAC generation key

Note:

On a z990, z890, z9 EC, z9 BC, z10 EC, z10 BC, and z196, MAC is a single or double-length key.

MACVER

Single-length MAC verification key

Note:

On a z990, z890, 9 EC, z9 BC, z10 EC, and z196, MACVER is a single or double-length key.

NULL

Used to create a null CKDS entry

OPINENC

Output PIN encryption key

PINGEN

PIN generation key

PINVER

PIN verification key

All these types of keys are stored in the CKDS.

Note:

For compatibility with previous releases of OS/390 ICSF, KGUP stores internal versions of DATAM and DATAMV keys in the CKDS under the key types of MACD and MACVER, respectively.

ALGORITHM (DES|AES)

This keyword defines the algorithm of the key you are generating. DES is the default value. All key types except CLRAES and CLRDES are valid with the DES value. Only the DATA and NULL key types are valid with AES. Generated operational keys will be encrypted under the respective master key.

Note:

To use AES, you need to have an AES-MK

OUTTYPE (key-type)

This keyword specifies the type of complementary key you want KGUP to generate for export. This keyword is valid only when you are requesting KGUP to generate keys and you also specify the CLEAR or TRANSKEY keywords. OUTTYPE is mutually exclusive with the KEY keyword. You cannot specify an OUTTYPE when you have chosen either CLRAES, CLRDES, DATAMV, PINVER, MACVER, or NULL for the key TYPE.

Refer to Table 14 for a list of the default and optional complementary key types for each of the 11 different key types. If OUTTYPE is not specified, KGUP generates the default complementary key that is shown in this table.

Table 14. Default and Optional OUTTYPES Allowed for Each Key TYPE

TYPE	OUTTYPE (Default)	OUTTYPE (Allowed)
CLRAES	Not Allowed	Not Allowed
CLRDES	Not Allowed	Not Allowed
DATA	DATA	DATA, DATAXLAT*
DATAXLAT	DATAXLAT	DATAXLAT*
DATAM	DATAMV	DATAM, DATAMV
DATAMV	Not Allowed	Not Allowed
EXPORTER	IMPORTER	IMPORTER
IMPORTER	EXPORTER	EXPORTER
IPINENC	OPINENC	OPINENC
MAC	MACVER	MAC, MACVER
MACVER	Not Allowed	Not Allowed
NULL	Not Allowed	Not Allowed
OPINENC	IPINENC	IPINENC
PINGEN	PINVER	PINVER
PINVER	Not Allowed	Not Allowed

Notes:

1. * DATAXLAT is only supported on the IBM zSeries 900
2. There is no defined OUTTYPE for the AES algorithm and the keyword may not be used with ALGORITHM(AES).

TRANSKEY (key-label1[,key-label2])

This keyword identifies the label of a transport key that already exists in the CKDS. KGUP uses the transport key either to decrypt an imported key value or to encrypt a key value to send to another system.

When KGUP generates a key, the program enciphers the key under a master key variant. KGUP may also generate a key value that can be used to create the key's complement. You can have KGUP encrypt the key value under a transport key or transport key variant. On the control statement, use the TRANSKEY keyword to specify the transport key that KGUP should use to encipher the complementary key. You can send the encrypted key value to another system to create the complementary key.

When you generate an importer key-encrypting key to encipher a key stored with data in a file, you can request that KGUP not generate the complementary export key-encrypting key. You do this by not specifying the TRANSKEY or CLEAR keyword. This is also true for DATA and MAC keys.

When you input a key value that is in importable form, the key that is specified by the KEY keyword is enciphered under a transport key. KGUP reenciphers the key value from under the transport key to under a master key variant. On the control statement, you use the TRANSKEY keyword to specify the transport key that enciphers the key.

You can import or export a new version of a key that is encrypted under the current version of the same key. You can do this by specifying the same key label in the TRANSKEY keyword as in the LABEL or RANGE keyword on an UPDATE control statement.

Your site can generate keys for key exchange between two other sites. These sites do not need to know the clear value of the keys used for this communication. KGUP generates control statements that you send to the sites. Then the sites' KGUPs establish the keys they need for key exchange.

To do this procedure, submit an ADD or UPDATE control statement with two TRANSKEY key labels. The first TRANSKEY label identifies the transport key that is valid between your site and the first recipient site. The second TRANSKEY label identifies the transport key that is valid between your site and the second recipient site. KGUP generates of a pair of control statements to create the complementary pair of keys that are needed at the two sites.

Note:

You cannot specify two transport keys that were installed without control vectors. For more information about control vectors, see the description of the NOCV keyword.

The TRANSKEY keyword and the CLEAR keyword are mutually exclusive.

If you have specified a key type of NULL, CLRDES or CLRAES for the TYPE keyword, you cannot use the TRANSKEY keyword.

Note:

TRANSKEY is not valid with ALGORITHM(AES).

CLEAR

This keyword indicates that either:

• You are supplying an unencrypted key value with the KEY keyword.
• KGUP should create a control statement that generates an unencrypted complementary key value.

You can supply either encrypted or unencrypted key values to KGUP with the KEY keyword. On the control statement to supply the unencrypted key, you specify the CLEAR keyword.

When KGUP generates a key, KGUP enciphers the key under a master key variant. KGUP may also generate a key value to be used to create the key's complement. KGUP can create the complementary key value in unencrypted form. To generate an unencrypted complementary key value, you specify the CLEAR keyword. Your ICSF system must be in special secure mode to use this keyword.

The CLEAR keyword and the TRANSKEY keyword are mutually exclusive. You cannot use the CLEAR keyword on a control statement when you use the TRANSKEY keyword. You cannot use the CLEAR keyword if you specify a NULL, CLRDES or CLRAES key for the TYPE keyword.

NOCV

To exchange keys with systems that do not recognize transport key variants, ICSF provides a way to by-pass transport key variant processing. KGUP or an application program encrypts a key under the transport key itself not under the transport key variant. This is called NOCV processing.

The NOCV keyword indicates that the key that is generated or imported is a transport key to use in NOCV processing. The transport key has the NOCV flag set in the key control information when stored in the CKDS.

Note:

To create keys for NOCV processing, NOCV-Enablement keys must exist. For a description of how to create NOCV-Enablement keys, see Initializing the CKDS and PKDS at First-Time Startup.

The NOCV keyword is only valid for generating transport keys. The keyword is not valid if you specify the TRANSKEY keyword with two transport key labels.

LENGTH or SINGLE

LENGTH indicates the length of the key to generate. LENGTH(8) generates a single-length key. LENGTH(16) generates a double-length DES key or 128-bit AES key, LENGTH(24) generates a triple-length DES key (DATA only) or a 192-bit AES key. LENGTH(32) generates a 256-bit AES key. If a LENGTH is specified when generating DATAM or DATAMV keys, it must be LENGTH(16). For CLRDES, valid values for the LENGTH keyword are 8, 16, and 24. For CLRAES, valid values for the LENGTH keyword are 16, 24 and 32.

For double-length key types, LENGTH(8) or SINGLE in an ADD or UPDATE statement causes KGUP to generate a double-length key with both halves the same. On the KGUP panel, you can achieve this by specifying 8 in the LENGTH field for a double-length key type.

In either case, LENGTH is used only for generating keys. If you are specifying clear or encrypted key parts, do not use the LENGTH keyword (and do not fill in a value for LENGTH on the KGUP panel).

The LENGTH keyword and the KEY keyword are mutually exclusive. Although the LENGTH keyword is valid when you create control statements to generate DATA keys, KGUP ignores it for DATAXLAT keys. KGUP automatically generates them as single-length keys.

DES

This keyword is no longer supported but is tolerated.

KEY (key-value[,key-value[,key_value[,key_value]]])

This keyword allows you to supply KGUP with a key value. KGUP can use this key value to add a key or update a key entry.

If you do not specify this keyword, KGUP generates the key value for you. You cannot use the RANGE keyword or the LENGTH keyword with this keyword. Each key part consists of exactly 16 characters that represent 8 hexadecimal values.

This keyword is required when you specify either DATAMV, MACVER, or PINVER for the TYPE keyword. Because KGUP cannot generate PIN verification or MAC verification keys in operational form, you must always supply values for these types of keys.

For DATAXLAT, supply one key value. DATAXLAT is a single-length key, if you supply a second key value, KGUP discontinues processing the control statement and issues an error message.

For a double-length key (EXPORTER, IMPORTER, IPINENC, OPINEC, PINGEN, PINVER), supply two key values. If you supply only one key value, KGUP will duplicate the key value as the secode key value. KGUP concatenates these two identical values, and then stores and uses the key as if the key was double-length.

For double-length keys, when you use the TRANSKEY keyword with the KEY keyword, the transport key you specify is the importer key that encrypts the key value. If you supply only one key value for a double-length key and also specify TRANSKEY, the TRANSKEY must be an NOCV importer.

For MAC and MACVER types, you can supply one or two key values.

For a DES DATA or CLRDES key, you can supply the key in one, two, or three parts.

For an AES DATA or CLRAES key, you must supply two, three or four parts.

The use of NOCV processing eliminates the ability of the system that generates the key to determine the use of the key on a receiving system. Therefore, access to these keys should be strictly controlled. For a description of security considerations, see z/OS Cryptographic Services ICSF System Programmer’s Guide.