Unique Key Derive (CSNBUKD and CSNEUKD)

CALL CSNBUKD(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             base_derivation_key_identifier_length,
             base_derivation_key_identifier,
             derivation_data_length,
             derivation_data,
             generated_key_identifier1_length,
             generated_key_identifier1,
             generated_key_identifier2_length,
             generated_key_identifier2,
             generated_key_identifier3_length,
             generated_key_identifier3,
             transport_key_identifier_length,
             transport_key_identifier,
             reserved2_length,
             reserved2,
             reserved3_length,
             reserved3,               
             reserved4_length,
             reserved4,
             reserved5_length,
             reserved5,
             reserved6_length,
             reserved6 )      

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
Input	Integer

The number of keywords you supplied in the rule_array parameter. Values are 1 through 7.

rule_array

Direction	Type
Input	String

The rule_array parameter is an array of keywords. The keywords must be 8 bytes of contiguous storage with the keyword left-justified in its 8-byte location and padded on the right with blanks. The rule_array keywords are:

Table 1. Keywords for Unique Key Derive

Keyword	Meaning
DUKPT algorithm (One, optional).
DES	Specifies to derive keys using DES DUKPT algorithm as described in X9.24 2007 Part 1. This is the default.
A-DUKPT	Specifies to derive keys using AES DUKPT algorithm as described in X9.24 2017 Part 3.
Output key selection for generated_key_identifier1 (One, optional). Specify at least one output key selection keyword for DES. Not valid with the K3IPEK, PIN-DATA, or A-DUKPT keywords.
K1DATA	The returned key type for this keyword is a DATA ENCRYPTION key. Output value generated_key_identifier1 will be created and will be a data encryption key. The skeleton token provided in that parameter on input must be one of the permitted 'Data encryption key' types for this callable service. For valid values, see Table 3.
Data encryption direction or initiation (One, optional, with K1DATA. Otherwise, not allowed).
REQ-ENC	Specifies to derive a data encryption key to be used to send or process a request. See 'Data Encryption, request or both ways' under the DUKPT key usage description column in Table 4.
RSP-ENC	Specifies to derive a data encryption key to be used to send or process a response. See 'Data Encryption, response' under the DUKPT key usage description column in Table 4.
Output key selection for generated_key_identifier2 (One, optional). Specify at least one output key selection keyword for DES. Not valid with the K3IPEK, PIN-DATA, or A-DUKPT keywords.
K2MAC	The returned key type for this keyword is a MAC key. Output value generated_key_identifier2 will be created and will be a MAC key. The skeleton token provided in that parameter on input must be one of the permitted MAC key types for this callable service. For valid values, see Table 3.
MAC direction or initiation (one, optional, with K2MAC. Otherwise, not allowed).
REQ-MAC	Specifies to derive a MAC key to be used to send or process a request. See 'Message authentication, request or both ways' under the DUKPT key usage description column in Table 4.
RSP-MAC	Specifies to derive a MAC key to be used to send or process a response. See 'Message authentication, response' under the DUKPT key usage description column in Table 4.
Output key selection for generated_key_identifier3 (One, optional). Specify at least one output key selection keyword for DES. Not valid with the K3IPEK or PIN-DATA. No other output key selection keywords are allowed. For A-DUKPT, only K3IPEK is allowed.
K3IPEK	The returned key for this keyword is the IPEK. When used in conjugation with the DES keyword, it specifies to use the generated_key_identifier3 parameter to identify on input a null key token. On output, the initial PIN encryption key (IPEK) is returned TDES-wrapped using the key identified by the transport_key_identifier parameter. The IPEK is created by taking the base derivation key and encrypting the 59-bit initial key serial number contained within the derivation data. The key is returned either in an external CCA fixed-length DES key-token or an external TR-31 key block, depending on which token output type keyword is specified. When used in conjugation with the A-DUKPT keyword, it specifies to use the generated_key_identifier3 parameter to identify on input a null key token. On output, the initial PIN encryption key (IPEK) is returned AES-wrapped using the key identified by the transport_key_identifier parameter. The IPEK is created by taking the information from derivation data. The key is returned in an external TR-31 key block. This keyword may not be combined with any other output key selection keyword.
K3PIN	The returned key type for this keyword is a PIN key. Output value generated_key_identifier3 will be created and will be a PIN key. The skeleton token provided in that parameter on input must be one of the permitted PIN key types for this callable service. For valid values, see Table 3. When the A-DUKPT keyword is specified, this keyword is not allowed.
PIN-DATA	The returned key type for this keyword is a PIN key, which is returned in a DATA key token. Output value generated_key_identifier3 will be created and will be a DATA key. The skeleton token provided in that parameter on input must be one of the permitted 'PIN key with rule keyword PIN-DATA' key types for this callable service. For valid values, see Table 3. To use this option: Control Vector bit 61 (Not-CCA) will be set to a one. Access Control Point Unique Key Derive - Allow PIN-DATA processing must be enabled. When the A-DUKPT keyword is specified, this keyword is not allowed.
Token output type (One, optional).
TDES-TOK	Specifies that the output IPEK should be wrapped by the TDES transport key and returned in an external TDES token. Valid with the K3IPEK keyword only. When the A-DUKPT keyword is specified, this keyword is not allowed.
TR31-TOK	Specifies that the output IPEK should be wrapped by the TDES transport key if DES is specified or the AES transport key if A-DUKPT is specified and returned in a TR-31 key block. Valid with the K3IPEK keyword only.
Key wrapping method (One, optional). These keywords are only valid when CCA DES keys are derived.
USECONFG	Specifies to wrap the key using the configuration setting for the default wrapping method. This is the default.
WRAP-ENH	Specifies to wrap the key using the enhanced wrapping method with SHA-1.
WRAPENH2	Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only with triple-length keys. This is the default for triple-length keys.
WRAPENH3	Specifies to wrap the key using the enhanced wrapping method and SHA-256 and CMAC authentication code.
WRAP-ECB	Specifies to wrap the key using the original wrapping method.

