Variable-length symmetric key token

The following table presents the presents the format for a variable-length symmetric key token. The length of the token depends on the key type and algorithm.

Table 1. Variable-length symmetric key token
Offset (Dec)	Length of Field (Bytes)	Description
		Header
0	1	Token flag X'00' for null tokens X'01' for internal tokens X'02' for external tokens
1	1	Reserved (X'00')
2	2	Length of the token in bytes
4	1	Token version number X'05' (May be X'00' for null tokens)
5	3	Reserved (X'000000')
		Wrapping information
8	1	Key material state. X'00' no key present (internal or external) X'01' key is clear (internal) X'02' key is encrypted under a key-encrypting key (external) X'03' key is encrypted under the master key (internal)
9	1	Key verification pattern (KVP) type. X'00' No KVP X'01' AES master key verification pattern X'02' key-encrypting key verification pattern
10	16	Verification pattern of the key used to wrap the payload. Value is left justified.
26	1	Wrapping method - This value indicates the wrapping method used to protect the data in the encrypted section. X'00' key is in the clear X'02' AESKW X'03' PKOAEP2
27	1	Hash algorithm used in wrapping algorithm. For wrapping method X'00' X'00' None. For clear key tokens. For wrapping method X'02' X'02' SHA-256 For wrapping method X'03' X'01' SHA-1 X'02' SHA-256 X'04' SHA-384 X'08' SHA-512
28	1	Payload version X'00' Variable-length payload X'01' Fixed-length payload All other values are reserved and must not be used.
29	1	Reserved (X'00')
		Associated data section
30	1	Associated data version (X'01')
31	1	Reserved (X'00')
32	2	Length of the associated data in bytes: adl
34	1	Length of the key name in bytes: kl
35	1	Length of the IBM extended associated data in bytes: iead
36	1	Length of the installation-definable associated data in bytes: uad
37	1	Reserved (X'00')
38	2	Length of the payload in bits: pl
40	1	Reserved (X'00')
41	1	Type of algorithm for which the key can be used X'01' DES X'02' AES X'03' HMAC
42	2	Key type: For algorithm AES: X'0001' CIPHER X'0002' MAC X'0003' EXPORTER X'0004' IMPORTER X'0005' PINPROT X'0006' PINCALC X'0007' PINPRW X'0009' DKYGENKY For algorithm HMAC: X'0002' MAC For algorithm DES: X'0008' DESUSECV
44	1	Key-usage field count (kuf) - (1 byte) Key-usage field information defines restrictions on the use of the key.
45	kuf * 2	Key-usage fields (kuf * 2 bytes) For HMAC algorithm keys, refer to Table 3. For AES algorithm Key-Encrypting keys (Exporter or Importer), refer to Table 9. For AES algorithm Cipher keys, refer to Table 10. For AES algorithm MAC keys, refer to Table 4. For AES algorithm PINCALC keys, refer to Table 5. For AES algorithm PINPROT keys, refer to Table 6. For AES algorithm PINPRW keys, refer to Table 7. For AES algorithm DKYGENKY keys, refer to Table 8. For DESUSECV keys, refer to Table 2
45 + kuf * 2	1	Key-management field count (kmf) - (2 byte): For AES and HMAC keys: 2 (no pedigree information) or 3 (has pedigree information) For DESUSECV keys: 1 Key-management field information describes how the data is to be managed or helps with management of the key material.
46 + kuf * 2	kuf * 2	Key-management fields (kmf * 2 bytes): For AES and HMAC algorithm keys, refer to Table 11 For DESUSECV keys, refer to Table 12
46 + kuf * 2 + kmf * 2	kl	Key name
46 + kuf * 2 + kmf * 2 + kl	iead	IBM extended associated data
46 + kuf * 2 + kmf * 2 + kl + iead	uad	Installation-defined associated data
		Clear key or encrypted payload
