Example 1: ADD Control Statement

This example shows a control statement that specifies that KGUP add an entry to the CKDS.

   ADD  TYPE(IMPORTER) LABEL(DASDOCT93401E)

KGUP checks that an entry labeled DASDOCT93401E with a keytype of importer does not already exist in the CKDS. It also checks that there are no DATA, DATAXLAT, DATAM, DATAMV, MAC, MACVER, or NULL key entries with that label. Each of these keys requires a unique label. If the key entry already exists, KGUP stops processing the control statement.

If the entry does not exist, KGUP creates the entry with a label of DASDOCT93401E and type of IMPORTER. KGUP generates a double-length key and encrypts the key under the master key variant for an importer key. KGUP places the key in the entry.

Example 2: ADD Control Statement with CLEAR Keyword

This example shows a control statement that specifies that KGUP add an entry to the CKDS. Because the CLEAR keyword is specified, KGUP processes only this control statement if ICSF is in special secure mode.

   ADD  TYPE(EXPORTER)  LABEL(ATMBRANCH5MO001)  CLEAR

KGUP checks that an entry with the label ATMBRANCH5MO001 with the type EXPORTER does not already exist in the CKDS. It also checks that there are no DATA, DATAXLAT, DATAM, DATAMV, MAC, MACVER, or NULL key entries with that label. Each of these keys requires a unique label. If the entry already exists, KGUP stops processing the control statement.

If the entry does not exist, KGUP creates the entry for the label specified and the type exporter. KGUP generates a double-length key, encrypts the key under the master key variant for an exporter key, and places the key in the entry.

KGUP stores information to the key output data set. You can send the information to another system that does not use KGUP. The other system uses the information to create the complements of the keys you created. The information contains the clear key value and specifies the key type as importer.

For example, the control statement would be in this format:

   ADD  TYPE(IMPORTER)  LABEL(ATMBRANCH5MO001)  CLEAR,
   KEY(6709E5593933DA00,9099937DDE93A944)

The key value is the clear key value of the key created. The type of key is the complement of the type of key created.

Example 3: ADD Control Statement with one TRANSKEY Keyword

This example shows a control statement that specifies that KGUP add an entry to the CKDS. Because the TRANSKEY keyword is specified, KGUP also creates a control statement that another installation uses to create the complement of the key for PIN exchange.

   ADD  TYPE(IPINENC)  LABEL(LOCTOJWL.JULY03)  TRANSKEY(SENDJWL.JULY03)

KGUP checks that an entry with the label LOCTOJWL.JULY03 for an input PIN-encrypting key does not already exist in the CKDS. It also checks that there are no DATA, DATAM, DATAMV, MAC, MACVER, or NULL key entries with that label. Each of these keys requires a unique label. If the entry already exists, KGUP stops processing the control statement.

If the entry does not exist, KGUP creates the entry with a label of LOCTOJWL.JULY03 and type of IPINENC. KGUP generates a double-length key. KGUP encrypts the key under the master key variant for an input PIN-encrypting key and places the key in the entry.

KGUP stores information to the key output data set. You can send the information to another system that does not use KGUP. The other system uses the information to create the complement of the key you created. The information contains the key in exportable form. The key is encrypted under the exporter key, labelled SENDJWL.JULY03, that was specified by the TRANSKEY keyword. The information specifies the key type as output PIN-encrypting key (OPINENC).

KGUP stores a control statement to the control statement output data set. You can send the control statement to another system. The other system's KGUP uses the statement to create a key that complements the key that you created.

For example, the control statement would be in this format:

   ADD  TYPE(OPINENC)  LABEL(LOCTOJWL.JULY03)  TRANSKEY(SENDJWL.JULY03),
   KEY(6709E5593933DA00,9099937DDE93A944)

The key value is the encrypted value of the key that KGUP created. The key is encrypted under the exporter key, labeled SENDJWL.JULY03, which was the transport key label that was specified on the original control statement. The type of key is the complement of the type of key it created.

Example 4: ADD Control Statement with two TRANSKEY Keywords

This example shows a control statement specifying that KGUP create keys for key exchange between two other sites.

   ADD  TYPE(EXPORTER)  LABEL(JWL@SSIJULY03),
   TRANSKEY(SENDTOJWLJULY03,SENDTOSIIJULY03)

KGUP generates a key value and encrypts the value under the variants of the exporter key-encrypting keys that are specified by the TRANSKEY keyword. KGUP does not alter the CKDS in any way.

