Using the ADD and UPDATE control statements for key management and distribution functions

z/OS Cryptographic Services ICSF Administrator's Guide

Using the ADD and UPDATE control statements for key management and distribution functions

z/OS Cryptographic Services ICSF Administrator's Guide
SA22-7521-17

You use the ADD and UPDATE control statements to run KGUP for functions that involve key generation, maintenance, and distribution. For ADD and UPDATE control statements, KGUP either imports a key value that you supply or generates a key value. KGUP allows the creation and maintenance of clear key tokens in the CKDS. This topic describes the combinations of control statement keywords you use to perform these functions. Table 15 shows the keyword combinations permitted on ADD and UPDATE control statements.

Table 15. Keyword Combinations Permitted in ADD and UPDATE Control Statements
Control Statement	LABEL or RANGE	TYPE	OUTTYPE	TRANSKEY or CLEAR	NOCV	ALGORITHM	LENGTH or KEY
ADD	Yes	Yes	Yes¹	Yes²	Yes³	Yes⁴	Yes¹
UPDATE	Yes	Yes	Yes¹	Yes²	Yes³	Yes⁴	Yes¹
Notes: OUTTYPE can be used with either TRANSKEY or CLEAR but is mutually exclusive with KEY. TRANSKEY is not valid when TYPE is NULL, CLRDES or CLRAES. NOCV is not valid when TRANSKEY is specified with two key labels. It is not valid when TYPE is CLRDES or CLRAES. OUTTYPE, TRANSKEY and NOCV are not valid with ALGORITHM(AES). There are no restrictions with ALGORITHM(DES).

To Import Keys

You use an ADD or UPDATE control statement to supply a value to KGUP. The program receives the value, enciphers the value under a master key variant, and places the value in a CKDS entry. The value that you supply may be in clear form or it may be encrypted under a transport key. The statement that contains the value may be sent from another system. The other system sends the value to create a key on your system. This key is the complement of a key that was generated on the other system.

You can supply a transport key value to KGUP from a system that does not use control vectors. You use the key for key exchange with that system. KGUP places the key into the CKDS with an indication that the key is to be used without control vectors.

Import a Clear Key Value

You can supply a clear key value on a control statement for KGUP to import.

These statements show the syntax when you supply a clear key value to KGUP.

Note:

For these control statements, your system should be in special secure mode.

When you supply a single-length, clear key value:

   ADD or UPDATE  LABEL(label)    TYPE(data,exporter,importer,
   mac,macver, or any PIN key)  CLEAR  KEY(key-value)

When you supply a double-length, clear key value:

   ADD or UPDATE  LABEL(label)  TYPE(data,datam,datamv,exporter,importer,
   or any PIN key)  CLEAR  KEY(key-value, key-value)

When you supply a triple-length, clear key value:

   ADD or UPDATE  LABEL(label)  TYPE(data),
   CLEAR  KEY(key-value, key-value, key-value)

When you supply a single-length clear key value and you use the key to exchange keys with a cryptographic product that does not use control vectors or double-length keys:

   ADD or UPDATE  LABEL(label)  TYPE(exporter or importer),
   CLEAR  KEY(key-value)  NOCV

When you supply a double-length, clear key value, and you use the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label)  TYPE(exporter or importer),
   CLEAR  KEY(key-value,ikey-value)  NOCV

When you supply a 128-bit, clear key value for an AES DATA key:

   ADD or UPDATE  LABEL(label)  TYPE(data) ALGORITHM(AES),
   CLEAR KEY(key-value,key-value)

For the CLRDES and CLRAES key types, the CLEAR keyword is not allowed because the key type indicates that the KEY is a clear key value. Also, special secure mode is not required for these key types.

   ADD or UPDATE LABEL(label) TYPE(clraes), 
   KEY(key-value, key-value)

   ADD or UPDATE LABEL(label) TYPE(clrdes), 
   KEY(key-value, key-value)

