Syntax of the ADD and UPDATE control statements

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

Refer to Figure 1 for the syntax of the ADD and UPDATE control statements for CCA key tokens.

 {ADD | UPDATE}


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

   TYPE(key-type)

   [ALGORITHM(DES|AES)] 

   [OUTTYPE(key-type)]

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

   [NOCV]

   [LENGTH(n)]

   [SINGLE | DOUBLEO | $TRIPLE | $TRIPLEO]

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

   [KEYUSAGE(key-usage-value[,key-usage-value]...)]

   [KEYMGT(key-management-value1[,key-management-value2])]

   [DKYGENKYUSAGE(key-usage-value1[,key-usage-value2])] 

LABEL (label[,label]...)

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. Use RANGE to only 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 DES key types EXPORTER, IMPORTER, IPINENC, PINGEN, PINVER, and OPINENC key types, KGUP allows keys with the same labels but different key types. You can specify any of the key types in Table 1.

Table 1. Key types

Key Type	Algorithm	Usage	Notes	Default Length
CIPHER	AES	Data-encrypting key for the CSNBSAD and CSNBSAE services.	128-bit, 192-bit, or 256-bit key.	256-bit
CIPHER	DES	Data-encrypting key for the CSNBDEC and CSNBENC services.	Single-length, double-length, or triple-length key.	Double-length
CIPHERXI	DES	Input cipher translate key for CSNCTT2 and CSNCTT3 services.	Double-length key. May not have replicated key values. The September, 2012 or later licensed internal code (LIC) is required.	Double-length
CIPHERXL	DES	Input cipher translate key for CSNCTT2 and CSNCTT3 services.	Double-length key. May not have replicated key values. The September, 2012 or later licensed internal code (LIC) is required.	Double-length
CIPHERXO	DES	Output cipher translate key for CSNCTT2 and CSNCTT3 services.	Double-length key. May not have replicated key values. The September, 2012 or later licensed internal code (LIC) is required.	Double-length
CLRAES		Clear AES data-encrypting key for the CSNBSYD and CSNBSYE services.	128-bit, 192-bit, or 256-bit key	128-bit
CLRDES		Clear DES data-encrypting key for the CSNBSYD and CSNBSYE services.	Single-length, double-length, or triple-length key.	Single-length
DATA	AES, DES	Data-encrypting key for the CSNBDEC, CSNBENC, CSNBSAD, CSNBSAE, CSNBSYD, and CSNBSYE services.	Single-length, double-length, or triple-length key for DES. 128-bit, 192-bit, or 256-bit key for AES.	Double-length for DES 128-bit for AES
DATAM	DES	Double-length MAC generation key.	Double-length key DOUBLEO not allowed.	Double-length
DATAMV	DES	Double-length MAC verification key.	Double-length key DOUBLEO not allowed.	Double-length
DECIPHER	DES	Data-decrypting key for the CSNBDEC service.	Single-length, double-length, or triple-length key.	Double-length
DKYGENKY*	AES, DES	Diversified key generating key for CSNBDKG and CSNBDKG2 services.	Double-length key for DES. 128-bit, 192-bit, or 256-bit key for AES.	Double-length for DES 256-bit for AES
ENCIPHER	DES	Data-encrypting key for the CSNBENC service.	Single-length, double-length, or triple-length key.	Double-length
EXPORTER	AES, DES	Exporter key-encrypting key.	Double-length or triple-length key for DES. 128-bit, 192-bit, or 256-bit key for AES.	Double-length for DES 256-bit for AES
IMPORTER	AES, DES	Importer key-encrypting key.	Double-length or triple-length key for DES. 128-bit, 192-bit, or 256-bit key for AES.	Double-length for DES 256-bit for AES
IMPPKA	DES	Limited authority importer key-encrypting key.	Double-length or triple-length key.	Double-length
IPINENC	DES	Input PIN encryption key.	Double-length or triple-length key.	Double-length
KEYGENKY*	DES	Key generating key for DUKPT. Used with CSNBPTR, CSNBPTV, CSNBDKG, and CSNBUKD services.	Double-length key.	Double-length
MAC*	AES	MAC generation and verification key.	128-bit, 192-bit, or 256-bit key for AES.	256-bit
MAC	DES	MAC generation key.	Single-length, double-length, or triple-length key.	Double-length
MACVER	DES	MAC verification key.	Single-length, double-length, or triple-length key.	Double-length
NULL	AES, DES	Used to create a null CKDS entry.
OPINENC	DES	Output PIN encryption key.	Double-length or triple-length key.	Double-length
PINCALC*	AES	PIN calculation key.	128-bit, 192-bit, or 256-bit key.	256-bit
PINGEN	DES	PIN generating key.	Double-length or triple-length key.	Double-length
PINPROT*	AES	PIN protection key.	128-bit, 192-bit, or 256-bit key.	256-bit
PINPRW*	AES	PIN reference value key.	128-bit, 192-bit, or 256-bit key.	256-bit
PINVER	DES	PIN verification key.	Double-length or triple-length key.	Double-length