base_derivation_key_identifier_length

Direction	Type
Input	Integer

The length of the base_derivation_key parameter.

If the base_derivation_key_identifier field contains a label, the length must be 64 bytes.

Otherwise, the value must be between the actual length of the key token and 9992.

base_derivation_key_identifier

Direction	Type
Input/Output	String

The identifier of the base derivation key used to derive operational keys using the DUKPT algorithms defined in ANSI X9.24 2007 Part 1 and 3. The key identifier is a variable-length operational key token or key block or the label of an operational token or block in key storage.

For CCA keys:

• For DES, the identifier is a 64-byte key token of a DES key-derivation key of key type KEYGENKY with the UKPT attribute (bit 18) enabled in the control vector.
• For A-DUKPT, the identifier is a variable-length key token of an AES key-derivation key of key type DKYGENKY with the A-DUKPT key usage attribute enabled.

For TR-31 key, the identifier is a variable-length key block of a key-derivation key: key usage B0 and mode of use X. The algorithm is T for DES and A for A-DUKPT.

If the token or block supplied was encrypted under the old master key, the token or block will be returned encrypted under the current master key.

derivation_data_length

Direction	Type
Input	Integer

The length of the derivation_data parameter. For DES, this value must be 10. For A-DUKPT, this value must be 20.

derivation_data

Direction	Type
Input	String

For DES, the derivation data is an 80-bit (10-byte) string that contains the Current Key Serial Number (CKSN) of the device concatenated with the 21-bit value of the current Encryption Counter which the device increments for each new transaction. For A-DUKPT, the derivation is a 20-byte string as defined in Table 1. For allowed derived working keys sizes, see Table 1.

generated_key_identifier1_length

Direction	Type
Input/Output	Integer

The length of the generated_key_identifier1 parameter. The maximum length is 9992.

For DES, when K1DATA is specified:

• This value must be 64 when a fixed-length DES token or skeleton is provided.
• This value may be up to 9992 when a TR-31 key block or skeleton is provided.

For DES, when K1DATA is not specified, this value must be 0.

For A-DUKPT, on input, the length of the buffer for the generated_key_identifier1 parameter in bytes. The maximum value is 9992. On output, the parameter will hold the actual length of the generated_key_identifier1. When A-DUKPT is specified with K3IPEK, this value must be 0.