30 + adl	(pl+7)/8	Encrypted AESKW payload (internal keys): The encrypted AESKW payload is created from the unencrypted AESKW payload which is made up of the ICV/pad length/hash options and hash length/hash options/hash of the associated data/key material/padding. See unencrypted AESKW payload below. Encrypted PKOAEP2 payload (external keys): The encrypted PKOAEP2 payload is created using the PKCS #1 v1.2 encoding method for a given hash algorithm. The message (M) inside the encoding contains: [2 bytes: bit length of key] \|\| [clear HMAC key]. M is encoded using OAEP and then encrypted with an RSA public key according to the standard. Clear key payload: When the key is clear, only the key material will be in the payload padded to the nearest byte with binary zeros.

Table 2. DESUSECV key-usage fields
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 1
45	2	Key-usage field 1 High-order byte: B'0000 0000' Reserved All unused bits are reserved and must be zero. Low-order byte: B'0000 0000' Reserved All unused bits are reserved and must be zero.

Table 3. HMAC algorithm key-usage fields
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 2
45	2	Key-usage field 1 High-order byte: 1xxx xxxx Key can be used for generate. x1xx xxxx Key can be used for verify. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: 1xxx xxxx SHA-1 hash method is allowed for the key. x1xx xxxx SHA-224 hash method is allowed for the key. xx1x xxxx SHA-256 hash method is allowed for the key. xxx1 xxxx SHA-384 hash method is allowed for the key. xxxx 1xxx SHA-512 hash method is allowed for the key. All unused bits are reserved and must be zero. Low-order byte: All bits are reserved and must be zero.

Table 4. AES algorithm MAC key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 2 – 3 Count is based on whether the key is DK enabled or not: kuf DK enabled 2 No 3 Yes
45	2	Key-usage field 1 High-order byte: B'00xx xxxx' Undefined. B'01xx xxxx' Key cannot be used for generate; key can be used for verify. B'10xx xxxx' Key can be used for generate; key cannot be used for verify. B'11xx xxx' Key can be used for generate and verify. Not valid if offset 50 is X'01'. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu* are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: X'01' CMAC mode. All unused bits are reserved and must be zero. Low-order byte: All bits are reserved and must be zero.
49	2	Key-usage field 3 High-order byte when DK enabled: X'01' PIN_OP (DKPINOP) X'03' PIN_ADMIN1 (DKPINAD1) X'04' PIN_ADMIN2 (DKPINAD2) All unused values are reserved and must not be used. Low-order byte: X'01' DK enabled. All unused values are reserved and must not be used.

Table 5. AES algorithm PINCALC key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 3
45	2	Key-usage field 1 High-order byte: B'00xx xxxx' Undefined. B'10xx xxxx' Key can be used for generate; key cannot be used for verify. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: X'00' Key can be used for Cipher Block Chaining (CBC). All unused values are reserved and must not be used. Low-order byte: All bits are reserved and must be zero.
49	2	Key-usage field 3 High-order byte when DK enabled: X'01' PIN_OP (DKPINOP) All unused values are reserved and must not be used. Low-order byte: X'01' DK enabled. All unused values are reserved and must not be used.

Table 6. AES algorithm PINPROT key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 3
45	2	Key-usage field 1 High-order byte: B'00xx xxxx' Undefined. B'01xx xxxx' Key cannot be used for encryption; key can be used for decryption. B'10xx xxxx' Key can be used for encryption; key cannot be used for decryption. B'11xx xxxx' Undefined. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: X'00' Key can be used for Cipher Block Chaining (CBC). All unused values are reserved and must not be used. Low-order byte: All bits are reserved and must be zero.
49	2	Key-usage field 3 High-order byte when DK enabled: X'01' PIN_OP (DKPINOP) X'02' PIN_OPP (DKPINOPP) X'03' PIN_ADMIN1 (DKPINAD1) All unused values are reserved and must not be used. Low-order byte: X'01' DK enabled. All unused values are reserved and must not be used.