KGUP stores these two control statements to the control statement output data set:

   ADD  TYPE(EXPORTER)  LABEL(JWL@SSIJULY03)  TRANSKEY(SENDTOJWLJULY03),
   KEY(4542E37B570033AD,3C00F6850A99E11B)

   ADD  TYPE(IMPORTER)  LABEL(JWL@SSIJULY03)  TRANSKEY(SENDTOSIIJULY03),
   KEY(6709E5993933DA00,1449A3D9ED0A1586)

The control statements create keys that complement each other. You send the statements to two sites that want to exchange keys. The receiving sites process the statements to create a complementary pair of transport keys.

KGUP also stores information to create the keys in the key output data set.

Example 5: ADD Control Statement with a Range of NULL Keys

This example shows a control statement that creates a range of empty key records in a CKDS. Once the key labels exist, you can enter key types and key values for these records in several ways. One method is to use KGUP to create UPDATE control statements. Another method is to write application programs that use the Key_Record_Write callable service to add key types and key values to the existing empty key records.

   ADD  TYPE(NULL)  RANGE(BRANCH5M0001,BRANCH5M0025)

KGUP checks for any entries with labels between BRANCH5M001 and BRANCH5M0025 in the CKDS. If any entries in this range already exist, KGUP processes the control statement up to the point where a duplicate label is found. It then stops processing the control statement and issues error messages.

If no entries exist, KGUP creates a range of 25 sequentially-numbered key records and adds them to the CKDS.

Example 6: ADD Control Statement with OUTTYPE and TRANSKEY Keywords

This example shows a control statement that specifies that KGUP add an entry with the key type of DATAM to the CKDS. The TRANSKEY keyword instructs KGUP to create a control statement for an intermediate node to use to create the complement DATAMV key for intermediate node data translation.

   ADD  LABEL(DATAKEY.TO.TRANSLATION)  TYPE(DATAM)  OUTTYPE(DATAMV),
   TRANSKEY(TKBRANCH2.INTER)

KGUP checks that an entry with the label DATAKEY.TO.TRANSLATION does not already exist in the CKDS, because DATAM keys require unique labels. If the entry already exists, KGUP stops processing the control statement.

If the entry does not exist, KGUP creates the entry with a label of DATAKEY.TO.TRANSLATION and a type of DATAM. KGUP then generates a single-length key, encrypts the key under the master key variant for a DATAM key, and places the key in the CKDS entry.

KGUP stores information to the key output data set. You can send the information to another system that does not use KGUP. The other system uses the information to create the complement of the key you created. The information contains the key value of the key in exportable form. The key is encrypted under the exporter key, labeled TKBRANCH2.INTER, that was specified by the TRANSKEY keyword. The information specifies the key type as data-translation key (DATAMV).

KGUP stores a control statement to the control statement output data set. You can send the control statement to another system. The other system's KGUP uses the statement to create a key that complements the key you created.

For example, the control statement would be in this format:

   ADD  TYPE(DATAMV)  LABEL(DATAKEY.TO.TRANSLATION),
   TRANSKEY(TKBRANCH2.INTER), KEY(2509F2869257BD00)

The key value is the encrypted value of the key that KGUP created. The key is encrypted under the exporter key, labelled TKBRANCH2.INTER, which was the transport key label that was specified on the original control statement. The type of key is the complement of the type of key it created.

Example 7: UPDATE Control Statement with Key Value and Transkey Keywords

This example shows a control statement that specifies that KGUP import a key value. KGUP places the key value into an entry in the CKDS that already exists.

   UPDATE  LABEL(PINVBRANCH5M0002)  TYPE(PINVER)  TRANSKEY(TKBRANCH5JUNE99),
   KEY(7165865940460A48,2237451B4545718B)

The key value on the control statement is encrypted under a transport key that is shared with another system. The label for the transport key is TKBRANCH5JUNE99. KGUP uses the importer key labelled TKBRANCH5JUNE99 to decrypt the key value.

KGUP encrypts the key value under the master key variant for a PIN verification key. KGUP then places the key in a key entry labelled PINVBRANCH5M0002 with the type PINVER in the CKDS.

Example 8: DELETE Control Statement

This example shows a control statement that specifies that KGUP delete an entry from the CKDS.

   DELETE  LABEL(GENBRANCH2M0003)  TYPE(PINGEN)

KGUP deletes the entry with a label of GENBRANCH2M0003 and type of PIN generation key from the CKDS. If KGUP cannot find the entry, KGUP gives you an error message.

Example 9: RENAME Control Statement

