Key Test Extended (CSNBKYTX)

This verb is essentially the same as Key Test (CSNBKYT).

For further information, see Key Test (CSNBKYT). The differences are:

In addition to operating on internal keys and key parts, this verb also operates on external keys and key parts.
This verb does not operate on clear keys, and does not accept rule_array keywords CLR-A128, CLR-A192, CLR-A256, KEY-CLR, and KEY-CLRD.

See also Key Test (CSNBKYT) for operating only on internal keys.

Use this verb to verify the value of a key or key part in an external or internal key token. This verb supports two options:

GENERATE: To compute and return a verification pattern for a specified key.
VERIFY: To verify that a passed verification pattern is correct for the specified key.
The verification pattern and the verification process do not reveal any information about the value of the tested key, other than equivalency of two key values. Several verification algorithms are supported.

This verb supports testing of AES, DES, and PKA master keys, and enciphered keys or key parts. rule_array keywords are used to specify information about the target key that is not implicit from other verb parameters.

When testing the master keys, there are two sets of rule_array keywords to indicate what key to test:

The SYM-MK, ASYM-MK, and AES-MK master-key selector keywords indicate whether to test the DES (symmetric) master key, the PKA (asymmetric) master key, or the AES master key.
The KEY-KM, KEY-NKM, and KEY-OKM key or key-part rule_array keywords choose among the current-master-key register, the new-master-key register, and the old-master-key register.

Not specifying a master-key selector keyword (SYM-MK, ASYM-MK, or AES-MK) means that the DES (symmetric) and PKA (asymmetric) master keys have the same value, and that you want to test that value.

Several key test algorithms are supported by the verb. See Cryptographic key-verification techniques/>. Some are implicitly selected based on the type of key you are testing, while others are optional and selected by specifying a verification process rule keyword. You can specify one of the following:

The ENC-ZERO keyword to encrypt a block of binary zeros with the specified key. This verb returns the leftmost 32 bits of the encryption result as the verification pattern. The encrypted block consists of 16 bytes of binary zeros for AES, and eight bytes for DES and Triple-DES keys. This method is valid only with the TOKEN keyword for AES, and KEY-ENC and KEY-ENCD keywords for DES.
The MDC-4 keyword to compute a 16-byte verification pattern using the MDC-4 algorithm. This keyword is valid only when computing the verification pattern for a DES (symmetric) or PKA (asymmetric) master key.
The SHA-1 keyword to compute the verification pattern using the SHA-1 hashing method. This keyword is valid only when computing the verification pattern for the DES (symmetric) or PKA (asymmetric) master key.
The SHA-256 keyword to compute the verification pattern using the SHA-256 hashing method. This keyword is valid only when computing the verification pattern for an AES key.

Table 2 describes the use of the random_number and verification_pattern fields for each of the available verification methods.

Note: For historical reasons, the verification information is passed in two 8-byte variables pointed to by the random_number and verification_pattern parameters. The GENERATE option returns information in these two variables, and the VERIFY option uses the information provided in these two variables. If the verb cannot verify the information provided, it returns a return code of 4 and a reason code of 1. For simplicity, these two variables can be two 8-byte elements of a 16-byte array, which is processed by your application program as a single quantity. Both parameters must be coded when calling the API.

DES and Triple-DES keys reserve the low-order bit of each byte for parity. If parity is used, the low-order bit is set so that the total number of B'1' bits in the byte is odd. These parity adjustment keywords allow you to control how the Key Test Extended verb handles the parity bits:

NOADJUST: Specifies not to alter the parity bit values in any way. This is the default.
ADJUST: Specifies to modify the low-order bit of each byte as necessary for odd parity.
This is done on the cleartext value of the key before the verification pattern is computed. The parity adjustment is performed only on a temporary copy of the key within the card, and does not affect the key value in the key_identifier parameter.

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