STATVKPR

Edit online

This keyword returns non-secret information about a particular named operational key part loaded by the TKE to the user.

This is different from STATKPR in that a register for creating a key in a variable length key token is described. The structures for various key types are given in section STATVKPR output data. An appropriate name for an existing operational key part is expected to be provided as described in STATVKPL input data. If not, the error return code of 8 and a reason code of 1026 is returned, meaning that the key name is not found.

STATVKPR input data:

A 64 byte key name must be provided in the verb_data field, while the verb_data_length must be set to 64.

The operational key name must match exactly the name returned by a call to STATVKPL.

STATVKPR output data:

See Table 1 for the output data format.
Note:
  1. The fields are returned in the order given.
  2. Output data overwrites the input data in the verb_data parameter, and set the verb_data_length parameter to the output value.
  3. The verb_data_length parameter indicates the total size, as shown at the bottom of the table describing the verb_data (Total byte count).

    Note that the output data is smaller than the input data.

  4. Multiple byte fields are stored in Big-Endian format, as is typical for CEX*C communication.
Table 1. Output data format for STATVKPR operational key parts

Output data format for STATVKPR operational key parts
Field name Length in bytes Description
version 1 Version of the structure
state 1 State of the key part register:
Value
Description
X'00'
The register is empty.
X'01'
The first DES key part was entered for the named key into this register.
X'02'
An intermediate DES key part (part after first) has been entered.
X'03'
The register contains a completed DES key.
X'11'
The first AES key part was entered for the named key into this register.
X'12'
An intermediate AES key part (part after first) has been entered.
X'13'
The register contains a completed AES key.
X'21'
The first AES key part for variable length token was entered for the named key into this register.
X'22'
An intermediate AES key part for variable length token (part after first) has been entered.
X'23'
The register contains a completed AES key part for variable length token.
key_length 1 Length of key in bytes. For DES keys, values are: 8, 16, 24. For AES keys, values are: 16, 24, 32.
key_completeness 1 Number of parts needed to complete key
X'C0'
Two parts are needed.
X'80'
One part is needed.
X'40'
No parts are needed. Key is complete.
ver_pattern 4 ENC-ZERO method calculated verification pattern of the key. This is the default behavior.

If the keyword ENC-ZERO has been passed and the key in the key part register is a DES key, then this field contains 3 bytes of an ENC-ZERO key check value over the key stored in the key part register. The remaining bytes are 0x00.

If the keyword CMACZERO has been passed but the keyword ENC-ZERO has not been passed, or if the key in the key part register is not a DES key, then this field will contain only bytes of 0x00.
key_part_hash 8 Hash using the SHA-256 algorithm over the key that is currently stored, at the current level of completeness. This is the default behavior.

If the keyword CMACZERO has been passed, then this field contains 5 bytes of a CMACZERO key check value over the key stored in the key part register. The remaining bytes are 0x00.

If the keyword ENC-ZERO has been passed, but the keyword CMACZERO has not been passed, then this field contains only bytes of 0x00.
skel_length 2 Skeleton token length.
pad 2 Pad structure to 4-byte boundary.
skel 384 Stored key token skeleton, which will hold completed key when operation is complete. No key material is stored or returned here.
reserved2 108 Extra bytes.
Total byte count 512