Table 7. AES algorithm PINPRW key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 3
45	2	Key-usage field 1 High-order byte: B'00xx xxxx' Undefined. B'01xx xxxx' Key cannot be used for generate; key can be used for verify. B'10xx xxxx' Key can be used for generate; key cannot be used for verify. B'11xx xxxx' Undefined. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: X'01' CMAC mode All unused values are reserved and must not be used. Low-order byte: All bits are reserved and must be zero.
49	2	Key-usage field 3 High-order byte when DK enabled: X'01' PIN_OP (DKPINOP) All unused values are reserved and must not be used. Low-order byte: X'01' DK enabled. All unused values are reserved and must not be used.

Table 8. AES algorithm DKYGENKY key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 2, 4, 5, or 6
45	2	Key-usage field 1 High-order byte: Defines the key type to be generated. X'00' Any type listed below (D-ALL) X'01' CIPHER (D-CIPHER) X'02' MAC (D-MAC) X'03' EXPORTER (D-EXP) X'04' IMPORTER (D-IMP) X'05' PINPROT (D-PPROT) X'06' PINCALC (D-PCALC) X'07' PINPRW (D-PPRW) All other values are reserved and undefined. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2: Indicates the key usage. High-order byte (key-usage field level of control): B'1xxx xxxx' The key usage fields of the key to be generated must be equal (KUF-MBE) to the related generated key usage fields that start with key usage field 3 below. B'0xxx xxxx' The key usage fields of the key identifier to be generated must be permitted (KUF-MBP) based on the related generated-key usage fields that start with key usage field 3 below. A key to be diversified is not permitted to have a higher level of usage than the related key usage fields permit. The key to be diversified is only permitted to have key usage that is less than or equal to the related key usage fields. The UDX-ONLY bit of the related key usage fields must always be equal in both the generating key and the generated key. Undefined when the value at offset 45 = X'00' (D-ALL). All other values are reserved and undefined. Low-order byte (key-derivation sequence level): X'00' DKYL0. Generate a key based on the key usage byte at offset 45. All other values are reserved and undefined.
49 (if defined)	2	Key-usage field 3 (related generated key usage fields): These values determine allowable key usage of key to be generated. Meaning depends on value of offset 45: X'01' Same as key-usage field 1 of AES CIPHER key. X'02' Same as key-usage field 1 of AES MAC key. X'03' Same as key-usage field 1 of AES EXPORTER key. X'04' Same as key-usage field 1 of AES IMPORTER key. X'05' Same as key-usage field 1 of AES PINPROT key. X'06' Same as key-usage field 1 of AES PINCALC key. X'07' Same as key-usage field 1 of AES PINPRW key.
51 (if defined)	2	Key-usage field 4 (related generated key usage fields): These values determine allowable key usage of key to be generated. Meaning depends on value of offset 45: X'01' Same as key-usage field 2 of AES CIPHER key. X'02' Same as key-usage field 2 of AES MAC key. X'03' Same as key-usage field 2 of AES EXPORTER key. X'04' Same as key-usage field 2 of AES IMPORTER key. X'05' Same as key-usage field 2 of AES PINPROT key. X'06' Same as key-usage field 2 of AES PINCALC key. X'07' Same as key-usage field 2 of AES PINPRW key.
53 (if defined)	2	Key-usage field 5 (related generated key usage fields): These values determine allowable key usage of key to be generated. Meaning depends on value of offset 45: X'02' Same as key-usage field 3 of AES MAC key. X'03' Same as key-usage field 3 of AES EXPORTER key. X'04' Same as key-usage field 3 of AES IMPORTER key. X'05' Same as key-usage field 3 of AES PINPROT key. X'06' Same as key-usage field 3 of AES PINCALC key. X'07' Same as key-usage field 3 of AES PINPRW key.
55 (if defined)	2	Key-usage field 6 (related generated key usage fields): These values determine allowable key usage of key to be generated. Meaning depends on value of offset 45: X'03' Same as key-usage field 4 of AES EXPORTER key. X'04' Same as key-usage field 4 of AES IMPORTER key.

