Diversify Directed Key (CSNBDDK and CSNEDDK)

The Diversify Directed Key callable service is used to selectively generate and derive a pair of associated keys in connection with a directed key diversification key scheme. The objective of the concept is to generate and derive a key pair with different key usages from one key diversification key (KDK). Key direction comes into play in that one of the keys is generated and is used for one direction (for example, encryption, MAC generate, and so forth), while the other key is derived and will have usage associated with a different direction (for example, decryption, MAC verification, and so forth). This callable service provides an option to perform the generate or derive operation.

A structure called a key type vector, which is always used as the initialization vector for the diversification process, is passed in as input and is used to determine what and how the key is produced by this callable service.

The key generated by this callable service is used as a session key. The intention in this context is that the keys of a generated and derived key pair are one-time keys. The key management fields of the output key will indicate that the key cannot be exported.

The callable service name for AMODE(64) invocation is CSNEDDK.

Format

CALL CSNBDDK(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             kdk_key_identifier_length,
             kdk_key_identifier,
             key_type_vector_length,
             key_type_vector,
             additional_derivation_data_length,
             additional_derivation_data,
             random_data_length,
             random_data,
             output_key_identifier_length,
             output_key_identifier)

Parameters

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return/reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that indicate specific processing problems. ICSF and cryptographic coprocessor return/reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Output	Integer

The number of keywords you supplied in the rule_array parameter. The value must be 2.

rule_array

Direction	Type
Input	Character

The rule_array contains keywords that provide control information to the callable service. The keywords must be in contiguous storage with each of the keywords left-justified in its own 8-byte location and padded on the right with blanks.

Table 1. Keywords for Diversify Directed Key
Keyword	Meaning
*Diversification Process (One required)*
KDFFM	Specifies to use the Key Derivation Function (KDF) in Feedback Mode (NIST SP 800-108) to generate key. The key type vector is used as the IV for this process.
*Function (one required)*
DERIVE	Specifies to derive the passive diversified key of a pair of directed keys.
GENERATE	Specifies to generate the active diversified key of a pair of directed keys.

kdk_key_identifier_length

Direction	Type
Input	Integer

Specifies the length in bytes of the kdk_key_identifier parameter. If the kdk_key_identifier contains a label, the value must be 64. Otherwise, the value must be between the actual length of the token and 725.

kdk_key_identifier

Direction	Type
Input/Output	String

The identifier of the key diversification key used to derive keys. The key identifier is an operational token or the key label of an operational token in key storage.

The key algorithm of this key must be AES and the key type must be KDKGENKY. The key usage fields indicate the type of key to diversify and if the key is to be derived for entity A or entity B.

Note: When the GENERATE function is specified and the generating key has usage of KDKTYPEA, the associated DERIVE function must have usage of KDKTYPEB. Likewise, when the GENERATE function is specified and this key has usage of KDKTYPEB, the associated DERIVE function must have usage of KDKTYPEA.

If the token supplied was encrypted under the old master key, the token is returned encrypted under the current master key.

key_type_vector_length

Direction	Type
Input	Integer

Specifies the length in bytes of the key_type_vector parameter. The value must be 16.

key_type_vector

Direction	Type
Input	String

The 16-byte key_type_vector specifies the rules for the calculation of the key value to be generated or derived and contains information needed to restrict the usage of the key to be generated or derived. The format of the structure is as follows:

