Key Test (CSNBKYT)

Edit online

Use the Key Test verb to generate or verify the value of either a master key, an internal AES key or key-part, or an internal DES key or key-part.

A key to test can be in the clear or encrypted under the master key. Keywords in the rule_array parameter specify whether the verb generates or verifies a verification pattern.

This algorithm is supported for clear and encrypted single and double length keys. Single, double and triple length keys are also supported with the ENC-ZERO algorithm. Clear triple length keys are not supported. See Cryptographic key-verification techniques.

With the default method, the verb generates a verification pattern and it creates and cryptographically processes a random number. This verb returns the random number with the verification pattern.

For historical reasons, the verification information is passed in two 8-byte variables pointed to by the value_1 and value_2 parameters. The GENERATE option uses these variables for output, and the VERIFY option uses these variables as input. For VERIFY, the verb returns a warning of return code 4, reason code 1 if the information provided in these variables does not match the calculated values.

Table 2 describes the use of the value_1 and value_2 variables for each of the available verification-process rule keywords.

Note: This verb supports PCI-HSM 2016 compliant-tagged key tokens.

This document uses new names for two of the parameters. The former names were misleading because they no longer reflected the use of these parameters. The header file, csulincl.h, continues to use the former names. See Table 1.

Table 1. Key Test parameter changes
Key Test parameter changes
Current name (used in this document)	Former name (used in header file)
value_1	random_number
value_2	verification_pattern

Table 2. Key Test GENERATE outputs and VERIFY inputs
Key Test GENERATE outputs and VERIFY inputs
Verification-process rule	GENERATE outputs and VERIFY inputs
Verification-process rule	value_1 variable	value_2 variable
ENC-ZERO	Unused	Contains the 4-byte KVP in the high-order 4 bytes of the variable, taken from the high-order 4 bytes of the encrypted result. The low-order 4 bytes of the variable are unspecified.
MDC-4	Contains the 8-byte KVP taken from the high-order 8 bytes of the MDC-4 hash value.	Contains the low-order 8 bytes of the MDC-4 hash value.
SHA-1	Contains the 8-byte KVP taken from the high-order 8 bytes of the SHA-1 hash value.	Contains the low-order 8 bytes of the SHA-1 hash value.
SHA-256	Unused	Contains the 8-byte KVP taken from the high-order 8 bytes of the SHA-256 hash value.
No keyword, and first and third parts of the master key have different values	Same as SHA-1	Same as SHA-1
No keyword, and first and third parts of the master key have the same value	Contains the 8-byte KVP taken from the result of the z/OS-based master-key verification method.	Unused