General format of a variable-length symmetric key-token

Edit online

View a table showing the general format of a variable-length symmetric key-token.

Table 1. General format of a variable-length symmetric key-token, version X'05'

General format of a variable-length symmetric key-token, version X'05'
Offset (bytes) Length (bytes) Description
Header
000 01 Token identifier:
Value
Meaning
X'00'
Null key-token.
X'01'
Internal key-token (encrypted key is wrapped with the master key, the key is clear, or there is no payload).
X'02'
External key-token (encrypted payload is wrapped with a transport key, the payload is clear, or there is no payload). A transport key can be a key-encrypting key or an RSA public-key.

All unused values are reserved and undefined.
001 01 Reserved, binary zero.
002 02 Length in bytes of the overall token structure. For a null key-token, the value is 8. Otherwise, the length is calculated as:

46 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlvs + ((pl + 7) / 8)

Value
Meaning
kuf
See key usage fields count at offset 44.
kmf
See key management fields count at offset 45 + (2 * kuf).
kl
See key label length at offset 46 + (2 * kuf) + (2 * kmf).
iead
See IBM extended associated data length at offset 46 + (2 * kuf) + (2 * kmf) + kl.
uad
See user associated data length at offset 46 + (2 * kuf) + (2 * kmf) + kl + iead.
tlvs
This value is currently 0. Tag-length-value data is defined for future use.
pl
See payload length in bits at offset 38.
004 01 Token version number (identifies the format of this key token):
Value
Meaning
X'05'
Version 5 format of the key token (variable-length symmetric key-token)
005 03 Reserved, binary zero.
End of header
Wrapping information section (all data related to wrapping the key)
008 01 Key material state:
Value
Meaning
X'00'
No key is present. This is called a skeleton key-token. The key token is external or internal.
X'01'
Key is clear. Only valid with AES CIPHER or HMAC MAC. The key token is external or internal.
X'02'
Key is wrapped with a transport key. When the encrypted section key-wrapping method is AESKW (value at offset 26 is X'02'), the transport key is an AES key-encrypting key. When it is PKOAEP2 (value at offset 26 is X'03'), the transport key is an RSA public-key. The key token is external.
X'03'
Key is wrapped with the AES master-key. The encrypted section key-wrapping method is AESKW. The key token is internal.