Offset	Length	Description
0	2	Version number X'0000'.
2	2	Type of key to be derived or generated. Value Meaning X'0000' MAC. X'0001' Data encryption (cipher). X'0003' PIN encryption. X'0004' Key wrapping. All other values are reserved and undefined.
4	2	Key algorithm. Value Meaning X'0002' AES. All other values are reserved and undefined.
6	2	Length of the key to be derived or generated in bits. Value Meaning X'0800' 2048 (for example, AES-256).
8	2	Key usage restriction 1 of the key to be derived or generated, based on the key type field (value at offset 2): For MAC key type (Value at offset 2 = X'0000'). Value Meaning X'0001' Key can derive or generate a CMAC mode key only. All other values are reserved and undefined. For data encryption (cipher) key type (Value at offset 2 = X'0001'). Value Meaning X'0002' Key can derive or generate a CBC mode key only. All other values are reserved and undefined. For PIN encryption key type (Value at offset 2 = X'0003'). Value Meaning X'0000' or X'0002' Key can derive or generate an ISO-4 format key only. See the note for KTVs for this key type. All other values are reserved and undefined. For Key wrap key type (Value at offset 2 = X'0004'). Value Meaning X'0001' Key can derive or generate a VARDRV-D key only. All other values are reserved and undefined. For all other key types not listed above: Value Meaning X'0000' No key usage restriction 1. All other values are reserved and undefined.
10	2	Key usage restriction 2 of the key to be derived or generated, depending on the key type (offset 2) and key usage restriction 1 (offset 8): MAC key type and HMAC mode (Value at offset 2 = X'0000' and offset 8 = X'0001'). Value Meaning X'0002' SHA-256. X'0003' SHA-384. X'0004' SHA-512. All other values are reserved and undefined. Key-wrap key type and VARDRV-D mode (Value at offset 2 = X'0004' and offset 8 = X'0001'). Value Meaning X'0100' Maximum key length of the protected keys is 2048 bits. All other values are reserved and undefined. All other values at offset 2 and offset 8. Value Meaning X'0000' Undefined. All other values are reserved and undefined. For all other key types and key usage restriction 1 combinations not listed above: Value Meaning X'0000' No key usage restriction 2. All other values are reserved and undefined.
12	3	Reserved, must be binary zero.
15	1	Key direction variant indicator Diversifies the key to be derived or generated depending on the permitted use of direction. The HSM has to restrict the usage of the key depending on this value and the type of entity (A or B) which is an additional parameter in the process of deriving or generating the key. This value affects a key usage attribute of the key to be derived or generated. Value Meaning X'00' A ↔ B (undirected use of key). X'01' A → B (A active, B passive use of key). X'10' A ← B or equivalent (A passive, B active use of key). X'FF' System is to determine key direction from entity usage of the KDKGENKY and rule array keywords. KDK-A + GENERATE rule array keyword Direction set to X'01' (A → B). KDK-B + GENERATE rule array keyword Direction set to X'10' (A ← B). KDK-A + DERIVE rule array keyword Direction set to X'10' (A ← B). KDK-B + DERIVE rule array keyword Direction set to X'01' (A → B). All other values are reserved and undefined.

The following tables define the valid KTV supported.

For each of the four key types defined at KTV offset 2 (MAC, data encryption, PIN encryption, and key wrapping), there are two KTVs defined, with the only difference between them being the key direction variant indicator (KTV offset 15). Either entity Type A is active and Type B is passive (A→B), or Type B is active and Type A is passive (A←B). See Table 2 for additional information.

Table 2. Summary of KTV tables
A→B or A←B	MAC generate/verify	Data encrypt/decrypt	PIN encrypt/decrypt	Key wrap/unwrap
A→B (A active)	KTVM1 Table 3	KTVC1 Table 5	KTVP1 Table 9	KTVW1 Table 11
A←B (B active)	KTVM2 Table 4	KTVC2 Table 6	KTVP2 Table 10	KTVW2 Table 12

Table 3. KTV for MAC generate/verify, Type A active and Type B passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	MAC	AES	AES-256	CMAC	'else'	-	A→B
00	00 00	00 02	01 00	00 01	00 00	00 00 00	01
KTVM1 = X'00 00 00 00 00 02 01 00 00 01 00 00 00 00 00 01'

Table 4. KTV for MAC generate/verify, Type B active and Type A passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	MAC	AES	AES-256	CMAC	'else'	-	A←B
00	00 00	00 02	01 00	00 01	00 00	00 00 00	10
KTVM2 = X'00 00 00 00 00 02 01 00 00 01 00 00 00 00 00 10'

Table 5. KTV for data encryption (cipher), Type A active and Type B passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	Cipher	AES	AES-256	CBC	'else'	-	A→B
00	00 01	00 02	01 00	00 02	00 00	00 00 00	01
KTVC1 = X'00 00 00 01 00 02 01 00 00 02 00 00 00 00 00 01'