Table 9. AES algorithm KEK key-usage fields
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 4
45	2	Key-usage field 1 High-order byte for EXPORTER: 1xxx xxxx Key can be used for EXPORT. x1xx xxxx Key can be used for TRANSLAT. xx1x xxxx Key can be used for GENERATE-OPEX. xxx1 xxxx Key can be used for GENERATE-IMEX. xxxx 1xxx Key can be used for GENERATE-EXEX. xxxx x1xx Key can be used for GENERATE-PUB. All unused bits are reserved and must be zero. High-order byte for IMPORTER: 1xxx xxxx Key can be used for IMPORT. x1xx xxxx Key can be used for TRANSLAT. xx1x xxxx Key can be used for GENERATE-OPIM. xxx1 xxxx Key can be used for GENERATE-IMEX. xxxx 1xxx Key can be used for GENERATE-IMIM. xxxx x1xx Key can be used for GENERATE-PUB. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: 1xxx xxxx Key can wrap a TR-31 key. All unused bits are reserved and must be zero. Low-order byte: xxxx xxx1 This KEK can export a key in RAW format. All unused bits are reserved and must be zero
49	2	Key-usage field 3 High-order byte: 1xxx xxxx Key can wrap DES keys x1xx xxxx Key can wrap AES keys xx1x xxxx Key can wrap HMAC keys xxx1 xxxx Key can wrap RSA keys xxxx 1xxx Key can wrap ECC keys All unused bits are reserved and must be zero. Low-order byte: All bits are reserved and must be zero.
51	2	Key-usage field 4 High-order byte: 1xxx xxxx Key can wrap DATA class keys x1xx xxxx Key can wrap KEK class keys xx1x xxxx Key can wrap PIN class keys xxx1 xxxx Key can wrap DERIVATION class keys xxxx 1xxx Key can wrap CARD class keys xxxx x1xx Key can wrap CVAR class keys All unused bits are reserved and must be zero. Low-order byte: All bits are reserved and must be zero.

Table 10. AES algorithm Cipher Key associated data
Offset (Dec)	Length of Field (Bytes)	Description
44	1	Key-usage field count (kuf): 2
45	2	Key-usage field 1 High-order byte: 1xxx xxxx Key can be used for encryption. x1xx xxxx Key can be used for decryption. xx1x xxxx Key can be used for cipher text translate only. All unused bits are reserved and must be zero. Low-order byte: xxxx 1xxx The key can only be used in UDXs (used in KGN, KIM, KEX). xxxx 0xxx The key can be used in both UDXs and CCA. xxxx xuuu Reserved for UDXs, where uuu are UDX-defined bits. All unused bits are reserved and must be zero.
47	2	Key-usage field 2 High-order byte: X'00' Key can be used for Cipher Block Chaining (CBC). X'01' Key can be used for Electronic Code Book (ECB). X'02' Key can be used for Cipher Feedback (CFB). X'03' Key can be used for Output Feedback (OFB). X'04' Key can be used for Galois/Counter Mode (GCM) X'05' Key can be used for XEX-based Tweaked CodeBook Mode with CipherText Stealing (XTS) All unused values are reserved and must not be used. Low-order byte: All bits are reserved and must be zero.

