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 2.

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 Change2 control information

Keywords for Key Token Change2 control information

Keyword	Description
Algorithm (One, required)
HMAC	Specifies that the key token is for an HMAC key in a CCA or TR-31 key token. When using a TR-31 token, the key_identifier must have the following properties: TR-31 key usage: M7 Algorithm: H TR-31 mode of key use: C, G, or V
AES	Specifies that the key token is for an AES key in a variable-length CCA or TR-31 symmetric key token. When using a TR-31 token, the key_identifier must have the Algorithm A attribute.
DES	Specifies that the key token is for a DES key in a TR-31 key token (CCA DES key tokens are not allowed). The TR-31 token used in the key_identifier parameter must have the Algorithm D or T attribute.
Re-encipherment method (Required)
RTCMK	Re-enciphers the internal key provided by the key_identifier 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 the internal key provided by the key_identifier 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 anymore, 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.

key_identifier_length

Direction:	Input/Output
Type:	Integer

A pointer to a string variable containing the length in bytes of the key_identifier parameter. On input, this variable contains the number of bytes for the key_identifier buffer, and must be large enough to hold the key token or key label. On output, this variable contains the number of bytes of data returned in the key_identifier variable.

key_identifier

Direction:	Input/Output
Type:	String

A pointer to a string variable containing an internal variable-length CCA or TR-31 symmetric key-token, or a key label of such a key in AES key-storage or combined key storage. The key token referred to is processed according to the rule-array keywords.