Common Cryptographic Architecture (CCA): Usage notes for CSNBKGN2

The key forms are defined as follows:

Operational (OP): The key value is enciphered under a master key. The result is placed into an internal key token. The key is then operational at the local system.
Importable (IM): The key value is enciphered under an importer key-encrypting key. The result is placed into an external key token. The corresponding key_encrypting_key_identifier_n parameter must contain an AES IMPORTER key token or label.
Exportable (EX): The key value is enciphered under an exporter key-encrypting key. The result is placed into an external key token. The corresponding key_encrypting_key_identifier_n parameter must contain an AES EXPORTER key token or label.

Key type specifications: Generated AES and HMAC keys returned in an internal key token are enciphered with the AES master key, while generated keys returned in an external key token are enciphered under an AES key-encrypting key.

There are two methods for specifying the type of keys to be generated:

One or two key type keywords are examined depending on the value of the key form rule-array keyword. Table 1 shows the permissible key type and key form keyword combinations to generate a single copy of a key. Table 2 shows the permissible key type and key form keyword combinations to generate two copies of a key.
Use the TOKEN keyword and provide a key token to be updated or a skeleton key-token to be completed.

Table 1. Key Generate2 key_type and key_form keywords for one AES or HMAC key
key_type_1	Required key usage	Key form OP	Key form IM or EX
CIPHER	DECRYPT and ENCRYPT	X	X
DKYGENKY^*	D-ALL	X	X
DKYGENKY^*	D-CIPHER	X	X
DKYGENKY^*	D-MAC	X	X
KDKGENKY (KDKTYPEA)	KDKGENKY (KDKTYPEB)	X	X
KDKGENKY (KDKTYPEB)	KDKGENKY (KDKTYPEA)	X	X
MAC^*	GENERATE and VERIFY	X	X
PINCALC^*	GENONLY	X	X
Note: An X indicates a permissible key type and key usage combination for a given key form. The key types marked with an asterisk must be requested through the specification of a proper key usage in a key token and the use of the TOKEN keyword. These key types are not recognized by the verb as key type keywords. A DKYGENKY is used by the Diversified Key Generate2 verb to ultimately derive a key with a different key type. The rules for generating a single DKYGENKY depend on the type of key to diversify: For D-ALL and D-SECMSG, there are no restrictions. For D-CIPHER and D-MAC, the related key usage fields (KUFs) defined in the DKYGENKY key must match the required key usage for the type of key to derive (that is, D-CIPHER requires DECRYPT and ENCRYPT, and D-MAC requires GENERATE and VERIFY). For D-KDKGKY, the related KUFs include one KDKGENKY related KUF which must match the required key usage for a KDKGENKY key, followed by one to four groups of active and passive related KUFs. The group related KUFs defined in the DKYGENKY key must match the required key usage for each pair of keys to derive, as defined in Table 2. A KDKGENKY is used by the Diversify Directed Key verb (Release 5.4 or later) to derive up to four different key types (MAC, CIPHER, PINPROT, or EXPORTER/IMPORTER). Each type of key to derive has related KUFs in an active/passive related KUF block. The group related KUFs defined in the KDKGENKY key must match the required key usage for each pair of keys to derive, as defined in Table 2. A pair of KDKGENKY keys or a pair of DKYGENKY keys with D-KDKGKY usage must have identical active or passive related KUF blocks. For example, it is an error if one of the two keys can diversify a MAC key and the other cannot. Another example is, if an EXPORTER key can be derived that allows a DES key to be wrapped (WR-DES), then it is an error if the IMPORTER cannot unwrap a DES key (WR-DES). Another example is, if a MAC key is to be derived and the key_type_1 parameter indicates related KUFs of GENONLY and NOOP, then the key_type_2 parameter must have indicated VERIFY and NOOP, and between this pair of key derivation operations, all other operations must be complete.

