Parameters

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

A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1, 2, 3, or 4.

rule_array

Direction:	Input
Type:	String array

The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.

Table 1. Keywords for Key Token Change control information

Keywords for Key Token Change control information

Keyword	Description
Re-encipherment method (Required)
RTCMK	Re-enciphers a DES or AES key to the current master-key in an internal key-token in application storage or in key storage. If the supplied key is already enciphered under the current master-key the verb returns a positive response (return code 0, reason code 0). If the supplied key is enciphered under the old master-key, the key is updated to encipherment by the current master-key and the verb returns a positive response (return code 0, reason code 0). Other cases return some form of abnormal response.
RTNMK	Re-enciphers an internal DES or AES key to the new master-key. A key enciphered under the new master key is not usable. It is expected that the user will use this keyword (RTNMK) to take a preparatory step in re-enciphering an external key store that they manage themselves to a new master-key, before the set operation has occurred. Note also that the new master-key register must be full; it must have had the last key part loaded and therefore not be empty or partially full (partially full means that one or more key parts have been loaded but not the last key part). The SET operation makes the new master-key operational, moving it to the current master-key register, and the current master-key is displaced into the old master-key register. When this happens, all the keys that were re-enciphered to the new master-key are now usable, because the new master-key is not 'new' any more, it is 'current'. Because the RTNMK keyword is added primarily for support of externally managed key storage (see Key storage on z/OS (RTNMK-focused), it is not valid to pass a key_identifer when the RTNMK keyword is used. Only a full internal key token (encrypted under the current master-key) can be passed for re-encipherment with the RTNMK keyword. When a key label is passed along with the RTNMK keyword, the error return code 8 with reason code 181 will be returned. For more information, see Key storage with Linux on IBM Z, in contrast to z/OS.
VALIDATE	Validate an internal key token as described in the key_identifier which is enciphered under the current master key. That is, the same processing as RTNMK is applied. However, after a successful checking of the token, no re-enciphering of the token to the new master key takes place. There is just a return code for a successful validation.
REFORMAT	Rewrap the input_key_token with the key wrapping method specified. Only the input_KEK_identifier will be used. The output_KEK_identifier is ignored.
Algorithm (Optional)
AES	Specifies that the key token is for an AES key.
DES	Specifies that the key token is for a DES key. This is the default.
Key wrapping method (Optional)
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 and CBC wrapping for AES 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)
ENH-ONLY	Restrict rewrapping of the output_key_token. After the token has been wrapped with the enhanced method, it cannot be rewrapped using the original method.

key_identifier

Direction:	Input/Output
Type:	String

The key_identifier parameter is a pointer to a string variable containing the DES internal key-token or the key label of an internal key-token record in key storage.