Import an Encrypted Key Value

When you supply KGUP with an encrypted key value, the value is encrypted under a transport key. The transport key is one key in a complementary key pair that you share with another system. When the other system's KGUP generated a key, the program also stored a control statement to use to create the complementary key. The other system sends the control statement to your system. You can use the statement to supply an encrypted key value to KGUP to create the key.

These statements show the syntax when you supply an encrypted key value to KGUP.

When you supply a single-length, encrypted key value:

   ADD or UPDATE  LABEL(label)  TYPE(data,exporter,importer,
   mac,macver, or any PIN key) TRANSKEY(key-label 1)  KEY(key-value)

When you supply a double-length, encrypted key value:

   ADD or UPDATE  LABEL(label)  TYPE(data,datam,datamv,exporter,importer,
   or any PIN key) TRANSKEY(key-label 1)  KEY(key-value,ikey-value)

When you supply a triple-length, encrypted key value:

   ADD or UPDATE  LABEL(label)  TYPE(data),
   TRANSKEY(key-label 1)  KEY(key-value, key-value, key-value)

When you supply a single-length, encrypted key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors or double-length keys:

   ADD or UPDATE  LABEL(label)  TYPE(exporter or importer),
   TRANSKEY(key-label 1)  KEY(key-value)  NOCV

Note:

Single-length keys with replicated key parts can be brought in under a TRANSKEY only if the TRANSKEY is an NOCV IMPORTER.

When you supply a double-length encrypted key value and you will use the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label)  TYPE(exporter or importer),
   TRANSKEY(key-label 1)  KEY(key-value,ikey-value)  NOCV

To Generate Keys

You use an ADD or UPDATE control statement to have KGUP generate a key value to place in the CKDS. The program generates the value, enciphers the value under a master key variant, and places the value in the CKDS. When KGUP generates a key, the program may also store information to create the key's complement in a data set.

You can have KGUP generate a transport key that you use to send or receive keys from a system that does not use control vectors. KGUP places the key into the CKDS with an indication that the key is to be used without control vectors.

Generate an Importer Key For File Encryption

You can have KGUP create an importer key without having KGUP store information about the complement of the key. You do not use the importer key in key exchange with another system. You use the importer key to encrypt a data-encrypting key that you use to encrypt data in a file on your system. You can store the data-encrypting key with the file, because the data-encrypting key is encrypted under the importer key.

These statements show the syntax when you generate an importer key to use in file encryption on a system:

When you generate a single-length key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(importer)  SINGLE

When you generate a double-length key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(importer)

Generate an AES data key

You can have KGUP create an AES data key. The keys may be 128-, 192- or 256-bits in length.

These statements show the syntax when you generate an AES data key on a system.

When you generate a 128-bit key value:

   ADD or UPDATE  ALGORITHM(AES) LABEL(label) or RANGE(start-label,end-label),
   TYPE(data)

When you generate a 192-bit key value:

   ADD or UPDATE  ALGORITHM(AES) LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(24)

Generate a Complementary, Clear Key Value

You can have KGUP store complementary key information when KGUP generates a key. This information includes the key value. You send the information to another system which uses the information to generate the complementary key. KGUP stores the key value to create the complementary key in either clear or encrypted form. KGUP stores information both in and not in the form of a control statement.

These statements show the syntax when you have KGUP store the complementary key value in clear form.

Note:

For these control statements, your system should be in special secure mode.

When you generate a single-length, transport or PIN clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen) CLEAR  SINGLE

When you generate a single-length, DATA clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(8) CLEAR

When you generate a double-length, DATA clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(16) CLEAR

When you generate a triple-length, DATA clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(24) CLEAR

When you generate a single-length, MAC clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(mac) OUTTYPE(mac or macver) CLEAR

When you generate a double-length, DATAM clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(datam) LENGTH(16) OUTTYPE(datam or datamv) CLEAR