Table 2. Key Generate2 key_type and key_form keywords for a pair of AES or HMAC keys
key_type_1 (usage)	key_type_2 (usage)	key_form
key_type_1 (usage)	key_type_2 (usage)	OPOP	OPOP, OPIM, IMIM	OPEX	EXEX	IMEX
CIPHER	CIPHER		X	X	X	X
CIPHER	CIPHER (DECRYPT)		X	X	X	X
CIPHER	CIPHER (ENCRYPT)		X	X	X	X
CIPHER	CIPHER (DECRYPT C-XLATE)		X	X	X	X
CIPHER	CIPHER (ENCRYPT C-XLATE)		X	X	X	X
CIPHER	CIPHER (DECRYPT ENCRYPT C-XLATE)		X	X	X	X
CIPHER (DECRYPT)	CIPHER		X	X	X	X
CIPHER (DECRYPT)	CIPHER (DECRYPT)
CIPHER (DECRYPT)	CIPHER (ENCRYPT)		X	X	X	X
CIPHER (DECRYPT)	CIPHER (DECRYPT C-XLATE)
CIPHER (DECRYPT)	CIPHER (ENCRYPT C-XLATE)		X	X	X	X
CIPHER (DECRYPT)	CIPHER (DECRYPT ENCRYPT C-XLATE)
CIPHER (ENCRYPT)	CIPHER		X	X	X	X
CIPHER (ENCRYPT)	CIPHER (DECRYPT)		X	X	X	X
CIPHER (ENCRYPT)	CIPHER (ENCRYPT)
CIPHER (ENCRYPT)	CIPHER (DECRYPT C-XLATE)		X	X	X	X
CIPHER (ENCRYPT)	CIPHER (ENCRPYT C-XLATE)
CIPHER (ENCRYPT)	CIPHER (DECRYPT ENCRYPT C-XLATE)
CIPHER (DECRYPT C-XLATE)	CIPHER		X	E	X	E
CIPHER (DECRYPT C-XLATE)	CIPHER (DECRYPT)
CIPHER (DECRYPT C-XLATE)	CIPHER (ENCRYPT)		X	E	X	E
CIPHER (DECRYPT C-XLATE)	CIPHER (DECRYPT C-XLATE)
CIPHER (DECRYPT C-XLATE)	CIPHER (ENCRYPT C-XLATE)			E	X	E
CIPHER (DECRYPT C-XLATE)	CIPHER (DECRYPT ENCRYPT C-XLATE)
CIPHER (ENCRYPT C-XLATE)	CIPHER		X	E	X	E
CIPHER (ENCRYPT C-XLATE)	CIPHER (DECRYPT)		X	E	X	E
CIPHER (ENCRYPT C-XLATE)	CIPHER (ENCRYPT)
CIPHER (ENCRYPT C-XLATE)	CIPHER (DECRYPT C-XLATE)			E	X	E
CIPHER (ENCRYPT C-XLATE)	CIPHER (ENCRYPT C-XLATE)
CIPHER (ENCRYPT C-XLATE)	CIPHER (DECRYPT ENCRYPT C-XLATE)
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER		X	E	X	E
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER (DECRYPT)
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER (ENCRYPT)
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER (DECRYPT C-XLATE)
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER (ENCRPYT C-XLATE)
CIPHER (DECRYPT ENCRYPT C-XLATE)	CIPHER (DECRYPT ENCRYPT C-XLATE)			E	X	E
MAC^* (GENERATE)	MAC^* (GENERATE)		X	X	X	X
MAC^* (GENERATE)	MAC^* (VERIFY)		X	X	X	X
MAC^* (VERIFY)	MAC^* (GENERATE)		X	X	X	X
MAC^* (GENONLY)	MAC^* (VERIFY)		X	X	X	X
MAC^* (VERIFY)	MAC^* (GENONLY)		X	X	X	X
MAC^* (GENERATE)	MAC^* (GENONLY)		X	X	X	X
MAC^* (GENONLY)	MAC^* (GENERATE)		X	X	X	X
IMPORTER	EXPORTER		X	X	X	X
EXPORTER	IMPORTER			X	X	X
DKYGENKY^*	DKYGENKY^*		X	X	X	X
DKYGENKY^* (DMAC:MMSAUTH1)	DKYGENKY^* (DMAC:MMSAUTH2)			X
PINPROT (ENCRYPT, REFORMAT, NOFLDFMT, ISO-4)	PINPROT (DECRYPT, EPINVER, NOFLDFMT, ISO-4)	F
PINPROT (DECRYPT EPINVER NOFLDFMT ISO-4)	PINPROT (ENCRYPT REFORMAT NOFLDFMT ISO-4)	F
Note: An `'X'` indicates a permissible key type and key usage combination for a given key form. An `'E'` indicates that a special (Extended) command is required as those keys require special handling. An `'F'` indicates that a special OPOP command is required as those keys require special handling. See Required commands for the commands required to enable these permissible combinations. The key types marked with an asterisk (*) must be requested through the specification of a proper key usage in a key token and the use of the TOKEN keyword. These key types are not recognized by the verb as key type keywords. A pair of DKYGENKY keys can be used to diversify a pair of keys with different key types and key usage attributes. The combination of key types and key usage attributes that can be diversified must meet the requirements of using the Key Generate2 verb to generate those same keys. A DKYGENKY key with D-ALL usage can only be paired with a DKYGENKY key with D-ALL usage. Refer to Table 4.