This example shows a control statement that specifies that KGUP rename an entry in the CKDS.

   RENAME  LABEL(JWL@SSIDEC97,JWL@SSIJUNE99)  TYPE(EXPORTER)

KGUP checks if an entry with a label of JWL@SSIJUNE99 and a key type of EXPORTER already exists in the CKDS. If the entry does exist, KGUP does not process the control statement. KGUP checks if an entry with the label JWL@SSIDEC97 contains a key type of EXPORTER exists. If the entry exists, KGUP renames the entry JWL@SSIJUNE99.

Example 10: SET Control Statement

This example shows a control statement that specifies that KGUP send certain installation data every time an exit is called during KGUP processing. KGUP sends the data every time an exit is called until KGUP encounters another SET statement or the job stream completes.

SET  INSTDATA('This key is valid effective 9/9/99')

KGUP sends the installation data each time an installation exit is called during KGUP processing.

Example 11: OPKYLOAD Control Statement

This example shows a control statement to load a key into the CKDS from a PCIXCC, CEX2C, or CEX3C. The serial number of the card is 94000011. A key has been loaded on the card with the label ERC033.DEC50.

OPKYLOAD LABEL(ERC033.DEC50) SERNBR(94000011)  

KGUP checks the CKDS for the label and will fail if the label exists. KGUP then queries the PCIXCC, CEX2C or CEX3C to see if the key exists on the card. If the key exists, the key token is retrieved from the card and loaded into the CKDS.

Example 12: OPKYLOAD Control Statement for NOCV Key-encrypting Keys

This example shows a control statement to load a key into the CKDS from a PCIXCC, CEX2C, or CEX3C where the key is a key-encrypting key to be used as a NOCV KEK. The serial number of the card is 94000064. A key has been loaded on the card with the label ERC033.NOCV.IMPORTER.

OPKYLOAD LABEL(ERC033.NOCV.IMPORTER) SERNBR(94000064) NOCV 

KGUP checks the CKDS for the label and will fail if the label exists. KGUP then queries the PCIXCC, CEX2C, or CEX3C to see if the key exists on the card. If the key exists, the key token is retrieved from the card. If the key is a key-encrypting key with the default control vector, the NOCV token flag is set. The token is then loaded into the CKDS.

Example 13 – ADD control statement with CLRDES keyword

This example shows a control statement that adds a CLRDES key to the CKDS with a random 8 byte key.

ADD TYPE(CLRDES) LENGTH(8) LAB(CLRDES.KEYLN8)                                                

Example 14 – ADD control statement to add a group of CLRDES keys

This example shows a control statement that adds a group of CLRDES keys to the CKDS. Key value is generated.

ADD TYPE(CLRDES) LENGTH(8) LAB(A.CLRDES.KEYLN8,B.CLRDES.KEYLN8,C.CLRDES.KEYLN8) 

Example 15 – ADD control statement to add a group of CLRDES keys

This example shows a control statement that adds a group of CLRDES keys. The clear key value is specified.

ADD TYPE(CLRDES) KEY(2C2C2C2C2C2C2C2C,1616161616161616),                           
LAB(X.CLRDES.KEYLN16,Y.CLRDES.KEYLN16,Z.CLRDES.KEYLN16)  

Example 16 – ADD control statement to add a range of CLRDES keys

This example shows a control statement that adds a range of CLRDES keys. A different key value is generated for each key label.

ADD TYPE(CLRDES) LENGTH(24) RAN(CLRDES.KEYLN24.KEY1,CLRDES.KEYLN24.KEY3)   

Example 17 – UPDATE control statement with CLRDES keyword

This example shows a control statement that changes a CLRDES key.

UPDATE TYPE(CLRDES) KEY(4343434343434343) LAB(CLRDES.KEYLN8)  

Example 18 – UPDATE control statement with CLRDES keyword

This example shows a control statement that changes a range of CLRDES keys.

UPDATE TYPE(CLRDES) LENGTH(16) RAN(CLRDES.KEY1,CLRDES.KEY3)     

Example 19 – DELETE control statement with CLRDES keyword

This example shows a control statement that deletes a CLRDES key.

DELETE TYPE(CLRDES) LAB(CLRDES.KEYLN24)

Example 20 – DELETE control statement to delete a group of CLRDES key labels

This example shows a control statement that deletes a group of CLRDES keys.

DELETE TYPE(CLRDES) LAB(A.KEYLN16,B.KEYLN16,C.KEYLN16)

Example 21 – RENAME Control Statement with CLRDES Keyword

This example shows a control statement that renames a CLRDES key.

