STATTKPR

Edit online

This keyword returns non-secret information about a particular named TR-31 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 TR-31 key token is described. The structures for various key types are given in section STATTKPR output data. An appropriate name for an existing operational key part is expected to be provided as described in STATTKPR input data. If not, an error return code of 8 and a reason code of 1026 is returned, meaning that the key name is not found.

STATTKPR input data:

A 64 byte key name must be provided in the verb_data parameter, while the verb_data_length parameter must be set to 64. The operational key name must match exactly the name returned by a call to STATTKPL.

STATTKPR 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 sets 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 STATTKPR, TR-31 operational key parts

Output data format for STATTKPR, TR-31 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 the key in bytes.
  • For DES keys, values are: 8, 16, or 24.
  • For AES keys, values are: 16, 24, or 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 The verification pattern of the key, calculated with the ENC-ZERO method. This is only allowed for DES keys, where it 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 three 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 contains 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. CMACZERO is the default for DES and AES, and not allowed with HMAC.

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 TR-31 key block header, which holds completed key when operation is complete. No key material is stored or returned here.
reserved2 108 Extra bytes.
Total byte count 512