Parameters

Edit online

The parameters for CSNBKYT2.

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
The number of keywords you supplied in the rule_array parameter. This value must be 2, 3, 4, or 5.
rule_array
The rule_array contains keywords that 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 Test2 control information
Keyword Description
Process rule (One required).
GENERATE Generate a verification pattern and an associated random number for the input key or key part for the specified key.
VERIFY Verify that a verification pattern matches the specified key.
KEY-LEN Return the length of the specified key in the verification_pattern parameter. Valid for token algorithms AES and DES.
Token algorithm (Not allowed with AES-MK, APKA-MK, ASYM-MK, or SYM-MK; otherwise one required).
AES Specifies that the key token is a CCA or TR-31 AES key token.
DES Specifies that the key token is a CCA or TR-31 DES token. Clear keys are not supported for this rule.
HMAC Specifies that the key token is a CCA or TR-31 HMAC key token.
Master-key register class (Not allowed with AES, DES, or HMAC; otherwise one required).
AES-MK Specifies to process a master key in one of the AES master-key registers. Only valid with CMACZERO.
APKA-MK Specifies to process a master key in one of the AES PKA (APKA) master-key registers. Only valid with CMACZERO.
ASYM-MK Specifies to process a master key in one of the PKA (asymmetric) master-key registers. Only valid with CMACZERO or ENC-ZERO.
SYM-MK Specifies to process a master key in one of the DES (symmetric) master-key registers. Only valid with CMACZERO or ENC-ZERO.
Key or key-part rule (One required with AES-MK, APKA-MK, ASYM-MK, or SYM-MK; otherwise not allowed).
KEY-KM Specifies to process the master key in the current-master-key register.
KEY-NKM Specifies to process the master key in the new-master-key register, which can be an incomplete key if all key parts have not been loaded.
KEY-OKM Specifies to process the master key in the old-master-key register.
Key verification pattern (KVP) calculation algorithm (One required with AES-MK, APKA-MK, ASYM-MK, and SYMMK; otherwise one optional). See Cryptographic key-verification techniques. Not valid with the KEY-LEN process rule.
CMACZERO Specifies to use the CMAC-ZERO method for the key verification pattern (KVP) calculation for AES and DES keys. This method calculates the KVP by using the key to perform the NIST SP 800-38B block cipher-based MAC (CMAC) algorithm on a data block of the size of the algorithm block, filled with bytes valued to X'00' and an initialization vector valued to binary zeros. Only valid with AES, DES, AES-MK, APKA-MK, ASYM-MK, or SYM-MK. The CMACZERO method does not support single-length DES keys.
ENC-ZERO

Specifies to use the encrypt zeros method. This method calculates the key verification pattern (KVP) by using the key to encrypt a data block of the size of the algorithm block filled with bytes of X'00'. The initialization vector is bytes of X’00’, and the mode is cipher block chaining (CBC).

Only valid with AES, DES, ASYM-MK, or SYM-MK (not valid for HMAC). This is the default for DES.