RENAME TYPE(CLRDES) LAB(CLRDES.KEYLN16,CLRDES.DOUBLE.LENGTH.KEY)

Example 22 – ADD Control Statement with CLRAES Keyword

This example shows a control statement that adds a CLRAES key to the CKDS with a random 16 byte key.

ADD TYPE(CLRDES) LENGTH(16) LAB(AES.BIT128)

Example 23 – ADD Control Statement to Add a Group of CLRAES Keys

This example shows a control statement that adds a group of CLRAES keys to the CKDS. Key value is generated.

ADD TYPE(CLRAES) LENGTH(16) LAB(A.AES.L128,B.AES.L128,C.AES.L128) 

Example 24 – ADD Control Statement to Add a Group of CLRAES Keys

This example shows a control statement that adds a group of CLRAES keys. The clear key value is specified.

ADD TYPE(CLRAES) KEY(2C2C2C2C2C2C2C2C,1616161616161616,A9A9A9A9A9A9A9A9),
LAB(X.AES.BIT192,Y.AES.BIT192,Z.AES.BIT192) 

Example 25 – ADD Control Statement to Add a Range of CLRAES Keys

This example shows a control statement that adds a range of CLRAES keys. A different key value is generated for each key label.

473 ADD TYPE(CLRAES) LENGTH(32) RAN(AES.LN32.KEY1,AES.LN32.KEY3) 

Example 26 – UPDATE Control Statement with CLRAES Keyword

This example shows a control statement that changes a CLRAES key.

UPDATE TYPE(CLRAES) KEY(4343434343434343) LAB(AES.BIT128) 

Example 27 – UPDATE Control Statement with CLRAES Keyword

This example shows a control statement that changes a range of CLRAES keys.

UPDATE TYPE(CLRAES) LENGTH(16) RAN(AES.KEY1,AES.KEY3) 

Example 28 – DELETE Control Statement with CLRAES Keyword

This example shows a control statement that deletes a CLRAES key.

DELETE TYPE(CLRAES) LAB(AES.LN24)

Example 29 – DELETE Control Statement to Delete a Group of CLRAES Key Labels

This example shows a control statement that deletes a group of CLRAES keys.

DELETE TYPE(CLRAES) LAB(A.AES.LN16,B.AES.LN16,C.AES.LN16)

Example 30 – RENAME Control Statement with CLRAES Keyword

This example shows a control statement that renames a CLRAES key.

RENAME TYPE(CLRAES) LAB(AES.ESC001,AES.EXC001)

Example 31 – ADD Control Statement for ALGORITHM keyword

This example shows a control statement that adds an AES DATA key to the CKDS with a random 128-bit key value.

ADD TYPE(DATA) ALGORITHM(AES) LENGTH(16) LAB(AES.BIT128) 

This example shows a control statement that adds a DES DATA key to the CKDS with a random 16-byte key value.

ADD TYPE(DATA) ALGORITHM(DES) LENGTH(16) LAB(DES.KEYLN16) 

This example shows a control statement that adds a group of AES DATA keys to the CKDS. A different key value will generated for each label.

 ADD TYPE(DATA) LENGTH(16) LAB(A.AES.L128,B.AES.L128,C.AES.L128) ALGORITHM(AES)

This example shows a control statement that adds a group of DES DATA keys to the CKDS. A different key value will generated for each label.

ADD TYPE(DATA) LENGTH(16) LAB(A.DES.L16,B.DES.L16,C.DES.L16) ALGORITHM(DES)

This example shows a control statement that adds a group of AES DATA keys. The clear key value is specified.

ADD TYPE(DATA) ALGORITHM(AES) KEY(2C2C2C2C2C2C2C2C,1616161616161616,A9A9A9A9A9A9A9A9), 
LAB(X.AES.BIT192,Y.AES.BIT192,Z.AES.BIT192)

This example shows a control statement that adds a group of DES DATA keys to the CKDS. A different key value will generated for each label.

ADD TYPE(DATA) ALGORITHM(DES) LENGTH(24) RAN(DES.LN24.KEY1,DES.LN24.KEY3) 

Example 32 – UPDATE Control Statement with the ALGORITHM keyword

This example shows a control statement that changes an AES DATA key.

UPDATE TYPE(DATA) KEY(4343434343434343,5656565656565656) LAB(AES.BIT128) ALGORITHM(AES)

This example shows a control statement that changes a range of DES keys.

UPDATE TYPE(DATA) LENGTH(16) RAN(DES.KEY1,DES.KEY3) ALGORITHM(DES)