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, 3, 4, or 5.

rule_array

Direction:	Input
Type:	String array

Between two and five keywords provide control information to the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.

Table 1. Keywords for Key Test Extended control information

Keywords for Key Test Extended control information

Keyword	Description
Process rule (One required)
GENERATE	Generate a verification pattern for the key supplied in key_identifier.
VERIFY	Verify a verification pattern for the key supplied in key_identifier.
Key or key-part rule (One required)
KEY-ENC	Specifies that the key supplied in key_identifier is a single-length encrypted key.
KEY-ENCD	Specifies that the key supplied in key_identifier is a double-length encrypted key.
KEY-KM	Specifies that the target is the master key register.
KEY-NKM	Specifies that the target is the new master-key register.
KEY-OKM	Specifies that the target is the old master-key register.
TOKEN	Process an AES clear or encrypted key contained in an AES key-token.
Master-key selector (One, optional). Use only with KEY-KM, KEY-NKM, or KEY-OKM keywords. The default is to process the ASYM-MK and SYM-MK key registers, which must have the same key for the default to be valid.
AES-MK	Process one of the AES master-key registers.
APKA-MK	Process one of the APKA master-key registers.
ASYM-MK	Specifies use of only the asymmetric master-key registers.
SYM-MK	Specifies use of only the symmetric master-key registers.
Parity adjustment (One, optional) Not valid with the AES-MK Master-key selector keyword.
ADJUST	Adjust the parity of test key to odd before generating or verifying the verification pattern. The key_identifier field itself is not adjusted.
NOADJUST	Do not adjust the parity of test key to odd before generating or verifying the verification pattern. This is the default.
Verification process rule (One, optional) For the AES master key, SHA-256 is the default. For the DES or PKA master keys, the default is SHA-1 if the first and third parts of the key are different, or the IBM® z/OS® method if the first and third parts of the key are the same.
ENC-ZERO	Specifies use of the encrypted zeros method. Use only with the KEY-CLR, KEY-CLRD, KEY-ENC, or KEY-ENCD keywords. A 4-byte verification pattern is generated for non-compliant-tagged tokens. A 3-byte verification pattern is generated for compliant-tagged tokens. Required for triple-length TDES keys.
MDC-4	Specifies use of the MDC-4 master key verification method. Use only with the KEY-KM, KEY-NKM, or KEY-OKM keywords. You must specify one master-key selector keyword to use this keyword.
SHA-1	Specifies use of the SHA-1 master-key-verification method. Use only with the KEY-KM, KEY-NKM, or KEY-OKM keywords. You must specify one master-key selector keyword to use this keyword.
SHA-256	Specifies use of the SHA-256 master-key-verification method.

key_identifier

Direction:	Input
Type:	String

A pointer to a string variable containing an internal or external key-token, a key label that identifies an internal or external key-token record, or a clear key.

The key token contains the key or the key part used to generate or verify the verification pattern.

random_number

Direction:	Input/Output
Type:	String

A pointer to a string variable containing a number the verb might use in the verification process. When you specify the GENERATE keyword, the verb returns the random number. When you specify the VERIFY keyword, you must supply the number. With the ENC-ZERO method, the random_number variable is not used but must be specified.

verification_pattern

Direction:	Input/Output
Type:	String

A pointer to a string variable containing the binary verification pattern. When you specify the GENERATE keyword, the verb returns the verification pattern. When you specify the VERIFY keyword, you must supply the verification pattern. With the ENC-ZERO method, the verification data occupies the high-order four bytes, while the low-order four bytes are unspecified (the data is passed between your application and the cryptographic engine but is otherwise unused). For more detail, see Cryptographic key-verification techniques.

kek_key_identifier

Direction:	Input
Type:	String

A pointer to a string variable containing an operational key-token or the key label of an operational key-token record containing an IMPORTER or EXPORTER key-encrypting key. If the key_identifier parameter does not identify an external key-token, the contents of the kek_key_identifier variable should contain a null DES key-token.