For AES keys, the AES KEK must be at least as strong as the key being generated to be considered sufficient strength.

For HMAC keys, the AES KEK must be sufficient strength as described in the following table:

Table 3. AES KEK strength required for generating an HMAC key under an AES KEK
Key-usage field 2 in the HMAC key contains	Minimum strength of AES KEK to adequately protect the HMAC key
SHA-256, SHA-384, or SHA-512	256 bits
SHA-224	192 bits
SHA-1	128 bits

Table 4 describes the key generation processing for DK keys (DK enabled AES key types MAC, PINCALC, PINPROT, and PINPRW). They have special rules related to which keys can exist on which system.

Table 4. CSNBKGN2 access control requirements for DK enabled keys
generated_key_identifier_1				generated_key_identifier_2				key_form
key_type_1	KUF 1 high-order byte	KUF 2 high-order byte	KUF 3 high-order byte	key_type_2	KUF 1 high-order byte	KUF 2 high-order byte	KUF 3 high-order byte	OPOP OPIM IMIM	OPEX IMEX	EXEX	OP EX IM
When using Key Generate2 to generate one or two DK keys that have DKPINOP, DKPINOPP, DKPINAD1, or DKPINAD2 on in key-usage field 3 of at least one skeleton key-token, the following table rows show the valid key usage for each DK key and the required access control command required for each key_form keyword.
PINPROT	ENCRYPT	Any usage	DKPINOP	PINPROT	DECRYPT	Any usage	DKPINOP	%	x
PINPROT	DECRYPT	Any usage	DKPINOP	PINPROT	ENCRYPT	Any usage	DKPINOP	%
PINPROT	ENCRYPT	Any usage	DKPINOP	CIPHER	DECRYPT	Any usage	No DK user	%	*
CIPHER	DECRYPT	Any usage	No DK user	PINPROT	ENCRYPT	Any usage	DKPINOP	%
PINPROT	ENCRYPT	Any usage	DKPINAD1	PINPROT	DECRYPT	Any usage	DKPINAD1	%	&
PINPROT	DECRYPT	Any usage	DKPINAD1	PINPROT	ENCRYPT	Any usage	DKPINAD1	%
MAC	GENONLY	Any usage	DKPINOP	MAC	VERIFY	Any usage	DKPINOP	%	x
MAC	VERIFY	Any usage	DKPINOP	MAC	GENONLY	Any usage	DKPINOP	%
MAC	GENONLY	Any usage	DKPINAD1	MAC	VERIFY	Any usage	DKPINAD1	~	~
MAC	VERIFY	Any usage	DKPINAD1	MAC	GENONLY	Any usage	DKPINAD1	~
MAC	GENONLY	Any usage	DKPINAD2	MAC	VERIFY	Any usage	DKPINAD2	%	$
MAC	VERIFY	Any usage	DKPINAD2	MAC	GENONLY	Any usage	DKPINAD2	%
PINPRW	GENONLY	Any usage	DKPINOP	PINPRW	VERIFY	Any usage	DKPINOP	x	x
PINPRW	VERIFY	Any usage	DKPINOP	PINPRW	GENONLY	Any usage	DKPINOP	x
PINCALC	GENONLY	Any usage	DKPINOP								#
The symbols in the key_form columns are as follows: % Generate DK Set Locally (OPOP, OPIM, IMIM), offset X'02BB' * Generate DK PIN Print Pair, offset X'02BC' & Generate DK PIN Admin 1 PINPROT Pair, offset X'02BD' ~ Generate DK PIN Admin 1 MAC Pair, offset X'02BE' $ Generate DK PIN Admin 2 MAC Pair, offset X'02BF' # Generate2 Key, offset X'00EA' x Generate2 Key Set, offset X'00EB' none Error 8/155

The DKPINAD1 MAC keys are special. They are the only keys listed as needing no special permission to be generated as OPOP, OPIM, or IMIM pairs. Those keys are needed for generating and verifying the value EPB_M_FUS in some DK functions. Those functions run on the same system (Generating Unit) and are the only functions that use the DKPINAD1 keys. Since the entire key pair is required on the same system, special permission should not be needed in order to generate a complete key pair on the same system.

DKPINAD2 MAC key pairs can be generated with GENONLY and VERIFY key usage in key form OPOP, OPIM, and IMIM (those formats that render possible the existence of the entire key pair on one system) only with an appropriate access control point (%) set.

Note: The HMAC key bit length must be equal or greater than half of the size of the hash function output. For example, SHA-256 output requires a 128-bit HMAC key.