Syntax of the ADD and UPDATE control statements

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 1 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 | DOUBLEO]

   [KEY(key-value1[,...,key-value4])]

   [KEYUSAGE(key-usage-value1[,...,key-usage-value2])]

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

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 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 the following table.

Table 1. Key types

Key Type	Algorithm	Usage	Notes
CIPHER	AES	Data-encrypting key for the CSNBSAD and CSNBSAE services	128-, 192, or 256-bit key
CIPHER	DES	Data-encrypting key for the CSNBDEC and CSNBENC services	Single- or double-length key
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 is required.
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 is required.
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 is required.
CLRAES		Clear AES data-encrypting key for the CSNBSYD and CSNBSYE services	128-, 192, or 256-bit key
CLRDES		Clear DES data-encrypting key for the CSNBSYD and CSNBSYE services	Single-, double-, or triple-length key
DATA	AES, DES	Data-encrypting key for the CSNBDEC, CSNBENC, CSNBSAD, and CSNBSAE services	Single-, double-, or triple-length key for DES 128-, 192-, or 256-bit key for AES
DATAM	DES	Double-length MAC generation key	Double-length key DOUBLEO not allowed
DATAMV	DES	Double-length MAC verification key	Double-length key DOUBLEO not allowed
DECIPHER	DES	Data-decrypting key for the CSNBDEC service	Single- or double-length key.
DKYGENKY*	AES, DES	Diversified key generating key for CSNBDKG and CSNBDKG2 services	Double-length key for DES 128-, 192-, or 256-bit key for AES
ENCIPHER	DES	Data-encrypting key for the CSNBENC service	Single- or double-length key
EXPORTER	AES, DES	Exporter key-encrypting key	Double-length key for DES 128-, 192, or 256-bit key for AES
IMPORTER	AES, DES	Importer key-encrypting key	Double-length key for DES 128-, 192, or 256-bit key for AES
IMPPKA	DES	Limited authority importer key-encrypting key	Double-length key
IPINENC	DES	Input PIN encryption key	Double-length key
KEYGENKY*	DES	Key generating key for DUKPT. Used with CSNBPTR, CSNBPTV, CSNBDKG, and CSNBUKD services	Double-length key
MAC*	AES	MAC generation and verification key	128-, 192-, or 256-bit key for AES
MAC	DES	MAC generation key	Single- or double-length key
MACVER	DES	MAC verification key	Single- or double-length key
NULL	AES, DES	Used to create a null CKDS entry
OPINENC	DES	Output PIN encryption key	Double-length key
PINCALC*	AES	PIN calculation key	128-, 192-, or 256-bit key
PINGEN	DES	PIN generating key	Double-length key
PINPROT*	AES	PIN protection key	128-, 192-, or 256-bit key
PINPRW*	AES	PIN reference value key	128-, 192-, or 256-bit key
PINVER	DES	PIN verification key	Double-length key

All these types of keys are stored in the CKDS.

Note:

1. For compatibility with previous releases of CSF, KGUP stores internal versions of DATAM and DATAMV keys in the CKDS under the key types of MACD and MACVER, respectively.
2. Key types CIPHERXI, CIPHERXL, and CIPHERXO have control vectors with guaranteed unique key halves. Key-encrypting keys used to wrap these key types must have control vectors with guaranteed unique key halves. These key-encrypting keys can be generated using KGUP by specifying the DOULBEO keyword in the control statement.
3. The key types 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 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 is listed in the table under the TYPE keyword. Generated operational keys will be 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 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.

Refer to 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	AES, DES	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 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 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. The algorithm of the transport key must match the key being wrapped, that is, an AES key must be wrapped with an AES transport key.

When KGUP generates a key, the program enciphers the key under the appropriate master key. 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 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.

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 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.

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 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.

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 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.

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

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 will be 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 and DOUBLEO 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 and DOUBLEO keywords are not allowed.

For DES keys:

• LENGTH(8) generates a single-length key, LENGTH(16) generates a double-length key, and LENGTH(24) generates a triple-length key (DATA only).
• For most double-length key types, 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. A key with this control vector cannot be used on systems with the Cryptographic Coprocessor Feature.

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 and DOUBLEO keywords are mutually exclusive.
• The SINGLE and KEY keywords are mutually exclusive.
• The DOUBLEO keyword can be specified with the KEY keyword when two different key values are supplied. The control vector will be modified.

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.

CAUTION:

KGUP does not create complementary key control statement for existing key labels, nor new a key label that has CLEAR parm specified in the KGUP statement.

This keyword is required when you specify either DATAMV, MACVER, or PINVER for the TYPE keyword. Because these type of keys require a complementary key to be used, you must always supply values for these types of keys.

This keyword is required when you specify CIPHERXI, CIPHERXO, DECIPHER, or ENCIPHER for the TYPE keyword and the TRANSKEY and OUTTYPE are not supplied. Because these type of keys require a complementary key to be used, you must always supply values for these types of keys.

For a double-length key, supply two key values. If you supply only one key value, KGUP will duplicate the key value as the second key value. KGUP concatenates these two identical values, and then stores and uses the key as if the key was double-length. For key types CIPHERXI, CIPHERXL, and CIPHERXO, the two keys values must be supplied and cannot be the same value.

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.

For an AES CIPHER, EXPORTER or IMPORTER key, you must supply two, three or four parts. Note that when the TRANSKEY keyword is specified with these keys, KGUP will not create an entry in the Control Statement Output data set.

KEYUSAGE(key-usage-value1[,...,key-usage-value2])