All these types of keys are stored in the CKDS.

Note:

1. Key types CIPHERXI, CIPHERXL, and CIPHERXO have control vectors with guaranteed unique key halves. Key-encrypting keys that are used to wrap these key types must have control vectors with guaranteed unique key halves. These key-encrypting keys can be generated by using KGUP by specifying the DOUBLEO keyword in the control statement.
2. The key types that are marked with an asterisk (*) require additional information to create the key. See the KEYUSAGE keyword for the values that must be specified.

ALGORITHM(DES|AES)

This keyword defines the algorithm of the key you are generating. DES is the default value except for key types that are not supported for the DES algorithm. When only one algorithm is supported for the key type, the keyword is optional. The supported algorithms for all key types are listed in Table 1. Generated operational keys are encrypted under the respective master key.

Note:

• To use an algorithm, the master key of the algorithm must be active.
• If you are going to create AES keys that use the variable-length format key token, the CKDS must be a variable-length record format or common record format (KDSR or KDSRL) CKDS and the key output data set must have a longer LRECL.

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.

See Table 2 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 2. Default and optional OUTTYPES allowed for each key TYPE

Type	Algorithm	OUTTYPE (Default)	OUTTYPE (Allowed)
CIPHER	AES	CIPHER	CIPHER
CIPHER	DES	CIPHER	CIPHER, CIPHERXI, CIPHERXL, CIPHERXO, ENCIPHER, DECIPHER
CIPHERXI	DES	CIPHERXO	CIPHER, CIPHERXO, ENCIPHER
CIPHERXL	DES	CIPHERXL	CIPHER, CIPHERXL
CIPHERXO	DES	CIPHERXI	CIPHER, CIPHERXI, DECIPHER
CLRAES		Not Allowed	Not Allowed
CLRDES		Not Allowed	Not Allowed
DATA	AES	Not Allowed	Not Allowed
DATA	DES	DATA	DATA
DATAM	DES	DATAMV	DATAM, DATAMV
DATAMV	DES	Not Allowed	Not Allowed
DECIPHER	DES	ENCIPHER	CIPHER, CIPHERXO, ENCIPHER
DKYGENKY*	AES, DES	DKYGENKY*	DKYGENKY*
ENCIPHER	DES	DECIPHER	CIPHER, CIPHERXI, DECIPHER
EXPORTER	AES, DES	IMPORTER	IMPORTER
IMPORTER	AES, DES	EXPORTER	EXPORTER
IMPPKA	DES	EXPORTER	EXPORTER
IPINENC	DES	OPINENC	OPINENC
KEYGENKY*	DES	KEYGENKY*	KEYGENKY*
MAC*	AES	MAC*	MAC*
MAC	DES	MACVER	MAC, MACVER
MACVER	DES	Not Allowed	Not Allowed
NULL		Not Allowed	Not Allowed
OPINENC	DES	IPINENC	IPINENC
PINCALC*	AES	Not Allowed	Not Allowed
PINGEN	DES	PINVER	PINVER
PINPROT*	AES	PINPROT*	PINPROT*, CIPHER
PINPRW*	AES	PINPRW*	PINPRW*
PINVER	DES	Not Allowed	Not Allowed

Note: The key types that are marked with an asterisk (*) require additional information to create the key and the key's complement. See the KEYUSAGE keyword for the values that must be specified.

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

This keyword identifies the label of a transport key that 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. The algorithm of the transport key must match the key that is being wrapped, that is, an AES key must be wrapped with an AES transport key. Also, you should make sure the strength of the transport key is sufficient to wrap the key being generated. A triple-length DES keys should be wrapped with a triple-length transport key.

The transport key may be in a CCA key token or TR-31 key block. 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.