Table 6. KTV for data encryption (cipher), Type B active and Type A passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	Cipher	AES	AES-256	CBC	'else'	-	A←B
00	00 01	00 02	01 00	00 02	00 00	00 00 00	10
KTVC2 = X'00 00 00 01 00 02 01 00 00 02 00 00 00 00 00 10'

For PIN encryption key type, the key usage indicator 1 (offset 8) for ISO-4 format can have the value of '0000' or '0002' for a pair of KTVs. The caller is not allowed to mix pairs of KTVs because the KTV is used as the IV in the key creating process. This is the responsibility of the caller of the service.

KTV pair for PIN encryption key type with key usage indicator 1 with '0000' value.

Table 7. KTV for PIN encryption, Type A active and Type B passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	PIN-Enc	AES	AES-256	ISO-4	'else'	-	A→B
00	00 03	00 02	01 00	00 00	00 00	00 00 00	01
KTVP1 = X'00 00 00 03 00 02 01 00 00 00 00 00 00 00 00 01'

Table 8. KTV for PIN encryption, Type B active and Type A passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	PIN-Enc	AES	AES-256	ISO-4	'else'	-	A←B
00	00 03	00 02	01 00	00 00	00 00	00 00 00	10
KTVP2 = X'00 00 00 03 00 02 01 00 00 02 00 00 00 00 00 10'

KTV pair for PIN encryption key type with key usage indicator 1 with '0002' value.

Table 9. KTV for PIN encryption, Type A active and Type B passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	PIN-Enc	AES	AES-256	ISO-4	'else'	-	A→B
00	00 03	00 02	01 00	00 02	00 00	00 00 00	01
KTVP1 = X'00 00 00 03 00 02 01 00 00 02 00 00 00 00 00 01'

Table 10. KTV for PIN encryption, Type B active and Type A passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	PIN-Enc	AES	AES-256	ISO-4	'else'	-	A←B
00	00 03	00 02	01 00	00 02	00 00	00 00 00	10
KTVP2 = X'00 00 00 03 00 02 01 00 00 02 00 00 00 00 00 10'

For Table 11, entity Type A must use an AES EXPORTER key with usage of EXPTT31D, while entity Type B must use an IMPORTER key with usage of IMPTT31D.

Key wrapping with key block protection (ISO TC 68/SC 2 Nxxxx, 2016-08-17, ISO DIS 20038):

Table 11. KTV for key wrapping, Type A active and Type B passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	Key wrap	AES	AES-256	VARDRV-D	Maximum bit length of the protected keys	-	A→B
00	00 04	00 02	01 00	00 01	01 00	00 00 00	01
KTVW1 = X'00 00 00 04 00 02 01 00 00 01 01 00 00 00 00 01'

For Table 12, entity Type B must use an AES EXPORTER key with usage of EXPTT31D, while entity Type A must use an IMPORTER key with usage of IMPTT31D.

Table 12. KTV for key wrapping, Type B active and Type A passive
Version (offset 0)	Key type indicator (offset 2)	Algorithm indicator (offset 4)	Key length (offset 6)	Key usage indicator 1 (offset 8)	Key usage restriction 2 (offset 10)	RFU (offset 12)	Key direction variant indicator (offset 15)
0	Key wrap	AES	AES-256	VARDRV-D	Maximum bit length of the protected keys	-	A←B
00	00 04	00 02	01 00	00 01	01 00	00 00 00	10
KTVW2 = X'00 00 00 04 00 02 01 00 00 01 01 00 00 00 00 10'

additional_derivation_data_length

Direction	Type
Input	Integer

Specifies the length in bytes of the additional_derivation_data parameter. The value must be between 0 and 2032 inclusive for CCA release 6.7, 7.4, and later. Otherwise, the value must be 0 and 24 inclusive.

The sum of the additional_derivation_data_length and the random_data_length cannot exceed 2048.

additional_derivation_data