All unused values are reserved and undefined.
009 01 Key verification pattern (KVP) type:
Value
Meaning
X'00'
No KVP (no key present, key is clear, or key is wrapped with an RSA public-key). The key token is external or internal.
X'01'
AESMK (8 leftmost bytes of SHA-256 hash: X'01 || clear AES MK). The key token is internal.
X'02'
Key-encrypting key (8 leftmost bytes of SHA-256 hash: X'01 || clear KEK). The key token is external.
X'03'
Truncated AES master key verification pattern with compliance information.

All unused values are reserved and undefined.
010 16 This field has different meanings for compliant-tagged and non-compliant tagged key tokens.
1. Non-compiant tagged key tokens: KVP of the key used to wrap the payload (value depends on value of key material state, that is, the value at offset 8):
Value at offset 8
Value of KVP
X'00'
The key-material state is no key present. The field should be filled with binary zeros. The key token is external or internal.
X'01'
The key-material state is key is clear. The field should be filled with binary zeros. The key token is external or internal.
X'02'
The key material state is the key is wrapped with a transport key. The value of the KVP depends on the value of the encrypted section key-wrapping method:
  • When the key-wrapping method is AESKW (value at offset 26 is X'02'), the field contains the KVP of the key-encrypting key used to wrap the key. The 8-byte KEK KVP is left-aligned in the field and padded on the right low-order bytes with binary zeros.
  • When the key-wrapping method is PKOAEP2 (value at offset 26 is X'03'), the value should be filled with binary zeros. The encoded message, which contains the key, is wrapped with an RSA public-key.

The key token is external.

X'03'
The key-material state is the key is wrapped with the AES master-key. The field contains the MKVP of the AES master-key used to wrap the key. The 8-byte MKVP is left-aligned in the field and padded on the right low-order bytes with binary zeros. The key token is internal.

2. Compliant -tagged key tokens: 5 bytes of the AES MKVP followed by 3 bytes of internal compliance information.

Values are left justified.
026 01 Encrypted section key-wrapping method (indicates the key-wrapping method used to protect the data in the encrypted section):
Value
Meaning
X'00'
No key-wrapping method (no key present or key is clear). The key token is external or internal.
X'02'
AESKW (ANS X9.102). The key token is external with a key wrapped by an AES key-encrypting key, or the key token is internal with a key wrapped by the AES master-key.
X'03'
PKOAEP2. Message M, which contains the key, is encoded using the RSAES-OAEP scheme of the RSA PKCS #1 v2.1 standard. The encoded message (EM) is produced using the given hash algorithm by encoding message M using the Bellare and Rogaway Optimal Asymmetric Encryption Padding (OAEP) method for encoding messages. For PKAOEP2, M is defined as follows:

M = [32 bytes: hAD] || [2 bytes: bit length of the clear key] || [clear key]

where hAD is the message digest of the associated data, and is calculated using the SHA-256 algorithm on the data starting at offset 30 for the length in bytes of all the associated data for the key token (length value at offset 32).

EM is wrapped with an RSA public-key. The key token is external.

All unused values are reserved and undefined.
027 01 Hash algorithm used for wrapping key or encoding message. Meaning depends on whether the encrypted section key-wrapping method (value at offset 26) is no key-wrapping method, AESKW, or PKOAEP2:

No key-wrapping method (value at offset 26 is X'00')

Hash algorithm used for wrapping key when encrypted section key-wrapping method is no key-wrapping method:

X'00'
No hash (no key present or key is clear).

All unused values are reserved and undefined. The key token is external or internal.

AESKW key-wrapping method (value at offset 26 is X'02')

Hash algorithm used for wrapping key when encrypted section key-wrapping method is AESKW. The value indicates the algorithm used to calculate the message digest of the associated data. The message digest is included in the wrapped payload and is calculated starting at offset 30 for the length in bytes of all the associated data for the key token (length value at offset 32).

X'01'
SHA-224 (not used)
X'02'
SHA-256
X'04'
SHA-384 (defined for future use)
X'08'
SHA-512 (defined for future use)

All unused values are reserved and undefined. The key token is external or internal.

PKOAEP2 key-wrapping method (value at offset 26 is X'03')

Hash algorithm used for encoding message when encrypted section key-wrapping method is PKOAEP2. The value indicates the given hash algorithm used for encoding message M using the RSAES-OAEP scheme of the RSA PKCS #1 v2.1 standard.

X'01'
SHA-1
X'02'
SHA-256
X'04'
SHA-384
X'08'
SHA-512

All unused values are reserved and undefined. The key token is external.
028 01 Payload format version (identifies format of the payload):
Value
Meaning
X'00'
V0 payload (V0PYLD). Only supported on HMAC MAC and AES CIPHER, EXPORTER, and IMPORTER key types. The payload format depends on the encrypted section key-wrapping method indicated by the value at offset 26, as shown:
X'00'
There is no key-wrapping method. When no key is present, there is no payload. When the key is clear (AES CIPHER and HMAC MAC only), the payload is unformatted. The key token is external or internal.
X'02'
The key-wrapping method is AESKW and the payload is variable length. The payload is formatted with the minimum size possible to contain the key material. The payload length varies for a given algorithm and key type. The key length can be inferred by the size of the payload. The key token is external or internal.
X'03'
The key-wrapping method is PKOAEP2 and the payload length is equal to the modulus size in bits of the RSA transport key used to wrap the encoded message. The key token is external. When the external key is exported, the internal target key has the same V0 payload format.
X'01'
V1 payload (V1PYLD). Supported on all key types except HMAC MAC. The payload format depends on the encrypted section key-wrapping method indicated by the value at offset 26, as shown:
X'00'
There is no key-wrapping method. When no key is present, there is no payload. When the key is clear (AES CIPHER only), the payload is unformatted. The key token is external or internal.
X'02'
The key-wrapping method is AESKW and the payload is fixed length based on the maximum possible key size of the algorithm for the key. The key is padded with random data to the size of the largest key for that algorithm. This helps to deter attacks on keys known to be weaker. The key length cannot be inferred by the size of the payload. The key token is external or internal.
X'03'
The key-wrapping method is PKOAEP2 and the payload length is equal to the modulus size in bits of the RSA transport key used to wrap the encoded message. The key token is external. When the external key is exported, the internal target key will have the same V1 payload format.

All unused values are reserved and undefined.
029 01 Reserved, binary zero.

End of wrapping information section

Clear key, AESKW, or PKOAEP2 components: (1) associated data sections and (2) optional clear key payload, wrapped AESKW formatted payload, or wrapped PKOAEP2 encoded payload (no payload if no key present)
Associated data sections: (1) required associated data section and (2) optional associated data sections
Required associated data section
030 01

Associated data section version:

Value
Meaning
X'01'
Version 1 format of associated data
031 01 Reserved, binary zero.
032 02 Length in bytes of all the associated data for the key token (adl): ≥ 16.
034 01 Length in bytes of the optional key label (kl): 0 or 64.
035 01 Length in bytes of the optional IBM extended associated data (iead): 0 - 255.
036 01 Length in bytes of the optional user-definable associated data (uad): 0 - 255.
037 01 Reserved, binary zero.
038 02 Length in bits of the clear or wrapped payload (pl): ≥ 0.
  • For no key-wrapping method (no key present or key is clear), pl is the length in bits of the key. For no key present, pl is 0. For key is clear (AES CIPHER and HMAC MAC only), pl can be 128, 192, or 256 for an AES key, or 80 - 2048 for an HMAC key.
  • For PKOAEP2 encoded payloads, pl is the length in bits of the modulus size of the RSA key used to wrap the payload. This can be 512 - 4096.
  • For an AESKW formatted payload, pl is based on the key size of the algorithm type (DES, AES, or HMAC) and the payload format version:

    DES algorithm (value at offset 41 is X'01')

    A DES key can have a length of 8, 16, or 24 bytes (64, 128, 192 bits). A DES key in an AESKW formatted payload is always wrapped with a V1 payload and has a fixed length payload of 576 bits.

  • AES algorithm (value at offset 41 is X'02'). An AES key can have a length of 16, 24, or 32 bytes (128, 192, or 256 bits). A V0 payload is only valid for HMAC MAC and AES CIPHER, EXPORTER, and EXPORTER keys. A V1 payload is not valid for an HMAC MAC key. The following table shows the payload length for a given AES key size and payload format:
                            Bit length of            Bit length of
                        V0 payload (value at     V1 payload (value at
AES key size            offset 28 is X'00')      offset 28 is X'01')
16 bytes (128 bits)     512                      640
24 bytes (192 bits)     576                      640
32 bytes (256 bits)     640                      640

HMAC algorithm (value at offset 41 is X'03'). An HMAC key can have a length of 80 - 2048 bits. An HMAC key in an AESKW formatted payload is always wrapped with a V0 payload.
040 01 Reserved, binary zero.
041 01 Type of algorithm for which the key can be used: 

Value        Meaning       Supported key types by release
X'01'        DES           Release 4.4 or later: DESUSECV
X'02'        AES           Release 4.2 or later: CIPHER
                           Release 4.4 or later: MAC
                           Release 4.2 or later: EXPORTER
                           Release 4.2 or later: IMPORTER
                           Release 4.4 or later: PINPROT
                           Release 4.4 or later: PINCALC
                           Release 4.4 or later: PINPRW
                           Release 4.4 or later: DKYGENKY
                           Release 4.4.55 or later: SECMSG
X'03'        HMAC          Release 4.1 or later: MAC

All unused values are reserved and undefined.
042 02 Key type (general class of the key):

For algorithm AES:

Value
Meaning
X'0001'
CIPHER
X'0002'
MAC
X'0003'
EXPORTER
X'0004'
IMPORTER
X'0005'
PINPROT
X'0006'
PINCALC
X'0007'
PINPRW
X'0008'
DESUSECV
X'0009'
DKYGENKY
X'000A'
SECMSG
X'000B'
KDKGENKY

For algorithm HMAC:

X'0002'
MAC

For algorithm DES:

X'0008'
DESUSECV

All unused values are reserved and undefined.
044 01 Key usage fields count (kuf): 0 - 255. Key-usage field information defines restrictions on the use of the key.

Each key type can have a variable number of key usage fields from none to a maximum of 255. Each key-usage field is 2 bytes in length. The value in this field indicates how many 2-byte key usage fields follow.
045, for kuf > 0 01 Optional key-usage field 1, high-order byte.

Defined based on algorithm type (value at offset 41) and key type (value at offset 42).

All unused bits are reserved and must be zero.
046, for kuf > 0 01 Optional key-usage field 1, low-order byte (user-defined extension control):
Value
Meaning
B'xxxx 1xxx'
Key can only be used in UDXs (UDX-ONLY).
B'xxxx 0xxx'
Key can be used in UDXs and CCA.
B'xxxx x1uu'
UDX-defined bit reserved for UDXs (UDX-100).
B'xxxx xu1u'
UDX-defined bit reserved for UDXs (UDX-010).
B'xxxx xuu1'
UDX-defined bit reserved for UDXs (UDX-001).
Note: This byte is common for all key types except for DES DESUSECV in which case this byte is reserved and must zero.

All unused bits are reserved and must be zero.
047, for kuf > 1 01 Optional key-usage field 2, high-order byte.
048, for kuf > 1 01 Optional key-usage field 2, low-order byte.


.
.
.
043 + (2 * kuf), for kuf > 0 01 Optional key-usage field kuf, high-order byte.
044 + (2 * kuf), for kuf > 0 01 Optional key-usage field kuf, low-order byte.
045 + (2 * kuf) 01 Key management fields count (kmf): 0 - 255. Key-management field information describes how the data is to be managed or helps with management of the key material.

Each key type can have a variable number of key management fields from none to a maximum of 255. Each key-management field is 2 bytes in length. The value in this field indicates how many 2-byte key management fields follow.
046 + (2 * kuf), for kmf > 0 01 Optional key-management field 1, high-order byte (export control):
Symmetric-key export control:
Value
Meaning
B'1xxx xxxx'
Allow export using symmetric key (XPRT-SYM). B'0xxx xxxx' for prohibiting (NOEX-SYM).
Unauthenticated asymmetric-key export control:
Value
Meaning
B'x1xx xxxx'
Allow export using unauthenticated asymmetric key (XPRTUASY). B'x0xx xxxx' for prohibiting (NOEXUASY). Not a trusted block.
Authenticated asymmetric-key export control:
Value
Meaning
B'xx1x xxxx'
Allow export using authenticated asymmetric key (XPRTAASY). B'xx0x xxxx' for prohibiting (NOEXAASY). Not a trusted block.
RAW-key export control:
Value
Meaning
B'xxx1 xxxx'
Allow export using RAW key (XPRT-RAW). B'xxx0 xxxx' for prohibiting (NOEX-RAW). Defined for future use. Currently ignored.
Compliance information:
Value
Meaning
B'xxx1 xxxx'
Compliant-tagged key. Applies to AES only. B'xxx0 xxxx' for non-compliant tagged keys.
Note: This byte is common for all key types. Except for DES DESUSECV, this byte is reserved and must zero.

All unused bits are reserved and must be zero.
047 + (2 * kuf), for kmf > 0 01 Optional key-management field 1, low-order byte (export control by algorithm):

DES-key export control:

Value
Meaning
B'1xxx xxxx'
Prohibit export using DES key (NOEX-DES).
B'0xxx xxxx'
Allow export using DES key (XPRT-DES).

AES-key export control:

Value
Meaning
B'x1xx xxxx'
Prohibit export using AES key (NOEX-AES).
B'x0xx xxxx'
Allow export using AES key (XPRT-AES).

RSA-key export control:

Value
Meaning
B'xxxx 1xxx'
Prohibit export using RSA key (NOEX-RSA).
B'xxxx 0xxx'
Allow export using RSA key (XPRT-RSA).
Note: This byte is common for all key types except for DES DESUSECV in which case this byte is undefined.

All unused bits are reserved and must be zero.
048 + (2 * kuf), for kmf > 1 01 Optional key-management field 2, high-order byte (key completeness):
Value
Meaning
B'11xx xxxx'
Key is incomplete. Key requires at least 2 more parts (MIN3PART).
B'10xx xxxx'
Key is incomplete. Key requires at least 1 more part (MIN2PART).
B'01xx xxxx'
Key is incomplete. Key can be completed or have more parts added (MIN1PART).
B'00xx xxxx'
Key is complete or no key present. If key is present, no more parts can be added (KEYCMPLT).
Note: This byte is common for all key types except for DES DESUSECV in which case this byte is undefined.

All unused bits are reserved and must be zero.
049 + (2 * kuf), for kmf > 1 01 Optional key-management field 2, low-order byte (security history). Used to reflect the overall history of the key, not just the history at the most recent import or other operation.
Value
Meaning
B'xxx1 xxxx'
Previously encrypted with an untrusted KEK (UNTRUSTD).
B'xxxx 1xxx'
Previously in a format without type or usage attributes (WOTUATTR).
B'xxxx x1xx'
Previously encrypted with a key weaker than itself (WWEAKKEY).
B'xxxx xx1x'
Previously in a non-CCA format (NOTCCAFM).
B'xxxx xxx1'
Previously encrypted in ECB mode (WECBMODE).
Note: This byte is common for all key types except for DES DESUSECV in which case this byte is undefined.

All unused bits are reserved and must be zero.
050 + (2 * kuf), for kmf > 2 01 Optional key-management field 3, high-order byte (pedigree original). Used to indicate how the key was originally created and how it got into the current system.
Value
Meaning
X'00'
Unknown (POUNKNWN).
X'01'
Other method than those defined here, probably used in UDX (POOTHER).
X'02'
Randomly generated (PORANDOM).
X'03'
Established by key agreement such as Diffie-Hellman (POKEYAGR).
X'04'
Created from cleartext key components (POCLRKC).
X'05'
Entered as a cleartext key value (POCLRKV).
X'06'
Derived from another key (PODERVD).
X'07'
Cleartext keys or key parts that were entered at a TKE and secured from there to the target card (POKPSEC).
Note: This byte is common for all key types except for DES DESUSECV in which case this byte is undefined.

All unused values are reserved and must be zero.
051 + (2 * kuf), for kmf > 2 01 Optional key-management field 3, low-order byte (pedigree current). Used to indicate how the key was originally created and how it got into the current system.

Description is continued on next table row.

Description continued for offset 051 + (2 * kuf), for kmf > 2:

X'00': Unknown (PCUNKNWN).

X'01': Other method than those defined here, probably used in UDX (PCOTHER).

X'02': Randomly generated (PCRANDOM).

X'03': Established by key agreement such as Diffie-Hellman (PCKEYAGR).

X'04': Created from cleartext key components (PCCLCOMP).

X'05': Entered as a cleartext key value (PCCLVAL).

X'06': Derived from another key (PCDERVD).

X'07': Imported from CCA Version X'05' variable-length symmetric key-token with pedigree field (PCMVARWP).

X'08': Imported from CCA Version X'05' variable-length symmetric key-token with no pedigree field (PCMVARNP).

X'09': Imported from CCA key-token that contained a nonzero control vector (PCMWCV).

X'0A': Imported from CCA key-token that either had no control vector or contained a zero control vector (PCMNOCV).

X'0B': Imported from a TR-31 key block that contained a control vector (ATTR-CV option) (PCMT31WC).

X'0C': Imported from a TR-31 key block that did not contain a control vector (PCMT31NC).

X'0D': Imported using PKCS 1.2 RSA encryption (PCMPK1-2).

X'0E': Imported using PKCS OAEP encryption (PCMOAEP).

X'0F': Imported using PKA92 RSA encryption (PCMPKA92).

X'10': Imported using RSA ZERO-PAD encryption (PCMZ-PAD).

X'11': Converted from a CCA key-token that contained a nonzero control vector (PCCNVTWC).

X'12': Converted from a CCA key-token that either had no control vector or contained a zero control vector (PCCNVTNC).

X'13': Cleartext keys or key parts that were entered at a TKE and secured from there to the target card (PCKPSEC).

X'14': Exported from CCA Version X'05' variable-length symmetric key-token with pedigree field (PCXVARWP).

X'15': Exported from CCA Version X'05' variable-length symmetric key-token with no pedigree field (PCXVARNP).

X'16': Exported using PKCS OAEP encryption (PCXOAEP).

Note: This byte is common for all key types except for DES DESUSECV in which case this byte is undefined.

All unused values are reserved and must be zero.

.
.
.
044 + (2 * kuf) + (2 * kmf), for kmf > 0 01 Optional key-usage field kmf, high-order byte.
045 + (2 * kuf) + (2 * kmf), for kmf > 0 01 Optional key-usage field kmf, low-order byte.
046 + (2 * kuf) + (2 * kmf) kl Optional key label.
046 + (2 * kuf) + (2 * kmf) + kl iead Optional IBM extended associated data.
046 + (2 * kuf) + (2 * kmf) + kl + iead uad Optional user-defined associated data.
End of required associated data section
Optional associated data sections (defined for future use)
Optional tag-length-value (TLV) fields.

The length of tlvn is in bytes and is calculated as follows:

tlvn = size of TLVn tag + size of tlvn length field + size of the TLV n value in bytes

for n > 0, where n = number of TLV fields.

The summation of TLV lengths is in bytes and is calculated as follows:


         n
tlvs =  ∑  tlvi
        i=1

for n > 0, where n = number of TLV fields. For n = 0, tlvs = 0.
046 + (2 * kuf) + (2 * kmf) + kl + iead + uad, for tlv1 > 0 01 Optional tag-length-value 1 (TLV1) tag.
047 + (2 * kuf) + (2 * kmf) + kl + iead + uad, for tlv1 > 0 02 Optional TLV1 length: tlv1.
049 + (2 * kuf) + (2 * kmf) + kl + iead + uad, for tlv1 > 0 tlv1 - 3 Optional TLV1 value.
046 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlv1, for n > 1 01 Optional tag-length-value 2 (TLV2) tag.
047 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlv1, for n > 1 02 Optional TLV2 length: tlv2.
049 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlv1, for n > 1 tlv2 - 3 Optional TLV2 value.


.
.
.
046 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlvs - tlv n, for n > 0 01 Optional TLVn tag.
047 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlvs - tlv n, for n > 0 02 Optional TLVn length: tlv n
049 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlvs - tlv n, for n > 0 tlv n - 3 Optional TLVn value.
End of TLV fields
End of optional associated data sections
End of associated data sections
Optional clear key payload, wrapped AESKW formatted payload, or wrapped PKOAEP2 encoded payload (no payload if no key present)

046 + (2 * kuf) + (2 * kmf) + kl + iead + uad + tlvs

(pl + 7) / 8

 Contents of payload (pl is in bits) depending on the encrypted section key-wrapping method (value at offset 26):
Value at offset 26 Encrypted section key-wrapping method Meaning
X'00' No key-wrapping method. Only applies when key is clear (key material state (value at offset 8) is X'01'). Only the key material is in the payload. The key token is external or internal.
X'02' AESKW An encrypted AESKW payload which the Segment 2 code creates by wrapping the unencrypted AESKW formatted payload. The payload is made up of the integrity check value, pad length, length of hash options and hash, hash options, hash of the associated data, key material, and padding. The key token is external or internal.
X'03' PKOAEP2 An encrypted PKOAEP2 payload which the Segment 2 code creates using the RSAES-OAEP scheme of the PKCS #1 v2.1 standard. The message M is encoded for a given hash algorithm using the Bellare and Rogaway Optimal Asymmetric Encryption Padding (OAEP) method for encoding messages. For PKAOEP2, M is defined as follows:

M = [32 bytes: hAD] || [2 bytes: bit length of the clear key] || [clear key]

where hAD is the message digest of the associated data, and is calculated using the SHA-256 algorithm starting at offset 30 for the length in bytes of all the associated data for the key token (length value at offset 32). The encoded message is wrapped with an RSA public-key according to the standard. The key token is external.
End of optional clear key payload, wrapped AESKW formatted payload, or wrapped PKOAEP2 encoded payload
End of clear key, AESKW, or PKOAEP2 components
Note: All numbers are in big endian format.