Parameters

Edit online

The parameters for CSNBKTR2.

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
Direction: Input
Type: Integer
The number of keywords you supplied in the rule_array parameter. This value must be 0, 1, 2, or 3.
rule_array
Direction: Input
Type: String array
Keywords that provide control information to the verb. The keywords must be 8 bytes of contiguous storage with the keyword left-aligned in its 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Key Translate2 control information

Keywords for Key Translate2 control information
Keyword Description
Encipherment (Optional)
COMP-CHK Check if the key token to be translated or reformatted can have the PCI-HSM 2016 compliance tag.
COMP-TAG Convert the input key token into a PCI-HSM 2016 compliant-tagged token. This requires that the domain at first is in full PCI-HSM 2016 compliance mode and from there enters into the migration mode, which is a temporary reduced mode of an active PCI-HSM 2016 mode (see also Migration mode).
REFORMAT Reformat the input_key_token.
  • When the input_key_token is a DES key token, reformat with the Key Wrapping Method specified.
  • When the input_key_token is an operational AES key token, either reformat an AES DATA key (version X‘04’) to an AES CIPHER key (version X‘05’) or the reverse (version X’05’ to version X’04’).
TRANSLAT Translate the input_key_token from encipherment under the input_KEK_identifier to encipherment under the output_KEK_identifier. This is the default.
V1PYLD Re-encipher an input variable-length AES key token (version X‘05’) to a payload version 1 (fixed-length) key token. This keyword is only valid for the CIPHER, EXPORTER and IMPORTER key types.
V0PYLD Re-encipher an input variable-length AES key token (version X‘05’) to a payload version 0 (variable-length) key token. This keyword is only valid for the CIPHER, EXPORTER and IMPORTER key types.
Key-wrapping method (optional, valid only if input_key_token is an external DES key token). Not valid if using a TR- 31 token for the input/output_KEK_key_identifier parameters.
USECONFG This is the default. 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-ENH Use enhanced key wrapping method, which is compliant with the ANSI X9.24 standard.
WRAP-ECB Use original key wrapping method, which uses ECB wrapping for DES key tokens.
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.
Translation control (Optional, valid only with WRAP-ENH)
ENH-ONLY Restrict the re-wrapping of the output_key_token. Once the token has been wrapped with the enhanced method, it cannot be re-wrapped using the original method.
Algorithm (One required, if the V0PYLD or V1PYLD keyword is specified)
AES Specifies that the input key is an AES key. Where used, the key-encrypting keys will be AES transport keys.
DES Specifies that the input key is a DES key. Where used, the key-encrypting keys will be DES transport keys. This is the default.
HMAC Specifies that the input key is an HMAC key. Where used, the key-encrypting keys will be AES transport keys.
input_key_token_length
Direction: Input
Type: Integer
The length of the input_key_token in bytes. The maximum value allowed is 725.
input_key_token
Direction: Input
Type: String
A variable length string variable containing the external key token. The external key token contains the key to be re-enciphered (or re-wrapped).
input_KEK_key_identifier_length
Direction: Input
Type: Integer
The length of the input_KEK_key_identifier in bytes. The maximum value allowed is 9992.
input_KEK_key_identifier
Direction: Input/Output
Type: String
A variable length string variable containing the internal CCA or TR-31 key token or the key label of an internal key token record in the key storage file. The internal key token contains the key-encrypting key used to decipher the key.

For CCA tokens, the internal key token must contain a control vector that specifies an IMPORTER or IKEYXLAT key type. The control vector for an IMPORTER key must have the XLATE bit set to B'1'.

If the key is a TR-31 token, the KEK must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A or T
  • TR-31 mode of key use: D
output_KEK_key_identifier_length
Direction: Input
Type: Integer
The length of the output_KEK_key_identifier in bytes. The maximum value is 9992.

If the REFORMAT keyword is specified, this value must be 0.

output_KEK_key_identifier
Direction: Input/Output
Type: String
A variable length string variable containing the internal CCA or TR-31 key token or the key label of an internal key token record in the key storage file. The internal key token contains the key-encrypting key used to encipher the key.

For CCA tokens, the internal key token must contain a control vector that specifies an EXPORTER or OKEYXLAT key type. The control vector for an exporter key must have the XLATE bit set to B'1'.

For TR-31 tokens, the KEK must have the following attributes:

  • TR-31 key usage: K0
  • Algorithm: A or T
  • TR-31 mode of key use: E

If the REFORMAT keyword is specified, this parameter is ignored.

output_key_token_length
Direction: Input/Output
Type: Integer
On input, the length of the output area provided for the output_key_token. This must be at least 64 bytes. On output, the parameter is updated with the length of the token copied to the output_key_token.
output_key_token
Direction: Input/Output
Type: String
A variable length string variable containing an external key token. The external key token contains the re-enciphered key.
If the REFORMAT keyword is specified and the input_key_token is an AES DATA key (version X‘04’), output_key_token must contain an AES CIPHER key (version X‘05’) on input. The algorithm rule array keyword must specify AES and the token must have the following characteristics:
  • Algorithm is AES
  • Key type CIPHER
  • Key-usage field 2 either allows the key to be used for Cipher Block Chaining (CBC) mode or allows the key to be used for Electronic Code Book (ECB) mode.
  • (optional) The CPACF export key management bit may be enabled. The CPACF export status is copied to the output key token.
Otherwise, this field is ignored on input.

On output, a variable length string variable containing the key token that was translated or reformatted.

If the REFORMAT keyword is specified, and the input_key_token is an AES DATA key (version X‘04’), on output, the output_key_token is updated with the following characteristics:
  • Key-usage field 1 allows the key to be used for encryption and decryption.
  • Key-management field 1 allows export using symmetric, unauthenticated asymmetric, and authenticated asymmetric transport keys, and allows export using DES, AES, and RSA transport keys. If the output_key_token was an AES CIPHER key token with CPACF export enabled in key-management field 1 then this is enabled in the returned output_key_token.
  • Key-management field 2 indicates that the key is complete.