Table 11. AES and HMAC algorithm key-management fields
Offset (Dec)	Length of Field (Bytes)	Description
48	2	Key-management field 1 High-order byte: 1xxx xxxx Allow export using symmetric key. x1xx xxxx Allow export using unauthenticated asymmetric key. xx1x xxxx Allow export using authenticated asymmetric key. xxx1 xxxx Allow export in RAW format. All other bits are reserved and must be zero. Low-order byte: --symmetric-- 1xxx xxxx Prohibit export using DES key. x1xx xxxx Prohibit export using AES key. --asymmetric-- xxxx 1xxx Prohibit export using RSA key. All other bits are reserved and must be zero.
48 + kuf * 2	2	Key-management field 2 High-order byte: 11xx xxxx Key, if present, is incomplete. Key requires at least 2 more parts. 10xx xxxx Key, if present, is incomplete. Key requires at least 1 more part. 01xx xxxx Key, if present, is incomplete. Key can be completed or have more parts added. 00xx xxxx Key, if present, is complete. No more parts can be added. All other bits are reserved and must be zero. Low-order byte (Security History): xxx1 xxxx Key was encrypted with an untrusted KEK. xxxx 1xxx Key was in a format without type/usage attributes. xxxx x1xx Key was encrypted with key weaker than itself. xxxx xx1x Key was in a non-CCA format. xxxx xxx1 Key was encrypted in ECB mode. All other bits are reserved and must be zero.
50 + kuf * 2	2	Key-management field 3 - Pedigree (this field may or may not be present) Indicates how key was originally created and how it got into the current system. High-order byte: Pedigree Original X'00' Unknown (Key Token Build2, Key Translate2) X'01' Other - method other than those defined here, probably used in UDX X'02' Randomly Generated (Key Generate2) X'03' Established by key agreement (ECC Diffie-Hellman) X'04' Created from cleartext key components (Key Part Import2) X'05' Entered as a cleartext key value (Key Part Import2, Secure Key Import2) X'06' Derived from another key X'07' Cleartext keys or key parts that were entered at TKE and secured from there to the target card (operational key load) All unused values are reserved and undefined.
50 + kuf * 2 (cont’d)	2 (cont’d)	X'00' Unknown (Key Token Build2) X'01' Other - method other than those defined here, probably used in UDX X'02' Randomly Generated (Key Generate2) X'03' Established by key agreement (ECC Diffie-Hellman) X'04' Created from cleartext key components (Key Part Import2) X'05' Entered as a cleartext key value (Key Part Import2, Secure Key Import2) X'06' Derived from another key X'07' Imported from a CCA 05 variable length token with pedigree field (Symmetric Key Import2) X'08' Imported from a CCA 05 variable length token with no pedigree field (Symmetric Key Import2) X'09' Imported from a CCA token that had a CV X'0A' Imported from a CCA token that had no CV or a zero CV X'0B' Imported from a TR-31 key block that contained a CCA CV (ATTR-CV option) (TR-31 Import) X'0C' Imported from a TR-31 key block that did not contain a CCA CV (TR-31 Import) X'0D' Imported using PKCS 1.2 RSA encryption (Symmetric Key Import2) X'0E' Imported using PKCS OAEP encryption (Symmetric Key Import2) X'0F' Imported using PKA92 RSA encryption (Symmetric Key Import2) X'10' Imported using RSA ZERO-PAD encryption (Symmetric Key Import2) X'11' Converted from a CCA token that had a CV (Key Translate2) X'12' Converted from a CCA token that had no CV or a zero CV (Key Translate2) X'13' Cleartext keys or key parts that were entered at TKE and secured from there to the target card (operational key load) X'14' Exported from a CCA 05 variable length token with pedigree field (Symmetric Key Export) X'15' Exported from a CCA 05 variable length token with no pedigree field (Symmetric Key Export) X'16' Exported using PKCS OAEP encryption (Symmetric Key Export) All unused values are reserved and undefined.

Table 12. DESUSECV key-management fields
Offset (Dec)	Length of Field (Bytes)	Description
47	1	Key-management field count (kmf): 1
48	2	Key-management field 1 High-order byte: B'0000 0000' Reserved All unused bits are reserved and must be zero. Low-order byte: B'0000 0000' Reserved All unused bits are reserved and must be zero.