generated_key_identifier1

Direction	Type
Input/Output	String

The buffer to receive the variable-length generated key.

For DES algorithm (DES keyword):

On input:

• For CCA keys, this must be a DES data-encryption 64-byte key token or a skeleton token of a DES data-encryption key, with one of the data-encryption control vectors as shown in Table 3. To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.
• For TR-31 keys, this must be a skeleton key block with key usage D0, algorithm T, and mode of use B, D, or E as indicated by the Data encryption direction keyword. To generate a compliant-tagged key block, the IBM optional block "10" with the Compliance Tag attribute enabled must be included with the skeleton key block.

On output:

generated_key_identifier1 will contain the data encryption token or block with the derived data encryption key.

For AES algorithm (A-DUKPT keyword):

On input:

• For CCA keys, this must be a variable-length skeleton token for a DES, AES, or HMAC key. To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.
• For TR-31 keys, this must be a skeleton key block with key usage, algorithm, and mode of use matching the key defined in the derivation data structure.
  • When the key usage indicator in the derivation data is X'8000', only key usages B0 and B3 are allowed.
  • When the key usage indicator in the derivation data is X'8001', only key usage B1 is allowed.
  • To generate a compliant-tagged key block, the IBM optional block "10" with the Compliance Tag attribute enabled must be included with the skeleton key block.

On output:

generated_key_identifier1 will contain the key token as specified in the Derived Data structure. For the supported CCA key types for AES-DUKPT derived working keys, see Table 1.

generated_key_identifier2_length

Direction	Type
Input/Output	Integer

The length of the generated_key_identifier2 parameter. The maximum length is 9992.

When the K2MAC keyword is specified:

• This value must be 64 when a fixed-length DES token or skeleton is provided.
• This value may be up to 9992 when a TR-31 key block or skeleton is provided.

Otherwise, this value must be 0.

generated_key_identifier2

Direction	Type
Input/Output	String

The buffer to receive the variable-length generated key.

On input:

• For CCA keys, this must be a DES MAC 64-byte key token or a skeleton token of a DES MAC key, with one of the MAC control vectors as shown in Table 3. To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.
• For TR-31 keys, this must be a skeleton key block with key usage M0, M1, or M3, algorithm T, and mode of use C, G, or V as indicated by the MAC direction keyword. To generate a compliant-tagged key block, the IBM optional block "10" with the Compliance Tag attribute enabled must be included with the skeleton key block.

On output, generated_key_identifier2 will contain the MAC token or block with the derived MAC key.

generated_key_identifier3_length

Direction	Type
Input/Output	Integer

The length of the generated_key_identifier3 parameter. The maximum length is 9992.

When the rule array keywords K3IPEK or K3PIN are specified, the length must be at least 64 bytes.

When PINDATA is specified, the length must be 64.

Otherwise, the length must be 0.

generated_key_identifier3

Direction	Type
Input/Output	String

The input and output values for this parameter depends on the keyword specified in the rule_array parameter. The rule_array keyword for the generated_key_identifier3 parameter can be PIN-DATA, K3PIN, or K3IPEK.

• When Rule Array Keyword is PIN-DATA, input must be a Data key token or skeleton token of a Data key with one of the 'PIN key with rule keyword PIN-DATA' control vectors as shown in Table 3. On output, this parameter will contain the Data token with the derived PIN key.
• When Rule Array Keyword is K3PIN, input must be either:
  • A DES PIN key token or a skeleton token of a DES PIN key, with one of the PIN control vectors as shown in Table 3. On output, this parameter will contain the PIN token with the derived PIN key.
  • A DES TR-31 key block or skeleton with key usage P0, algorithm T for DES, and mode of use D or E.