This keyword defines key usage values for the key 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 indicated in the tables below.

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 will be generated with the same key-usage flags when the KEYUSAGE keyword is used.

Table 3. Usage values for key types

Key type	Key algorithm	Key Usage Values
CIPHER	AES	The following values are optional: C-XLATE, V1PYLD                                            and One or both may be specified: DECRYPT, ENCRYPT. Note: The key generated when KEYUSAGE is not specified will have only the DECRYPT and ENCRYPT key-usage. This is the default.
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 The following values are required: DKYL0, KUF-MBE, DKYUSAGE
DKYGENKY	AES	The following values are required: D-MAC, DKYL0, DKYUSAGE                                            and One of the following values must be specified: KUF-MBE, KUF-MBP
DKYGENKY	AES	The following values are required: D-CIPHER, DKYL0                                              and The following value is optional: DKYUSAGE                                              and One of the following values may be specified when DKYUSAGE is specified: KUF-MBE, KUF-MBP (KUP-MBE is the default)
DKYGENKY	AES	One of the following must be specified: D-ALL, D-EXP, D-IMP                                              and The following value is required: DKYL0
EXPORTER	AES	The following value is optional: V1PYLD
IMPORTER	AES	The following value is optional: V1PYLD
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 Note: 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	AES	Three values must be specified: GENONLY, DKPINOP, and CBC.
PINPROT	AES	One of the following must be specified: ENCRYPT, DECRYPT                                             and One of the following must be specified: DKPINOPP, DKPINOP, DKPINAD1                                             and The following value must be specified: CBC
PINPRW	AES	One of the following must be specified: GENONLY, VERIFY                                             and The following values must be specified: DKPINOP, CMAC

Note:

• DES Diversified Key Generating Keys: The subtype field specifies the hierarchical level of the DKYGENKY. If the subtype is non-zero, the DKYGENKY can only generate another DKYGENKY key with the hierarchy level 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 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 DKINOPP. The key usage value for the AES CIIPHER key is DECRYPT.

Table 4. 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.
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 may 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 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 may be derived except DKYGENKY keys.
D-CIPHER	DKYGENKY	CIPHER keys may be derived.
D-EXP	DKYGENKY	EXPORTER keys may be derived.
D-IMP	DKYGENKY	IMPORTER keys may be derived.
D-MAC	DKYGENKY	MAC keys may be derived.
D-PCALC	DKYGENKY	PINCALC keys may be derived.
D-PPROT	DKYGENKY	PINPROT keys may be derived.
D-PPRW	DKYGENKY	PINPRW keys may be derived.
DALL	DKYGENKY	All key types may be generated except DKYGENKY and KEYGENKY keys. Usage is restricted by an access control point. See 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 may be used in the DK PIN protection methods to create or verify a pin block to allow the changing of the account number associated with a PIN.
DKPINAD2	MAC	This key may be used in the DK PIN protection methods to create or verify an account change string to allow the changing of the account number associated with a PIN.
DKPINOP	MAC, PINCALC, PINPROT, PINPRW	This key may be used in the DK PIN protection methods as a general-purpose key. It may not 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 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 and PINPRW. Not valid for D-ALL, D-CIPHER, D-IMP and D-EXP.
DMAC	DKYGENKY	Generate single- and double-length MAC keys
DMKEY	DKYGENKY	Generate secure messaging keys for encrypting keys
DMPIN	DKYGENKY	Generate secure messaging keys for encrypting PINs
DMV	DKYGENKY	Generate single- and double-length MACVER keys
DPVR	DKYGENKY	Generate PINVER keys
ENCRYPT	PINPROT CIPHER	This key can be used to encrypt DK PIN blocks. This key can be used to encrypt data.
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).
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.
TRANSLAT	CIPHER	Restricts the key to be used with the cipher text translate2 service only.
UKPT	KEYGENKY	The UKPT key usage bit (control vector offset 18) is set to '1'b. The key may only be used in the CSNBPTR and CSNBPVR services.
VERIFY	MAC, PINPRW	This key can be used to verify data (MACs or PRWs).
V1PYLD	CIPHER, EXPORTER, IMPORTER	The generated key or keys will have version 1 (fixed-length) format of the payload for the variable-length symmetric key token. Applies to AES keys only.

Note:

• 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 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 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 DKINOPP. The key usage value for the AES CIIPHER 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.

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

This keyword defines key usage values to be supplied for the AES DKYGENKY key 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 only be specified for the key type indicated in Table 7 and Table 8. 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 quotes when specified with the DKYGENKYUSAGE keyword. For example: DKYGENKYUSAGE( ’CVVKEY-A’ ).

Table 7. 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 generated when DKYGENKYUSAGE is not specified will have 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 Note: 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

Table 8. Meaning of usage values

Value	Key types	Description
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.
DECRYPT	CIPHER, PINPROT	The derived key may be used to decrypt PIN blocks.
DKPINAD1	MAC, PINPROT	The derived key may 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 may be used to create or verify an account change string to allow changing the account number associated with a PIN for the DK PIN methods.
DKPINOP	MAC, PINCALC, PINPROT, PINPRW	The derived key may be used as a general purpose key for the DK PIN methods.
DKPINOPP	PINPROT	The derived key may 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 may be used to encrypt PIN blocks.
GENERATE	MAC	The derived key may be used to generate and verify MACs.
GENONLY	MAC, PINCALC	The derived key may be used to generate MACs or PINs.
VERIFY	MAC	The derived key may 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.