When KGUP generates a key, the program enciphers the key under the appropriate master key. KGUP can also generate a key value that can be used to create the key's complement. You can have KGUP encrypt the key value with a transport key. On the control statement, use the TRANSKEY keyword to specify an EXPORTER key-encrypting 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.

Notes:

• If you specify this keyword on the UPDATE control statement and you do not supply a key value, KGUP generates a new key value and updates the existing record with the new key value in the CKDS. For more information, see Example 7: UPDATE Control Statement with Key Value and Transkey Keywords.
• TRANSKEY is disallowed with KEYMGT(WRAPENH3).

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

For DES key types: When you input a key value that is in importable form, the key that is specified by the KEY keyword is enciphered under an IMPORTER key-encrypting 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. When the key being imported with the original wrapping method for DES keys, only the key value is required. When enhanced wrapping is used, the KEYMGT('WRAP-ENH') keyword is required along with the key value.

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 that are used for this communication. KGUP generates control statements that you send to the sites. Then, the sites' KGUPs establish the keys that 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 DES NOCV key-encrypting keys. 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. If you have specified a key type of DATA for the TYPE keyword with an algorithm of AES for the ALGORITHM keyword, you cannot use the TRANSKEY keyword.

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 can 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 CCA key tokens, 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 DES 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.

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(n), SINGLE, DOUBLEO, $TRIPLE, and $TRIPLEO

The LENGTH keyword specifies the length of the key value. Specifying the length of the key is optional. If the length is not specified, the default length is used.

For AES keys and CLRAES, LENGTH(16) generates a 128-bit key, LENGTH(24) generates a 192-bit key, and LENGTH(32) generates a 256-bit key. The SINGLE, DOUBLEO, $TRIPLE, and $TRIPLEO keywords are not allowed.

For CLRDES keys, LENGTH(8) generates a single-length key, LENGTH(16) generates a double-length key and LENGTH(24) generates a triple-length key. The SINGLE, DOUBLEO, $TRIPLE, and $TRIPLEO keywords are not allowed.

For DES keys:

• LENGTH(8) generates a single-length key.
• LENGTH(16) generates a double-length key.
• LENGTH(24) generates a triple-length key for key type DATA only. The control vector will be zeros. Not valid with other key types.
• For key types that are double-length by default, LENGTH(8) or SINGLE in an ADD or UPDATE statement causes KGUP to generate a double-length key with both key halves the same. On the KGUP panel, you can achieve this by specifying 8 in the LENGTH field for a double-length key type.
• For most double-length key types, specifying DOUBLEO causes KGUP to create a double length key with guaranteed unique key halves. The control vector is modified to indicate this.
• $TRIPLE generates a triple-length key for those key types which can be triple-length. All key tokens will have a control vector including DATA keys.
• For those key types which can be triple-length, specifying $TRIPLEO causes KGUP to create a triple-length key with guaranteed unique key values. The control vector is modified to indicate this.

Table 3. DES key types and supported key lengths

Key Type	Single-length(K1)	Double-length replicated key parts (K1 || K1)	Double-length (K1 || K2)	Triple-length (K1 || K2 || K3)
CIPHER	LENGTH(8) or SINGLE	Note 1	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
CIPHERXI	Not allowed	Not allowed	LENGTH(16) or DOUBLEO	Not allowed
CIPHERXL	Not allowed	Not allowed	LENGTH(16) or DOUBLEO	Not allowed
CIPHERXO	Not allowed	Not allowed	LENGTH(16) or DOUBLEO	Not allowed
DATA zero CV	LENGTH(8) or SINGLE	Note 1	LENGTH(16)	LENGTH(24)
DATA standard CV	Not allowed	Not allowed	Not allowed	$TRIPLE or $TRIPLEO
DATAM	Not allowed	Not allowed	LENGTH(16)	Not allowed
DATAMV	Not allowed	Not allowed	LENGTH(16)	Not allowed
DECIPHER	LENGTH(8) or SINGLE	Note 1	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
DKYGENKY	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	Not allowed
ENCIPHER	LENGTH(8) or SINGLE	Note 1	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
EXPORTER	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
IMPORTER	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
IMPPKA	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
IPINENC	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
MAC	LENGTH(8) or SINGLE	Note 1	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
MACVER	LENGTH(8) or SINGLE	Note 1	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
OPINENC	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
PINGEN	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO
PINVER	Not allowed	LENGTH(8) or SINGLE	LENGTH(16) or DOUBLEO	$TRIPLE or $TRIPLEO