• When Rule Array Keyword is K3IPEK, input must be a null key token. Depending on the token output type keyword specified, the IPEK is either returned in an external CCA fixed-length DES key-token (TDES-TOK) or in an external non-CCA TR-31 key block (TR31-TOK). When TDES-TOK is specified, on output, the IPEK is returned in an external DES key-token wrapped by the TDES transport key. The control vector in the returned double-length DATA key-token is valued to binary zeros. When TR31-TOK is specified with the DES keyword, on output, the IPEK is returned in an external TR-31 key block wrapped by the TDES transport key. When TR-31-TOK is specified with the A-DUKPT keyword, on output, the IPEK is returned in an external TR-31 key block wrapped by the AES transport key. The key usage indicator in the AES-DUKPT derivation data must be set to X'8001' (Key Derivation Initial Key).
• To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.

  Table 2. Contents of the TR-31 block header of the generated TR-31 key block and their meaning

  TR-31 key block header field	Value in ASCII	Meaning
  Key block version ID	B	Key block version and wrapping method. 'D' must be used for an AES IPEK.
  	D
  Key usage	B1	IPEK key
  Algorithm	T	TDES
  	A	AES
  Key mode of use	x	Key derivation key
  Key version number	00	Unused
  Key exportability (value depends on key-wrapping method, either specified in rule array or, if no keyword, by default configuration setting)	S if key-wrapping method is WRAP-ECB.	Sensitive: key exportable under any KEK
  	E if key-wrapping method is any enhanced wrapping method.	Extra sensitive: key exportable under KEK meeting ANSI X9.24 Part 1 or Part 2 (no ECB mode encrypted KEKs allowed)
  Number of optional blocks	00	No optional blocks

transport_key_identifier_length

Direction	Type
Input	Integer

The length of the transport_key_identifier parameter. If the transport key identifier is not used, the length must be 0.

When DES is specified with TDES-TOK or TR31-TOK, the length must be 64.

When A-DUKPT and TR31-TOK are specified, the length must the length of the AES transport key specified in transport_key_identifier. The maximum value is 725.

transport_key_identifier

Direction	Type
Input/Output	String

If the K3IPEK keyword is specified, the transport_key_identifier contains the label or key token for the key encrypting key to be used to wrap the IPEK.

For DES, the transport key must be a DES EXPORTER KEK.

For A-DUKPT, the transport key must be an AES EXPORTER KEK with key usage EXPTT31D and WR-AES. Otherwise, this field is ignored.

reserved2_length

Direction	Type
Input	Integer

This parameter must be zero.

reserved2

Direction	Type
Ignored	String

This parameter is ignored.

reserved3_length

Direction	Type
Input	Integer

This parameter must be zero.

reserved3

Direction	Type
Ignored	String

This parameter is ignored.

reserved4_length

Direction	Type
Input	Integer

This parameter must be zero.

reserved4

Direction	Type
Ignored	String

This parameter is ignored.

reserved5_length

Direction	Type
Input	Integer

This parameter must be zero.

reserved5

Direction	Type
Ignored	String

This parameter is ignored.

reserved6_length

Direction	Type
Input	Integer

This parameter must be zero.

reserved6

Direction	Type
Ignored	String

This parameter is ignored.

The following table shows the valid skeleton tokens depending on the key type to be derived.

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

The DUKPT key derivation process that is defined in the ANSI X9.24 standard describes the use of the derived keys in terms of a terminal, which sends requests, and a host, which processes those requests and sends responses.

Beginning with the July 2019 Licensed Internal Code (LIC), two direction or initiation rule-array keyword groups are added, one group for deriving MAC keys, and the other group for deriving data encryption keys. The use of these keywords is to specify the purpose of the key (MAC or data encryption) and whether the key is to be used to send or receive a request or to send or receive a response.

If ICSF is configured to audit the lifecycle of tokens [AUDITKEYLIFECKDS(TOKEN(YES),...) is specified], an additional request is made to the Crypto Express coprocessor to generate the key fingerprint to be used for auditing the generated key.

The Unique Key Derive access control point controls the function of this service. Specifying a 'Key wrapping method' in the rule array requires the Unique Key Derive - Override default wrapping access control point to be enabled in the active role.

Specifying the PIN-DATA rule array keyword requires the Unique Key Derive - Allow PIN-DATA access control point to be enabled in the active role.

Specifying the K3IPEK rule array keyword requires the Unique Key Derive - K3IPEK access control point to be enabled in the active role.

To disallow the import of a key wrapped with a weaker transport key, the Symmetric Key Import2 - disallow weak import access control must be enabled.

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.