Parameters
The parameter definitions for CSNBUKD.
For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.
- rule_array_count
-
A pointer to an integer variable containing the number of elements in the rule_array variable. Values are in the range 1 - 9.
Direction: Input Type: Integer - rule_array
-
An array of 8-byte keywords providing the processing control information to the verb. 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. The rule_array keywords are described in Table 1.
Direction: Input Type: String array Table 1. Keywords for Unique Key Derive control information Keyword Description DUKPT algorithm (One, optional.) DES Specifies to derive keys using the DES DUKPT algorithm as described in X9.24 2007 Part 1. This is the default. All input skeleton tokens must be DES tokens and all generated output tokens are DES tokens. A-DUKPT Specifies to derive keys using the AES DUKPT algorithm as described in X9.24 2017 Part 3. Token output type (One, required for K3IPEK, otherwise not allowed.) TDES-TOK Specifies that the output initial PIN encryption key (IPEK) should be wrapped by the TDES transport key and returned in an external TDES token. 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 wrapped by the AES transport key if ADUKPT is specified. In both cases, wrapped IPEK is returned in a TR-31 key block. Note: A TR-31 key block is written to the combined key storage if the parameter identifies a key label on input.Key wrapping method (One, optional. The default is USECONFG.) The access control point Unique Key Derive – Override Default Wrapping Method must be enabled to specify these keywords. These keywords are only valid when CCA DES keys are derived and therefore not allowed when deriving CCA AES keys, nor TR-31 keys.
USECONFG Specifies to wrap the key using the configuration setting for the default wrapping method. The default wrapping method configuration setting may be changed using the TKE. This keyword is ignored for AES keys. WRAP-ECB Specifies to wrap the key using the original wrapping method. WRAP-ENH Specifies to wrap the key using the enhanced wrapping method. WRAPENH2 Specifies to wrap the key using the enhanced wrapping method and SHA-256. Valid only for TRIPLE or TRIPLE-O. This method requires CV bit 56 = B’1’ (ENH-ONLY). This is the default for TRIPLE and TRIPLE-O. WRAPENH3 Specifies to wrap the key using the enhanced wrapping method with TDES-CMAC and the SHA-256 hashing algorithm. This keyword sets CV bit 56 = B’1’ (ENH-ONLY), which is required for the WRAPENH3 wrapping method. Output key selection for generated_key_identifier1 (one, optional). ). Specify at least one output key selection keyword. Not valid with the K3IPEK, PIN-DATA or the A-DUKPT keyword. K1DATA The returned key type for this keyword is a DATA ENCRYPTION key. This is the output key selection keyword for the generated_key_identifier1_length and generated_key_identifier1 parameters. The output value generated_key_identifier1 is created and is 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 1.When the A-DUKPT keyword is specified, this keyword is not allowed.
Output key selection for generated_key_identifier2 (one, optional). Specify at least one output key selection keyword. Not valid with the K3IPEK or the PIN-DATA keyword. When A-DUKPT keyword is used, this keyword is not allowed. K2MAC The returned key type for this keyword is a MAC key. This is the output key selection keyword for the generated_key_identifier2_length and generated_key_identifier2 parameters. The output value generated_key_identifier2 is created and is 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 1.When the A-DUKPT keyword is specified, this keyword is not allowed.
Output key selection for generated_key_identifier3 (one, optional). Specify at least one output key selection keyword. K3IPEK 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. The returned key for this keyword is the initial PIN encryption key (IPEK). This is an output key selection keyword for the generated_key_identifier3_length and generated_key_identifier3 parameters. The output value generated_key_identifier3 is created and is the initial PIN encryption key wrapped by the TDES transport key and returned in an external symmetric token or TR-31 key block as indicated by the token output type keyword. 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 1.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 the derivation data. The key is returned in an external non-CCA 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. This is an output key selection keyword for the generated_key_identifier3_length and generated_key_identifier3 parameters. The output value generated_key_identifier3 is created and is 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 1.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. This is an output key selection keyword for the generated_key_identifier3_length and generated_key_identifier3 parameters. The output value generated_key_identifier3 is created and is 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 1.To use this option:
- Control Vector bit 61 (Not-CCA) is set to a B'1'.
- 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.
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 Table 1. RSP-ENC Specifies to derive a data encryption key to be used to send or process a response. See Table 1. 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 Table 1. RSP-MAC Specifies to derive a MAC key to be used to send or process a response. See Table 1. Translation control (optional). This is valid only with key-wrapping method WRAP-ENH or with USECONFG when the default wrapping method is WRAP-ENH. This option has no effect on a key with a control vector valued to binary zeros. This keyword is only valid when DES keys are derived.
ENH-ONLY Specifies to restrict the key from being wrapped with the legacy method once it has been wrapped with the enhanced method. Set bit 56 of the control vector to B'1' (ENH-ONLY). - base_derivation_key_identifier_length
-
Length of the base_derivation_key_identifier parameter in bytes. When the DES keyword is specified and the base_derivation_key_identifier is a CCA DES token, then set this value to 64. When the A-DUKPT keyword is specified, and the base_derivation_key_identifier is a CCA AES token, then set this value to the length of the variable-length symmetric key-token, version X'05' AES DKYGENKY. When the base_derivation_key_identifier is a TR-31 token, then set this value to the length of the TR-31 token. The maximum value is 9992.
Direction: Input Type: Integer - base_derivation_key_identifier
-
Direction: Input/Output Type: String For DES, the base derivation key is the key from which the operational keys are derived using the DUKPT algorithms defined in ANSI X9.24 2007 Part 1. The base derivation key must be an internal key token or the label of an internal key token. A CCA DES token must contain a double-length KEYGENKY key with the UKPT bit (bit 18) set to 1 in the control vector. A TR-31 DES token must have the following attributes:- TR-31 key usage: B0
- Algorithm: T
- TR-31 mode of key use: X
For A-DUKPT, the base derivation key is the key from which the operational keys are derived using the DUKPT algorithms defined in ANSI X9.24 2017 Part 3. The base derivation key must be an internal key token or the label of an internal key token. A CCA AES token must contain an AES DKYGENKY version X'05' variable-length symmetric key token with the A-DUKPT bit set to 1 in the low-order byte of key usage field 1.
A TR-31 AES token must have the following attributes:
- TR-31 key usage: B0
- Algorithm: A
- TR-31 mode of key use: X
- derivation_data_length
-
Length of the derivation_data parameter in bytes. For DES, this value must be 10. For A-DUKPT, this value must be 20.
Direction: Input Type: Integer - derivation_data
-
When the DES keyword is specified, this parameter is a pointer to a string variable containing the 80-bit current-key serial number (CKSN) used as input to the DUKPT derivation process. The CKSN is a concatenation of the 59-bit initial key serial number (the value that was loaded when the PIN keypad was initialized) followed by the 21-bit current encryption counter. The device increments the encryption counter for each new transaction.
Direction: Input Type: String When the A-DUKPT keyword is specified,this parameter is a pointier to a string variable that contains the derivation data structure which is 20 bytes long. If the initial terminal key is being derived then Key Usage Indicator offset 2 must be set to 0x8001 = Key Derivation, Initial key (this value cannot be used for a working key). When deriving a working key specify valid working key derivation data values. See AES-DUKPT reference for details. Additionally, in this topic, you find information about allowed derived working keys sizes.
- generated_key_identifier1_length
-
Length of the generated_key_identifier1 parameter in bytes.
Direction: Input/Output Type: Integer When deriving a CCA token with DES and K1DATA specified, then set this value to 64. When deriving a TR-31 token with DES and K1DATA specified, then set this value to the size of the buffer used in the generated_key_identifier2 parameter, up to a maximum of 9992. When the DES keyword is specified and K1DATA is not specified, then set this value to 0. On output, this variable is updated with the length of the data returned in the generated_key_identifier1 variable.
When the A-DUKPT keyword is specified on output, the verb sets the variable to the length of the returned generated_key_identifier1 variable. On input this is the size of the buffer large enough to contain the generated CCA or TR-31 key token. The maximum value is 9992. When the A-DUKPT keyword is specified with the K3IPEK keyword, set this value to 0.
- generated_key_identifier1
-
Direction: Input/Output Type: String When DES and K1DAT are specified, the generated_key1_identifier parameter is a pointer to a string variable containing a fixed-length CCA DES key-token, a TR-31 DES key-token, or the key label of such a record in key storage. Otherwise, it should be a null pointer or identify a null key-token. To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.
When generating a CCA DES token and K1DATA is specified, on input, use this parameter to identify a complete or skeleton internal fixed-length CCA DES key-token for a double-length CIPHER, DECIPHER, or ENCIPHER key that can encipher or decipher data. Use the data encryption control vectors as shown in Table 1. On output, the key token identified is updated with the derived data confidentiality key.When generating a TR-31 DES token and K1DATA is specified, on input, use this parameter to identify a skeleton internal TR-31 DES key-token with the following attributes:
- TR-31 key usage: B0, B1, B3, D0, K0, K1, M0, M1, M3, or P0
- Algorithm: T
- TR-31 mode of key use: * (any as allowed according to the TR-31 key usage)
For A-DUKPT, on input, the generated_key1_identifier parameter is a pointer to a string variable containing a CCA or TR-31 skeleton token for a DES, AES, or HMAC key. To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied. On output, generated_key_identifier1 contains the key token as specified in the derived_data structure. See the supported CCA key types for AES-DUKPT derived working keys in AES-DUKPT reference.
When generating a TR-31 DES token the input skeleton token must have the following attributes:
- TR-31 key usage: B0, B1, B3, D0, K0, K1, M0, M1, M3, or P0
- Algorithm: T
- TR-31 mode of key use: * (any as allowed according to the TR-31 key usage)
When generating a TR-31 AES token the input skeleton token must have the following attributes:
- TR-31 key usage: B0, B1, B3, D0, K0, K1, M6, or P0
- Algorithm: A
- TR-31 mode of key use: * (any as allowed according to the TR-31 key usage)
In addition, when generating TR-31 tokens in general, the key usage indicator in the AES-DUKPT derivation data must be set to X'8001' if you want to use the B1 TR-31 key usage in your TR-31 token, and X’8000’ if you want to use the B0 or B3 TR-31 key usage.
When generating AES or DES keys specify a one of the supported CCA key types for AES-DUKPT derived working keys, see AES-DUKPT reference.
- generated_key_identifier2_length
-
Length of the generated_key_identifier2 parameter in bytes.
Direction: Input/Output Type: Integer When deriving a CCA token with DES and K2MAC specified, set the value to 64. When deriving a TR-31 token with DES and K2MAC specified, set this value to the size of the buffer used in the generated_key_identifier2 parameter, up to a maximum of 9992. Otherwise set this to 0, including when A-DUKPT is specified.
On output, this variable is updated with the length of data returned in the generated_key_identifier2 variable.
- generated_key_identifier2
-
Direction: Input/Output Type: String On input, when deriving a CCA token, this must be a DES MAC key token or a skeleton token of a DES MAC key, with one of the MAC control vectors as shown in Table 1.When deriving a TR-31 token, this must be a TR-31 skeleton token with the following attributes:
- TR-31 key usage: M0, M1, or M3
- Algorithm: T
- TR-31 mode of key use: C, G, or V (as indicated by direction keywords)
To derive a compliant-tagged key token, a compliant-tagged skeleton token must be supplied.
On output, generated_key_identifier2 contains the MAC token with the derived MAC key.
When the A-DUKPT keyword is specified the value must be null.
- generated_key_identifier3_length
-
Length of the generated_key_identifier3 parameter in bytes.
Direction: Input/Output Type: Integer When deriving a CCA DES token with the DES keyword: If rule-array keyword K3IPEK, K3PIN, or PIN-DATA is specified set the value to 64.
When deriving a TR-31 DES token with the DES and K3PIN keywords: Set this value to the size of the buffer used in the generated_key_identifier3 parameter, up to a maximum of 9992. Otherwise set it to 0. On output, the variable is updated with the length of the data returned in the generated_key _identifier3 variable.
For A-DUKPT and K3IPEK keywords: On input, this is the size of the buffer. On output, the verb sets the variable to the length of the returned generated_key_identifier3 variable. On input this is the size of the buffer large enough to contain the generated key token. The maximum value is 3500.
- generated_key_identifier3
-
The input and output values for this parameter depends on the keyword specified in the rule_array parameter. The rule_array keyword for the generation_key_identifier3 parameter can be either PIN-DATA, K3PIN, or K3IPEK.
Direction: Input/Output Type: String - When the rule array keyword is PIN-DATA, input must be a CCA data key token or CCA skeleton token of a data key with one of the control vectors for PIN key with rule keyword PIN-DATA as shown in Table 1. On output, this parameter contains the data token with the derived PIN key.
- When the rule array keyword is K3PIN, input can be a CCA DES PIN key token, a CCA skeleton token of a DES PIN
key, or a TR-31 skeleton token. In the case of a CCA DES PIN token, it must have one of the PIN
control vectors as shown in Table 1.
For a TR-31 token, it must have the following attributes:
- TR-31 key usage: P0
- Algorithm: T
- TR-31 mode of key use: D or E
On output, this parameter contains the PIN token with the derived PIN key.
- 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.
- transport_key_identifier_length
-
Length of the transport_key_identifier parameter in bytes. If the transport key identifier is not used, the length must be 0.
Direction: Input Type: Integer When DES is specified with TDES-TOK or TR31-TOK, the length must be 64.
When A-DUKPT and TR31-TOK are specified, this must be the length of the AES transport key specified in the transport_key_identifier. The maximum value is 725.
When a TR-31 token is used with either the DES or A-DUKPT keyword specified, this must be the length of the TR-31 transport key specified in the transport_key_identifier. The maximum value is 9992.
- transport_key_identifier
-
Direction: Input/Output Type: String When the DES keyword is specified the transport_key_identifier parameter is a pointer to a string variable containing an operational fixed-length CCA DES key-token, an operational TR-31 DES key-token, or the key label of such a record in key-storage. The CCA key token must have a key type of EXPORTER. In addition, it must have a control vector with bit 21 = B'1' (EXPORT). The TR-31 key token must have the following attributes:- TR-31 key usage: K0 or K1
- Algorithm: T
- TR-31 mode of key use: E
If keyword TDES-TOK is specified, this parameter identifies the key-encrypting key used to wrap the IPEK in an external CCA key-token. If TR31-TOK is specified, this parameter identifies the key- encrypting key used to wrap the IPEK in an external non-CCA TR-31 key block.
If A-DUKPT is specified, you may use a TR-31 AES token with the following attributes to wrap your generated key:
- TR-31 key usage: K1
- Algorithm: A
- TR-31 mode of key use: E
Otherwise, if A-DUKPT and derived data specified to generate an AES key this parameter identifies the key encrypting key used for exporting TR-31 key blocks, namely AES EXPORTER with EXPTT31D and WR-AES usage.
- reserved1_length
-
This parameter must be zero.
Direction: Input Type: Integer - reserved1
-
This parameter is ignored.
Direction: Ignored Type: String - reserved2_length
-
This parameter must be zero.
Direction: Input Type: Integer - reserved2
-
This parameter is ignored.
Direction: Ignored Type: String - reserved3_length
-
This parameter must be zero.
Direction: Input Type: Integer - reserved3
-
This parameter is ignored.
Direction: Ignored Type: String - reserved4_length
-
This parameter must be zero.
Direction: Input Type: Integer - reserved4
-
This parameter is ignored.
Direction: Ignored Type: String - reserved5_length
-
This parameter must be zero.
Direction: Input Type: Integer - reserved5
-
This parameter is ignored.
Direction: Ignored Type: String