Note 1

The only way to get a double-length key with replicated key values for these key types is to supply the key values with the KEY( ) and CLEAR keywords.

In any 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.
• The SINGLE, DOUBLEO, $TRIPLE, and $TRIPLEO keywords are mutually exclusive.
• The SINGLE, $TRIPLE, and KEY keywords are mutually exclusive.
• The DOUBLEO and $TRIPLEO keywords can be specified with the KEY keyword when unique key values are supplied. The control vector is modified.

KEY (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, DOUBLE, or $TRIPLE keywords with this keyword. Each key part consists of exactly 16 characters that represent 8 hexadecimal values.

Note: KGUP does not create complementary key control statement for existing key labels nor for a key label that has CLEAR keyword specified in the KGUP statement. When the TRANSKEY keyword is specified with KEY, KGUP does not create an entry in the control statement output data set.

For key types CLRDES and CLRAES, the key value is the clear value you want to be stored in the key token. The CLEAR keyword is not allowed. For CLRDES, you must supply one, two, or three parts. For CLRAES, you must supply two, three, or four parts.

AES keys

For AES keys, the key value is the clear value you want to import to be stored in the key token wrapped by the master key.

• You must supply two, three, or four parts.
• The CLEAR keyword is required. The TRANSKEY keyword is not allowed.

DES keys

For DES keys, the key value is either:

• The clear value you want to import to be stored in the key token wrapped by the master key. The CLEAR keyword is required.
• The encrypted value to import to be stored in the key token wrapped by the master key. The TRANSKEY keyword is required. If the key value is wrapped with the SHA-1 enhanced wrapping method, the KEYMGT('WRAP-ENH') keyword must be specified for the key to be imported correctly. Triple-length keys are always wrapped with the SHA-256 enhanced wrapping method and there is no need to indicate the wrapping method.

When you supply one key value,

• For keys that can be single-length, a single-length key is returned.
• For keys that are double-length by default, a double-length key with replicated key values is returned.

When you supply two key values, a double-length key is returned. You should not supply the same value twice in the keyword. When you specify DOUBLEO, the two values must not be the same. The control vector will indicate unique key values.

When you supply three key values, a triple-length key is returned. You should not supply the same value twice in the keyword. When you specify $TRIPLEO, all three key values must be unique. The control vector will indicate unique key values.

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.

Complementary key pairs

Most key types have complementary key type. See Table 2 for more information.

You cannot generate one key of a key pair without supplying a key value for the key. You must specify the KEY keyword.

KEYUSAGE(key-usage-value[,key-usage-value]...)

This keyword defines key usage values for the key that is being generated. The usage values are used to restrict a key to a specific algorithm or usage.

The associated data for variable length tokens is described in Appendix B of the Application Programmer's Guide. The DES control vector is described in Appendix C. of the Application Programmer's Guide.

The following values have been defined. The usage values are specific to a key type. The values can only be specified for the key type that is indicated in the following tables.

Note: Any value with a non-alphanumeric character must be enclosed in quotes when specified with the KEYUSAGE keyword. For example:

KEYUSAGE( 'CVVKEY-A' )

When a pair of keys is generated, one for the local system and the other for a remote system, both keys are generated with the same key-usage flags when the KEYUSAGE keyword is used.

Table 4. Usage values for key types

Key type	Key algorithm	Key Usage Values
CIPHER	AES	The following values are optional: C-XLATE, V1PYLD and One of following value is optional: ANY-MODE, FF1, FF2, FF2.1, GCM and One or both can be specified: DECRYPT, ENCRYPT. Notes: The key generated when KEYUSAGE is not specified has only the DECRYPT and ENCRYPT key-usage. This is the default. When no encryption mode keyword is specified, the encryption mode defaults to CBC.
DKYGENKY	DES	One of the following must be specified: DKYL0, DKYL1, DKYL2, DKYL3, DKYL4, DKYL5, DKYL6, DKYL7 and One of the following must be specified: DALL, DDATA, DEXP, DIMP, DMAC, DMKEY, DMPIN, DMV, DPVR
DKYGENKY	AES	One of the following must be specified: D-PPROT, D-PCALC, D-PPRW and One of the following values must be specified: DKYL0, DKYL1, DKYL2 and The following values are required: KUF-MBE, DKYUSAGE
DKYGENKY	AES	One of the following must be specified: D-MAC, D-SECMSG and The following value is required: DKYUSAGE and One of the following values must be specified: KUF-MBE, KUF-MBP and One of the following values must be specified: DKYL0, DKYL1, DKYL2
DKYGENKY	AES	The following value is required: D-CIPHER and One of the following values must be specified: DKYL0, DKYL1, DKYL2 and The following value is optional: DKYUSAGE and One of the following values may be specified when DKYUSAGE is specified: KUF-MBE, KUF-MBP (KUF-MBE is the default)
DKYGENKY	AES	One of the following must be specified: D-ALL, D-EXP, D-IMP and One of the following values must be specified: DKYL0, DKYL1, DKYL2
EXPORTER	AES	The following value is optional: V1PYLD             and The following values are optional, but both must be specified together: EXPTT31D, VARDRV-D. When the EXPTT31D keyword is not specified, all other exporter control keywords are enabled in the generated key. When the EXPTT31D keyword is specified, the key can only be used with the CSNBT31X service.
IMPORTER	AES	The following value is optional: V1PYLD             and The following values are optional, but both must be specified together: IMPTT31D, VARDRV-D. When the IMPTT31D keyword is not specified, all other importer control keywords are enabled in the generated key. When the IMPTT31D keyword is specified, the key can only be used with the CSNBT31X service.
KEYGENKY	DES	One of the following must be specified: UKPT, CLR8-ENC
MAC	DES	One of the following may be specified: ANY-MAC, CVVKEY-A, CVVKEY-B
MACVER	DES	One of the following may be specified: ANY-MAC, CVVKEY-A, CVVKEY-B
MAC	AES	One of the following must be specified: GENERATE, GENONLY, VERIFY and The following value must be specified: CMAC and One of the following is optional: DKPINOP, DKPINAD1, DKPINAD2 Notes: One of either DKPINOP, DKPINAD1, or DKPINAD2 is required for keys to be used with the DK PIN services. When DKPINOP, DKPINAD1, or DKPINAD2 is specified, GENERATE is not allowed.
PINCALC	AES	Three values must be specified: GENONLY, DKPINOP, and CBC.
PINPROT	AES	The following values must be specified: ENCRYPT, CBC and One of the following must be specified: DKPINOPP, DKPINOP, DKPINAD1.
PINPROT	AES	One of the following must be specified: ENCRYPT, DECRYPT and The following values must be specified: NOFLDFMT, CBC, ISO-4. Note: All PIN services key usage controls will be enabled.
PINPRW	AES	One of the following must be specified: GENONLY, VERIFY and The following values must be specified: DKPINOP, CMAC

Notes:

• Note that certain key usage for these key types prevent a single key from being generated. A complementary key is required or a key value must be specified with the KEY keyword.
• Diversified Key Generating Keys: The key-derivation sequence level specifies the hierarchical level of the DKYGENKY. If the sequence level is non-zero, the DKYGENKY can only generate another DKYGENKY key with the sequence level decremented by one. If the sequence level is zero, the DKYGENKY can only generate the final diversified key (a non-DKYGENKY key) with the key type specified by the usage bits.
• PINPROT Keys: When specifying an AES CIPHER as the OUTTYPE for an AES PINPROT key, the key usage values must be ENCRYPT and DKPINOPP. The key usage value for the AES CIPHER key is DECRYPT.

Table 5. Meaning of usage values

Key Usage Value	Key types	Meaning
ANY-MAC	MAC, MACVER	The MAC usage field (control vector offset 0-3) is set to '0000'b. There is no restriction for this key. This is the default value.
ANY-MODE	CIPHER	This key can be used for any encryption mode.
C-XLATE	CIPHER	Restricts the key to be used with the cipher text translate2 service only.
CBC	PINCALC, PINPRW	Use the CBC encryption mode.
CLR8-ENC	KEYGENKY	The CLR8-ENC key usage bit (control vector offset 19) is set to '1'b. The key can only be used with the 'CLR8-ENC' rule array keyword for CSNBDKG.
CMAC	MAC, PINPROT	Use the CMAC algorithm.
CVVKEY-A	MAC, MACVER	The MAC usage field (control vector offset 0-3) is set to '0010'b. When this key is used with CSNBCVG or CSNBCVV, it can only be used as the key A parameter. This is valid with single- and double-length keys.
CVVKEY-B	MAC, MACVER	The MAC usage field (control vector offset 0-3) is set to '0011'b. When this key is used with CSNBCVG or CSNBCVV, it can only be used as the key B parameter. This is valid with single-length keys.
D-ALL	DKYGENKY	All key types can be derived except DKYGENKY keys.
D-CIPHER	DKYGENKY	CIPHER keys can be derived.
D-EXP	DKYGENKY	EXPORTER and OKEYXLAT keys can be derived.
D-IMP	DKYGENKY	IMPORTER and IKEYXLAT keys can be derived.
D-MAC	DKYGENKY	MAC keys can be derived.
D-PCALC	DKYGENKY	PINCALC keys can be derived.
D-PPROT	DKYGENKY	PINPROT keys can be derived.
D-PPRW	DKYGENKY	PINPRW keys can be derived.
D-SECMSG	DKYGENKY	SECMSG keys can be derived.
DALL	DKYGENKY	All key types can be generated except DKYGENKY and KEYGENKY keys. Usage is restricted by an access control point. See the Diversified Key Generate callable service.
DDATA	DKYGENKY	Generate single- and double-length DATA keys.
DECRYPT	PINPROT CIPHER	This key can be used to decrypt DK PIN blocks. This key can be used to decrypt data.
DEXP	DKYGENKY	Generate EXPORTER and OKEYXLAT keys.
DIMP	DKYGENKY	Generate IMPORTER and IKEYXLAT keys.
DKPINAD1	MAC, PINPROT	This key can be used in the DK PIN protection methods to create or verify a pin block to allow the changing of the account number that is associated with a PIN.
DKPINAD2	MAC	This key can be used in the DK PIN protection methods to create or verify an account change string to allow the changing of the account number that is associated with a PIN.
DKPINOP	MAC, PINCALC, PINPROT, PINPRW	This key can be used in the DK PIN protection methods as a general-purpose key. It cannot be used as a special-purpose key.
DKPINOPP	PINPROT	This key is to be used to encrypt a PBF-1 format pin block for the specific purpose of creating a DK PIN mailer.
DKYL0	DKYGENKY	Specifies that this key-generating key can be used to derive the key that is specified by the Key derivation and Derived key usage controls (AES) or control vector (DES).
DKYL1	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL0.
DKYL2	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL1.
DKYL3	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL2.
DKYL4	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL3.
DKYL5	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL4.
DKYL6	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL5.
DKYL7	DKYGENKY	Specifies that this key-generating key can be used to derive a DKYGENKY with a subtype of DKYL6.
DKYUSAGE	DKYGENKY	Specifies that the DKYUSAGE keyword identifies key usage information for the key to be derived by the DKYGENKY. This value is required when the key type to be derived is MAC, PINCALC, PINPROT, PINPRW, and SECMSG. Not valid for D-ALL, D-CIPHER, D-IMP, and D-EXP.
DMAC	DKYGENKY	Single-length and double-length MAC keys can be derived.
DMKEY	DKYGENKY	Secure messaging keys for encrypting keys can be derived..
DMPIN	DKYGENKY	Secure messaging keys for encrypting PINs can be derived.
DMV	DKYGENKY	Single-length and double-length MACVER keys can be derived.
DPVR	DKYGENKY	PINVER keys can be derived.
ENCRYPT	PINPROT CIPHER	This key can be used to encrypt DK PIN blocks. This key can be used to encrypt data.
EXPTT31D	EXPORTER	Key can be used with CSNBT31X to export an AES KDKGENKY or DES DKYGENKY key.
FF1	CIPHER	This key can be used for Format Preserving method FF1.
FF2	CIPHER	This key can be used for Format Preserving method FF2.
FF2.1	CIPHER	This key can be used for Format Preserving method FF2.1.
GCM	CIPHER	This key can be used for Galois/counter mode.
GENERATE	MAC	This key can generate and verify MACs.
GENONLY	MAC, PINCALC, PINPRW	This key can be used to only generate data (MACs, PINs, or PRWs).
IMPTT31D	IMPORTER	Key can be used with CSNBT31I to import an TR-31 key block version “D”.
ISO-4	PINPROT	Specifies that ISO-4 PIN blocks can be wrapped.
KUF-MBE	DKYGENKY	Specifies that the key usage fields of the key to be generated must be equal to the related generated key usage fields of the DKYGENKY generating key. Not valid for D-ALL, D-CIPHER, D-IMP, and D-EXP.
KUF-MBP	DKYGENKY	Specifies that the key usage fields of the key to be generated must be permitted based on the related generated key usage fields of the DKYGENKY generating key. The key to be derived is not permitted to have a higher level of usage than the related key usage fields permit. The key to be derived is only permitted to have key usage that is less than or equal to the related key usage fields. Not valid for D-ALL, D-CIPHER, D-IMP, and D-EXP.
NOFLDFMT	PINPROT	Specifies that there is no field format identifier.
UKPT	KEYGENKY	The UKPT key usage bit (control vector offset 18) is set to '1'b. The key can only be used in the CSNBPTR and CSNBPVR services.
VARDRV-D	EXPORTER, IMPORTER	Key can be used to wrap or unwrap an AES TR-31 key block version “D”.
VERIFY	MAC, PINPRW	This key can be used to verify data (MACs or PRWs).
V1PYLD	CIPHER, EXPORTER, IMPORTER	The generated key or keys have version 1 (fixed-length) format of the payload for the variable-length symmetric key token. Applies to AES keys only.

Notes:

• Diversified Key Generating Key Note: The subtype field specifies the hierarchical level of the DKYGENKY. If the subtype is non-zero, then the DKYGENKY can only generate another DKYGENKY key with the hierarchy level that is decremented by one. If the subtype is zero, the DKYGENKY can only generate the final diversified key (a non-DKYGENKY key) with the key type that is specified by the usage bits.
• PINPROT Keys: When specifying an AES CIPHER as the OUTTYPE for an AES PINPROT key, the key usage values must be ENCRYPT and DKPINOPP. The key usage value for the AES CIPHER key is DECRYPT.
• AES MAC Keys: When DKPINOP, DKPINAD1, or DKPINAD2 is specified, GENERATE is not allowed.

DES

This keyword is no longer supported but is tolerated.

KEYMGT(key-management-value1[,key-management-value2])

This keyword defines the key management value for the key that is being generated. The values are used to govern the management of the key.

The associated data for variable length tokens is described in Appendix B of z/OS Cryptographic Services ICSF Application Programmer's Guide. The DES control vector is described in Appendix C of z/OS Cryptographic Services ICSF Application Programmer's Guide.

The following values are defined. The management values are specific to a key type. The values can be specified only for the key type that is indicated in Table 8 and Table 9.

Note: Any value with a non-alphanumeric character must be enclosed in quotation marks when specified with the KEYMGT keyword. For example, KEYMGT( ’COMP-TAG’ ).

When a pair of keys is generated (one for the local system and the other for a remote system), both keys are generated with the same key-management values when the KEYMGT keyword is used.

KGUP adds the KEYMGT('WRAP-ENH') keyword to the output control statement when the default wrapping method is enhanced.

Table 8. Management values for key types

Key type	Key algorithm	Key management values
CIPHER	AES	The following values are optional: COMP-TAG, XPRTCPAC.
CIPHER	DES	The following values are optional: COMP-TAG, XPRTCPAC, and either WRAP-ENH or WRAPENH3.
CIPHERXI	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
CIPHERXL	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
CIPHERXO	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
DATA	DES	The following value is optional: WRAP-ENH.
DATAM	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
DATAMV	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
DECIPHER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
DKYGENKY	AES	The following value is optional: COMP-TAG.
DKYGENKY	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
ENCIPHER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
EXPORTER	AES	The following value is optional: COMP-TAG.
EXPORTER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
IMPORTER	AES	The following value is optional: COMP-TAG.
IMPORTER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
IMPPKA	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
IPINENC	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
KEYGENKY	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
MAC	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
MACVER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
OPINENC	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
PINCALC	AES	The following value is optional: COMP-TAG.
PINGEN	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.
PINPROT	AES	The following value is optional: COMP-TAG.
PINPRW	AES	The following value is optional: COMP-TAG.
PINVER	DES	The following values are optional: COMP-TAG, and either WRAP-ENH or WRAPENH3.

Table 9. Meaning of management values

Key management value	Key types	Meaning and notes
COMP-TAG	DES: CIPHER, CIPHERXI, CIPHERXL, CIPHERXO, DATAM, DATAMV, DECIPHER, DKYGENKY, ENCIPHER, EXPORTER, IMPORTER, IMPPKA, IPINENC, KEYGENKY, MAC, MACVER, OPINENC, PINGEN, PINVER. AES: CIPHER, DKYGENKY, EXPORTER, IMPORTER, PINCALC, PINPROT, PINPRW.	The key is marked to be used with PCI-HSM compliant applications. This value cannot be used with single-length keys. This value cannot be used when the NOCV keyword is specified.
WRAP-ENH	All DES key types.	The wrapping method is the enhanced method with SHA-1. The wrapping method is ANSI X9.24 compliant.
WRAPENH3	All DES key types except DATA.	The wrapping method is the enhanced method with SHA-256 and CMAC authentication code. Note: When the XFACILIT class CSF.WRAPENH3.OVERRIDE discrete profile exists and the user has READ access to the profile, the WRAPENH3 method will be used.
XPRTCPAC	DES: CIPHER. AES: CIPHER.	The key can be exported to CPACF protected key format.

DKYGENKYUSAGE(key-usage-value1[,key-usage-value2])

This keyword defines key usage values to be supplied for the AES DKYGENKY key that is being generated. This keyword is required when the DKYUSAGE value is specified in the KEYUSAGE keyword.

The following values have been defined. The usage values are specific to the key type to be derived. The values can be specified only for the key type that is indicated in Table 10 and Table 11. The values for the specific key types are detailed in this document in the Key Token Build2 callable service description.

Note: Any value with a non-alphanumeric character must be enclosed in quotation marks when specified with the DKYGENKYUSAGE keyword. For example, DKYGENKYUSAGE( ’CVVKEY-A’ ).

Table 10. Values by type for DKYGENKYUSAGE

Type of key to be derived	DKYGENKYUSAGE values
CIPHER	The following values are optional: C-XLATE, DECRYPT, ENCRYPT Note: The key that is generated when DKYGENKYUSAGE is not specified has DECRYPT and ENCRYPT key-usage. This is the default.
MAC	One of the following values is required: GENERATE, GENONLY, VERIFY                                                and The following value is required: CMAC                                                and One of the following values is optional: DKPINAD1, DKPINAD2, DKPINOP Notes: One of DKPINOP, DKPINAD1, or DKPINAD2 is required for keys to be used with the DK PIN services. When DKPINOP, DKPINAD1, or DKPINAD2 is specified, GENERATE is not allowed.
PINCALC	The following values are required: GENONLY, CBC, DKPINOP.
PINPROT	One of the following values is required: DECRYPT, ENCRYPT                                                and The following value is required: CBC                                                and One of the following values is required: DKPINAD1, DKPINOP, DKPINOPP
PINPRW	One of the following values is required: GENONLY, VERIFY                                                and The following values are required: CMAC, DKPINOP
SECMSG	The following value is required: SMPIN                                                and One of the following values is required: ANY-USE, DPC-ONLY

Table 11. Meaning of usage values

Value	Key types	Description
ANY-USE	SECMSG	The use of the key in a callable service is not restricted.
CBC	PINPROT, PINCALC	The derived key must use the CBC encryption mode.
CMAC	MAC, PINPRW	The derived key must use the CMAC algorithm.
C-XLATE	CIPHER	Restricts the key to be used with the cipher text translate2 service only.
DPC-ONLY	SECMSG	The use of the key is restricted to the DK PIN Change service.
DECRYPT	CIPHER, PINPROT	The derived key can be used to decrypt PIN blocks.
DKPINAD1	MAC, PINPROT	The derived key can be used to create or verify a pin block to allow changing the account number associate with a PIN for the DK PIN methods.
DKPINAD2	MAC	The derived key can be used to create or verify an account change string to allow changing the account number that is associated with a PIN for the DK PIN methods.
DKPINOP	MAC, PINCALC, PINPROT, PINPRW	The derived key can be used as a general-purpose key for the DK PIN methods.
DKPINOPP	PINPROT	The derived key can be used to encrypt a PIN block for the specific purpose of creating a PIN mailer for the DK PIN methods.
ENCRYPT	CIPHER, PINPROT	The derived key can be used to encrypt PIN blocks.
GENERATE	MAC	The derived key can be used to generate and verify MACs.
GENONLY	MAC, PINCALC	The derived key can be used to generate MACs or PINs.
SMPIN	SECMSG	Enable the encryption of PINs in an EMV secure message.
VERIFY	MAC	The derived key can be used to verify MACs.

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.