This method is only available for AES if the Key Test2 - AES, ENC-ZERO access control point (offset X'0021)' is enabled.
SHA-256 Verification pattern is calculated for an AES token using the same method as the Key Test verb, with the SHA-256 rule. Only valid with AES; this is the default for AES.

This rule can be used to verify that the same key value is present in a version X'04' DATA token and version X'05' AES CIPHER token or to verify that the same key value is present in a version X'05' AES IMPORTER/EXPORTER pair.
SHA2VP1 Specifies to use the SHA-256 based verification pattern calculation algorithm. Valid only with HMAC. This is the default for HMAC. For more information, see SHAVP1 algorithm.
Token type rule (Required if TR-31 token passed and token algorithm DES is specified. Not valid otherwise.)
TR-31 Specifies that key_identifier contains an external or internal TR-31 key block.

Only valid with AES, DES, or HMAC. If an external TR-31 key block version ID (offset 0) is ‘D’ and the token Algorithm is DES (‘D’ or ‘T’), IKEK-AES must also be specified.
KEY-CLR Process a clear key or clear key-part that is not in a token. The algorithm is given by the Token algorithm keyword group, only valid with AES or DES. The length is given in the key_identifier_length parameter.
AESKWCV Specifies that the key identified by the key_identifier parameter is a DES key contained in an external version X’05’ variable-length symmetric CCA key token with a key type of DESUSECV. Only valid with DES. The IKEK-AES keyword must be specified for the KEK identifier rule.
KEK identifier rules Not allowed with AES-MK, APKA-MK, ASYM-MK, or SYM-MK. Otherwise, one required if:
  • the KEK_key_identifier variable contains a key label,
  • AESKWCV is specified and the input key token has a key type of DESUSECV,
  • TR-31 is specified and the key block has a version ID of “D” and the token Algorithm is DES (‘T’ or ‘D’),
  • if the key identified by the key_identifier parameter is external and wrapped using the PKOAEP2 method.
Otherwise one optional, provided that the algorithm of the keyword matches the algorithm of the KEK.
IKEK-AES Specifies that the key token identified by the key_encrypting_key_identifier parameter contains a CCA or TR-31 AES KEK. This keyword is required for DES if: (1) AESKWCV is specified, and the parameter identifies a key token with a key type of DESUSECV; or (2) if the TR-31 keyword is specified and the key_identifier parameter identifies a TR-31 key block that has a key block version ID of D.

This is the default for AES and HMAC.
IKEK-DES Specifies that the key token identified by the key_encrypting_key_identifier parameter contains a CCA or TR-31 DES KEK. Not valid with AESKWCV. Valid only for DES.

This is the default for DES.
IKEK-PKA Specifies that the key token identified by the key_encrypting_key_identifier parameter contains a CCA PKA KEK (RSA public key). Required if the key identified by the key_identifier parameter is external and wrapped using the PKOAEP2 method. This rule is not allowed with DES token algorithm (neither for CCA nor TR-31 tokens).

Not a default for any token algorithm.
Verification pattern length rule (One optional, if DES and CMACZERO are both specified, otherwise not allowed).
VPLEN3 Specifies that a 3-byte verification pattern is calculated. This is the default.
VPLEN5 Specifies that a 5-byte verification pattern is calculated.
key_identifier_length
The length of the key_identifier in bytes. The maximum value is 9992.
key_identifier
A pointer to the key for which to generate or verify the verification pattern. The parameter is a variable length string of an internal token or the 64-byte label of a key in key storage. This token may be a DES internal or external token, AES internal version X'04' token, internal or external variable-length symmetric token, or a TR-31 key block. Clear DES tokens are not supported. If an internal token was supplied and was encrypted under the old master key, the token will be returned encrypted under the current master key.
key_encrypting_key_identifier_length
The byte length of the key_encrypting_key_identifier parameter. When key_identifier is an internal token, the value must be zero.

If the key_encrypting_key_identifier is a label for a record in key storage, the value must be 64.

If the key_encrypting_key_identifier is a CCA AES KEK, the value must be between the actual length of the token and 725.

If the key_encrypting_key_identifier is a CCA DES KEK, the value must be 64.

If the key_encrypting_key_identifier is a CCA RSA KEK, the maximum length is 3500.

If the key_encrypting_key_identifier is a TR-31 KEK, the value must be between the actual length of the token and 9992.

key_encrypting_key_identifier
When key_encrypting_key_identifier_length is non-zero, the key_encrypting_key_identifier contains an internal key token containing the key-encrypting key, or a key label. If the key identifier supplied was a CCA AES or DES token encrypted under the old master key, the token will be returned encrypted under the current master key.

If the key_encrypting_key_identifier contains a TR-31 token, it must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A or T
  • TR-31 mode of key use: D or E

The ’K0’ TR-31 key usage is required when the key being wrapped is a CCA token. If the key is a TR-31 token, ‘K0’ or ‘K1’ can be used in this service. The ‘A’ Algorithm is required when the key being wrapped is an AES or HMAC key or a CCA DES key in a variable-length symmetric key-token. When dealing with fixed-length CCA DES keys or TR-31 DES keys, the ‘T’ or ‘A’ Algorithm may be used.

reserved_length
The byte length of the reserved parameter. This value must be 0.
reserved
This parameter is ignored.
verification_pattern_length
The length in bytes of the verification_pattern parameter.
Table 2. Length of the verification pattern for each algorithm supported
Calculation algorithm or Process rule Length of the verification pattern in bytes
CMACZERO
AES: 5
DES: 3 or 5
ENC-ZERO
Non-compliant-tagged tokens: 4
Compliant-tagged tokens: 3
The verification pattern is left-justified in an 8-byte field and padded on the right with zeros.
SHA-256 8
SHA2VP1 9
KEY-LEN (process rule)
AES: 2
DES: 4

On input: for GENERATE the length must be at least 8 bytes; for VERIFY the length must be 8 bytes.

On output for GENERATE the length of the verification pattern returned.

verification_pattern
A pointer to a string variable containing the binary verification pattern.

For GENERATE, the verb generates and returns the left-most, high-order bytes of the generated verification pattern in this variable.

For VERIFY, the verb verifies the verification pattern supplied in this variable.

For KEY-LEN, the length of the key in the supplied key_identifier is as shown in Table 3.
Table 3. Returned data for the KEY-LEN process rule
Token algorithm Data format
DES 4 bytes:
  • Stored key bit length: 2 bytes, Big-Endian binary integer
  • Effective key bit length: 2 bytes, Big-Endian binary integer
Possible values: 56 (X'0038'), 112 (X'0070'), 168 (X'00A8')
AES 2 bytes:
  • Stored key bit length: 2 bytes, Big-Endian binary integer
Possible values: 128 (X'0080'), 192 (X'00C0'), 256 (X'0100')