HMAC MAC variable-length symmetric key token

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

Table 1 shows the format of the HMAC MAC variable-length symmetric key-token. An HMAC token is used by the HMAC Generate(CSNBHMG) and HMAC Verify(CSNBHMV) verbs to generate and verify keyed hash Message Authentication Codes.

Table 1. HMAC MAC variable-length symmetric key-token, version X'05'
HMAC MAC variable-length symmetric key-token
Offset (bytes)	Length (bytes)	Description
Header
000	01	Token identifier: Value Meaning 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: 46 + (2 * kuf) + (2 * kmf) + kl + iead + uad + ((pl + 7) / 8) Key token Minimum token length (Release 4.1) Skeleton 46 + (2 * 2) + (2 * 2) + 0 + 0 + 0 + 0 = 54 Clear V0 payload 46 + (2 * 2) + (2 * 2) + 0 + 0 + 0 + ((80 + 7) / 8) = 64 Encrypted V0 payload 46 + (2 * 2) + (2 * 2) + 0 + 0 + 0 + ((448 + 7) / 8) = 110 Key token Minimum token length Skeleton 46 + (2 * 2) + (2 * 3) + 0 + 0 + 0 + 0 = 56 Clear V0 payload 46 + (2 * 2) + (2 * 3) + 0 + 0 + 0 + ((80 + 7) / 8) = 66 Encrypted V0 payload 46 + (2 * 2) + (2 * 3) + 0 + 0 + 0 + ((448 + 7) / 8) = 112 Key token Maximum token length External* 46 + (2 * 2) + (2 * 2) + 64 + 0 + 255 + ((8192 + 7) / 8) = 1397 Input 46 + (2 * 2) + (2 * 2) + 64 + 0 + 255 + ((2432 + 7) / 8) = 677 Key token Maximum token length External* 46 + (2 * 2) + (2 * 3) + 64 + 0 + 255 + ((8192 + 7) / 8) = 1399 Internal 46 + (2 * 2) + (2 * 3) + 64 + 0 + 255 + ((2432 + 7) / 8) = 679 *This assumes a PKOAEP2 key-wrapping method using a 8192-bit RSA transport key.
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. 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' KEK (8 leftmost bytes of SHA-256 hash: X'01 \|\| clear KEK). The key token is external. All unused values are reserved and undefined.
010	16	KVP (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.
026	01	Encrypted section key-wrapping method (how data in the encrypted section is protected): 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: Value Meaning 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). Value Meaning X'02' SHA-256 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. Value Meaning 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). Release 4.4 or later, otherwise undefined. Value Meaning X'00' V0 payload (V0PYLD). The payload format depends on the encrypted section key-wrapping method (value at offset 26): Value at offset 26 Meaning X'00' There is no key-wrapping method. When no key is present, there is no payload. When the key is clear, 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 will have the same V0 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 section and (2) optional clear key payload, wrapped AESKW formatted payload, or wrapped PKOAEP2 encoded payload (no payload if no key present)
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: 24 - 343 (Release 4.1); 26 - 345
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.
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, 80 - 4096. 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, pl can be 128, 192, or 256. 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 and the payload format version: 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	Algorithm type (algorithm for which the key can be used): Value Meaning X'03' HMAC All unused values are reserved and undefined.
042	02	Key type (general class of the key): Value Meaning X'0002' MAC All unused values are reserved and undefined.
044	01	Key usage fields count (kuf): 2. Key-usage field information defines restrictions on the use of the key. Refer to Figure 6. Each key-usage field is 2 bytes in length. The value in this field indicates how many 2-byte key usage fields follow.
045	01	Key-usage field 1, high-order byte (MAC operation): Value Meaning B'11xx xxxx' Key can be used for generate; key can be used for verify (GENERATE). B'10xx xxxx' Undefined or not used. B'01xx xxxx' Key cannot be used for generate; key can be used for verify (VERIFY). B'00xx xxxx' Undefined or not used. All unused bits are reserved and must be zero.
046	01	Key-usage field 1, low-order byte (user-defined extension control).
047	01	Key-usage field 2, high-order byte (hash method): Value Meaning B'1xxx xxxx' SHA-1 hash method is allowed for the key (SHA-1). B'0xxx xxxx' SHA-1 hash method is not allowed for the key. B'x1xx xxxx' SHA-224 hash method is allowed for the key (SHA-224). B'x0xx xxxx' SHA-224 hash method is not allowed for the key. B'xx1x xxxx' SHA-256 hash method is allowed for the key (SHA-256). B'xx0x xxxx' SHA-256 hash method is not allowed for the key. B'xxx1 xxxx' SHA-384 hash method is allowed for the key (SHA-384). B'xxx0 xxxx' SHA-384 hash method is not allowed for the key. B'xxxx 1xxx' SHA-512 hash method is allowed for the key (SHA-512). B'xxxx 0xxx' SHA-512 hash method is not allowed for the key. All unused bits are reserved and must be zero.
048	01	Key-usage field 2, low-order byte (reserved). All bits are reserved and must be zero.
049	01	Key management fields count (kmf): 3. Key-management field information describes how the data is to be managed or helps with management of the key material. Each key-management field is 2 bytes in length. The value in this field indicates how many 2-byte key management fields follow.
050	01	Key-management field 1, high-order byte (symmetric-key export control).
051	01	Key-management field 1, low-order byte (export control by algorithm).
052	01	Key-management field 2, high-order byte (key completeness).
053	01	Key-management field 2, low-order byte (security history).
054, for kuf > 2	01	Key-management field 3, high-order byte (pedigree original). Release 4.2 or later.
055, for kuf > 2	01	Key-management field 3, low-order byte (pedigree current).
050 + (2 * kmf)	kl	Optional key label.
050 + (2 * kmf) + kl	iead	Optional IBM extended associated data (unused).
050 + (2 kmf) + kl* + iead	uad	Optional user-defined associated data.
End of associated data section.
Optional clear key payload, wrapped AESKW formatted payload, or wrapped PKOAEP2 encoded payload (no payload if no key present)
050+ (2 * kmf) + kl + iead + uad	(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, that is, when key material state (value at offset 8) is X'01'.	Only the key material will be in the payload. The key token is external or internal.
		X'02'	AESKW	An encrypted 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 internal.
		X'03'	PKOAEP2	An encrypted PKOAEP2 encoded payload created 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.