Direction	Type
Input	String

Data to be used in the key generation or key derivation process.

The additional derivation data concatenated with the random data cannot exceed 2048 for CCA releases 6.7, 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.

random_data_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the random_data parameter. The value must be between 16 and 40 inclusive. The sum of the additional_derivation_data_length and the random_data_length cannot exceed 2048 for CCA releases 6.7, 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.

When keyword GENERATE is specified in the rule array, this is an input and an output parameter. On input, this value specifies the number of bytes of data to use as the random data portion of the diversification data used in diversifying the first key of a key pair. On output, the returned value indicates the number of bytes of data actually returned in the random_data variable.

When keyword DERIVE is specified in the rule array, this is an input only parameter. On input, this value specifies the number of bytes of data to use as the random data portion of the diversification data used in diversifying the second key of a key pair. To produce the desired results, this value must be the same length returned by a previous associated GENERATE function call.

random_data

Direction	Type
Input/Output	String

The random data used in the diversification process.

When the GENERATE function is specified, on input, this variable is ignored, and on output, this variable contains the random data created and used to diversify the first output key of a key pair.

When the DERIVE function is specified, on input, this variable must contain the random data previously created during a previous GENERATE function and is used to diversify the second output key of a key pair.

Note: For a given pair of output keys, the DERIVE function must provide the same random data and additional_derivation_data value as the GENERATE function used.

The additional derivation data concatenated with the random data cannot exceed 2048 for CCA releases 6.7, 7.4, and later. Otherwise, the random data cannot exceed 40 bytes.

output_key_identifier_length

Direction	Type
Input/Output	Integer

Specifies the length in bytes of the buffer for the output_key_identifier parameter. On input, the value is the size of the buffer. The maximum length is 725. On output, the value is the length of the key token returned in the output_key_identifier parameter.

output_key_identifier

Direction	Type
Input/Output	String

The buffer to receive the generated key. The key attributes are identified by the key_type_vector parameter.

On input, the buffer must contain a variable-length symmetric null key token (see Table 1), left justified in the buffer. The rest of the buffer is copied, but not checked.

When the kdk_key_identifier is compliant-tagged, a compliant-tagged key token will be created.

Usage notes

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS.

Access control points

The Diversify Directed Key access control point in the domain role controls the function of this service.

The access controls for rule array keywords are listed in the table:

Diversification process rule-array keyword	Function rule-array keyword	Access control
KDFFM	DERIVE	Diversify Directed Key - allow KDFFM DERIVE
KDFFM	GENERATE	Diversify Directed Key - allow KDFFM GENERATE

Required hardware

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service. The CCA releases used in the table are described in CCA release levels.

Table 13. Diversify Directed Key required hardware
Server	Required cryptographic hardware	Restrictions
IBM z14 IBM z14 ZR1	Crypto Express5 CCA Coprocessor	This service requires the July 2019 or later licensed internal code (LIC). Compliant-tagged key tokens are not supported. The additional_derivation_data_length must not exceed 24.
IBM z14 IBM z14 ZR1	Crypto Express6 CCA Coprocessor	This service requires the December 2018 or later licensed internal code (LIC). Compliant-tagged key tokens require a CEX6C with the July 2019 or later licensed internal code (LIC). The additional_derivation_data_length parameter support requires the CCA release 6.7 or later licensed internal code (LIC).
IBM z15 IBM z15 T02	Crypto Express5 CCA Coprocessor	Compliant-tagged key tokens are not supported. The additional_derivation_data_length must not exceed 24.
	Crypto Express6 CCA Coprocessor	The additional_derivation_data_length parameter support requires the CCA release 6.7 or later licensed internal code (LIC).
	Crypto Express7 CCA Coprocessor	The additional_derivation_data_length parameter support requires the CCA release 7.4 or later licensed internal code (LIC).
IBM z16 IBM z16 A02	Crypto Express6 CCA Coprocessor Crypto Express7 CCA Coprocessor Crypto Express8 CCA Coprocessor
IBM z17	Crypto Express7 CCA Coprocessor Crypto Express8 CCA Coprocessor