When you generate a single-length, PINGEN clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(pingen) LENGTH(8) CLEAR

When you generate a double-length, clear key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen) CLEAR

When you generate a single-length, clear key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter or importer)  CLEAR  NOCV  SINGLE

When you generate a double-length, clear key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(16) CLEAR NOCV

When you generate a triple-length, clear key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(24)  CLEAR  NOCV

When you generate a double-length, clear key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter or importer)  CLEAR  NOCV

When you generate a clear key value to transport data-encrypting keys for use in the DES algorithm:

   ADD or UPDATE LABEL(label) TYPE(exporter or importer) CLEAR

Generate a Complementary, Encrypted Key Value

KGUP encrypts the complementary key value under the exporter key that you specify.

These statements show the syntax when you have KGUP generate the complementary key value in encrypted form.

When you generate a single-length, transport or PIN encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen),
   TRANSKEY(key-label 1)  SINGLE

When you generate a single-length, DATA encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) OUTTYPE(data) TRANSKEY(key-label 1)

When you generate a single-length, MAC encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(mac) OUTTYPE(mac or macver) TRANSKEY(key-label 1)

When you generate a double-length, encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen)  TRANSKEY(key-label 1)

When you generate a double-length DATA encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data or datam)  LENGTH(16) TRANSKEY(key-label 1)

When you generate a double-length DATAM encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(datam)  TRANSKEY(key-label 1)

When you generate a triple-length DATA encrypted key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data)  LENGTH(24) TRANSKEY(key-label 1)

When you generate a single-length, encrypted key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter or importer)  TRANSKEY(key-label 1)  SINGLE  NOCV

When you generate a double-length, encrypted key value, and you are using the key to exchange keys with a cryptographic product that does not use control vectors.

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter or importer)  TRANSKEY(key-label 1)  NOCV

Generate a Complementary Key Pair For Other Systems

You can also use KGUP as a key distribution center. KGUP generates a pair of complementary key values that are both used on other systems. KGUP encrypts the values under appropriate variants of two different exporter key-encrypting keys. KGUP does not alter your system's CKDS. The program stores two control statements each containing one of the keys that are encrypted under a transport key. You send the statements to two other sites which can create the keys and use the keys to exchange keys.

These statements show the syntax when you have KGUP generate a pair of complementary key values to send to other systems.

When you generate single-length transport or PIN key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen),
   TRANSKEY(key-label 1,key-label 2)  SINGLE

When you generate single-length DATA key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) OUTTYPE(data) TRANSKEY(key-label 1,key-label 2)

When you generate double-length DATA key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(16) TRANSKEY(key-label 1,key-label 2)

When you generate triple-length DATA key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(data) LENGTH(24) TRANSKEY(key-label 1,key-label 2)

When you generate single-length MAC key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(mac) OUTTYPE(mac or macver) TRANSKEY(key-label 1,key-label 2)

When you generate double-length DATAM key values:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label)
   TYPE(datam) OUTTYPE(datam or datamv),
   TRANSKEY(key-label 1,key-label 2)

When you generate a double-length key value:

   ADD or UPDATE  LABEL(label) or RANGE(start-label,end-label),
   TYPE(exporter,importer,ipinenc,opinenc, or pingen),
   TRANSKEY(key-label 1,key-label2)

To Create NULL Keys

You can use KGUP to create an initial record in the CKDS. To do this, you create an ADD control statement with a key TYPE of NULL. Once you have created this key record, you can use the Key Record Write callable service to place a key value in the record.

If you are generating a large number of keys, you will get better performance if you create the NULL key records with KGUP. This is preferrable to using the Key_Record_Create callable service.

Create NULL Key Records

You can use KGUP to create a single NULL key record or a range of NULL key records. This statement shows the syntax you use:

   ADD  LABEL(label) or RANGE(start-label,end-label)  TYPE(null)

Notices | Terms of use | Support | Contact z/OS | zFavorites