Parameters
The parameters for CSNDKTC.
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. This value must be 1 or 2.Direction: Input Type: Integer - rule_array
The process rule for the verb. The keyword must be in eight bytes of contiguous storage, left-aligned, 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 PKA Key Token Change control information Keywords for PKA Key Token Change control information
Keyword Description Token type (One, optional) ECC Specifies that the key being changed is an ECC key. RSA Specifies that the key being changed is an RSA key or a trusted block. This is the default. QSA Specifies that the key being changed is a PQC key such as a CRYSTALS-Dilithium, CRYSTALS-Kyber, ML-KEM, or pure and pre-hash ML-DSA key. Re-encipherment method (One, required) RTCMK If the key_identifier is an RSA key token, the verb will change an RSA private key from encipherment with the old ASYM-MK to encipherment with the current ASYM-MK. If the key_identifier is a trusted block token, the verb will change the trusted block's embedded MAC key from encipherment with the old ASYM-MK to encipherment with the current ASYM-MK.
If the key_identifier is an ECC key token, the verb changes an ECC private key from encipherment with the old APKA-MK to encipherment with the current APKA-MK.
If the key_identifier is a PQC key token, for example, a CRYSTALS-Dilithium or ML-KEM key token, the verb changes a PQC private key from encipherment with the old APKA master key to encipherment with the current APKA master key.
RTNMK Re-enciphers a private (internal) RSA or ECC 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 63 will be returned.
For more information, see Key storage with Linux on IBM Z, in contrast to z/OS.
VALIDATE Validate an internal PKA key token which is under the current master key (same processing as RTNMK without checking the new master key or actually re-enciphering the token). - key_identifier_length
The length of the key_identifier parameter. The maximum size is 8000 bytes.Direction: Input Type: Integer - key_identifier
Contains an internal RSA key-token, ECC key-token, or PQC key token, an active trusted block, or a key label identifying such a key-record in PKA key-storage. The master-key enciphered data within the RSA key-token or trusted block is securely re-enciphered under the current PKA master key, and any such key token records are stored in PKA key-storage. The master-key enciphered OPK contained in an RSA private-key section with section identifier of X'30' or X'31' is securely re-enciphered under the current APKA master key, and any such key token records are stored in AES key-storage. The enciphered OPK of an ECC private key-token is securely re-enciphered under the current APKA master key. ECC key token records are stored in PKA key-storage.Direction: Input/Output Type: String If the key token is a PQC key token, the private key within the token is securely re-enciphered under the current APKA master key.