TR-31 key block header

Edit online

A TR-31 key block always begins with a key block header consisting of a required 16-byte fixed-length portion followed by from 0 – 99 variable-length optional blocks. Table 1 shows the format of the required fixed-length portion of the header and shows only those values supported by CCA:

Table 1. Format and CCA supported values of the required header for a TR-31 key block
Offset (bytes)	Length (bytes)	TR-31 key block header field name
0	1	Key block version ID. Identifies the version of the key block, which defines the method by which it is cryptographically protected and the content and layout of the block. The allowed key block version ID values depend upon the *Key Context* value (offset 14 in KBH). Internal key blocks, those that have a `1` as the *Key Context* value, are limited to "B" and "D". The following key block version ID values defined by TR-31 are the only ones supported by CCA: ASCII Value Meaning "A" Key block protected by the Key Variant Binding Method 2005 Edition (maps to TR31 Translate rule-array keyword VARXOR-A). This method is deprecated and should not be used for any new development. "B" Key block protected by the Key Derivation Binding Method 2010 Edition (maps to TR31 Translate rule-array keyword VARDRV-B). "C" Key block protected by the Key Variant Binding Method 2010 Edition (maps to TR31 Translate rule-array keyword VARXOR-C). This method is only valid with T31X and is invalid with T31C. "D" Key block protected by the Key Derivation Binding Method 2017 Edition (maps to TR31 Translate rule-array keyword VARDRV-D.
1	4	Key block length. Provides the key-block length after encoding. Length includes the entire block (header + encrypted confidential data + MAC).
5 (1 of 13)	2	Key usage. Provides information about the intended function of the protected key/sensitive data. The following key usage values defined by TR-31 are the only ones supported by CCA: "B0", "B1", "B3" - see 5 (2 of 13) "C0" - see 5 (3 of 12) "D0", "D3" - see 5 (4 of 13) "E0", "E1", "E2", "E3", "E4", "E5" - see 5 (5 of 13) "F0", "F1", "F2", "F3", "F4" - see 5 (6 of 13) "K0", "K1", "K4" - see 5 (7 of 13) "M0", "M1", "M3", "M6", "M7" - see 5 (8 of 13) "P0" - see 5 (9 of 13) "V0", "V1", "V2" - see 5 (10-12 of 13) In addition, CCA supports the following proprietary key usage values: "10", "11", and "12" - see 5 (13 of 13) .
5 (2 of 13)	2	ASCII Value Meaning "B0" BDK base derivation key (maps to both TR31 Translate and TR31 Key Create rule-array keyword BDK). This key is used to derive the initial PIN encryption key (IPEK) in the derived unique key per transaction (DUKPT) process defined in X9.24-3. "B1" Initial DUKPT key (maps to both TR31 Translate and TR31 Key Create rule-array keyword DUKPT). This key is used as the initial PIN encryption key (IPEK) in the derived unique key per transaction (DUKPT) process as defined in X9.24-3. Only valid with TR-31 key usage ’"X". "B3" Key derivation key (maps to both TR31 Translate and TR31 Key Create rule-array keyword KDK). This key is used as an input to an irreversible key derivation function to derive other keys. Only valid with TR-31 key usage ’"X".
5 (3 of 13)	2	ASCII Value Meaning "C0" CVK card verification key (maps to both TR31 Translate and TR31 Key Create rule-array keyword CVK). These are the keys used for computing or verifying (against a supplied value) a card verification code with the CVV, CVC, CVC2, and CVV2 algorithms. In CCA, this corresponds to keys used with two algorithms: Visa CVV and MasterCard CVC codes are generated and verified using the CVV Generate and CVV Verify verbs. These verbs require a key type of DATA or MAC/MACVER with a subtype extension (CV bits 0 – 3) of ANY-MAC, single-length CVVKEY-A and single-length CVVKEY-B, and a double-length CVVKEY-A (see the CVV Key Combine verb). The MAC generate and MAC verify (CV bits 20 – 21) key usage values must be set appropriately. American Express CSC codes are generated and verified using the Transaction Validation verb. This verb requires a key type of MAC or MACVER with a subtype extension of ANY-MAC or AMEX-CSC. Note: CCA and TR-31 represent CVV keys differently. This makes representations between the two incompatible. CCA represents the key-A and key-B keys as two 8-byte (single length) keys, while TR-31 represents these keys as one 16-byte (double length) key. Current Visa standards now require one 16-byte key. The CVV Generate and CVV Verify verbs accept one 16-byte CVV key, using left and right key parts as key-A and key-B. See CVV Key Combine (CSNBCKC). This verb provides a way to combine two single-length MAC-capable keys into one double-length CVV key. Import and export of 8-byte CVVKEY-A and CVVKEY-B MAC/MACVER keys are only allowed using the IBM proprietary TR-31 key usage and mode of use values (ASCII "10" and "1", respectively) to indicate encapsulation of the IBM control vector in a TR-31 optional block since the 8-byte CVVKEY-A is meaningless and useless as a TR-31 "C0" key usage key of any mode of use. Security consideration: There is asymmetry in the translation from a CCA DATA key to a TR-31 key when using the TR31 Translate verb. The asymmetry results from CCA DATA keys having attributes of both data encryption and MAC keys, while TR-31 separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "C0" key, provided that one or both applicable MAC generate and MAC verify control vector bits are on. However, a TR-31 "C0" key cannot be imported to the lower-security CCA DATA key. It can only be imported to a CCA key type of MAC or MACVER. This restriction eliminates the ability to export a MAC or MACVER key to a TR-31 key and re-importing it back as a DATA key with the capability to encipher, decipher, or both. Since the translation from key usage "C0" is controlled by rule array keywords when using the TR31 Key Import verb, it is possible to convert an exported CCA CVVKEY-A or CVVKEY-B key into an AMEX-CSC key or the other way around. This can be restricted by not enabling offsets X'015A' (T31I Permit C0:G/C/V to TDES MAC/MACVER: CVVKEY-A) and X'015B' (T31I Permit C0:G/C/V to DES/TDES MAC/MACVER: AMEX-CSC) at the same time. However, if both CVVKEY-A and AMEX-CSC translation types are required, then offsets X'015A' and X'015B' must both be enabled in the active role. In this case, control is up to the development, deployment, and execution of the applications themselves.
5 (4 of 13)	2	ASCII Value Meaning "D0" Symmetric data encryption key (maps to both TR31 Translate and TR31 Key Create rule-array keyword ENC). Security consideration: There is asymmetry in the translation from a CCA DATA key to a TR-31 key. The asymmetry results from DATA keys having attributes of both data encryption and MAC keys, while TR-31 separates data encryption keys from MAC keys. A CCA DATA key can be exported to a TR-31 "D0" key, provided that one or both applicable Encipher or Decipher control vector bits are on. However, a TR-31 "D0" key cannot be imported to the lower-security CCA DATA key. It can only be imported to a CCA key type of ENCIPHER, DECIPHER, or CIPHER. This restriction eliminates the ability to export a CCA DATA key to a TR-31 key and re-importing it back as a CCA DATA key with the capability to MAC generate and MAC verify. "D3" Symmetric data encryption key for sensitive data (maps to both TR31 Translate and TR31 Key Create rule-array keyword ENCSENS).
5 (5 of 13)	2	ASCII Value Meaning "E0" Derivation key for an EMV/chip issuer master key: application cryptograms (maps to TR31 Translate rule-array keyword EMVACMK and TR31 Key Create rule-array keyword EMVAC-E). Note (also applies to key usage values "E1", "E2", "E3", "E4", and "E5"): EMV/chip issuer master keys are used by the chip cards (also called integrated circuit cards, IC cards, or smart cards) to perform cryptographic operations or, in some cases, to derive keys used to perform operations. In CCA, these are (1) diversified key-generating keys (DES key type DKYGENKY), allowing derivation of operational keys, or (2) operational keys. In this context, the term master key has a different meaning than a CCA master key. The master keys used in this context, also called KMCs, are described by EMV as DES master keys for personalization session keys. They are used to derive the corresponding chip card master keys and are not typically used directly for cryptographic operations other than key derivation. In CCA, these are usually key generating keys with derivation level DKYL1 (CV bits 12 – 14 = B’001’) used to derive other key generating keys (the chip card master keys). In some cases or for older EMV key derivation methods, the issuer master keys could be level DKYL0 (CV bits 12 – 14 = B’000’). "E1" Derivation key for an EMV/chip issuer master key: secure messaging for confidentiality (maps to TR31 Translate rule-array keyword EMVSCMK and TR31 Key Create rule-array keyword EMVSC-E). ”E2” Derivation key for an EMV/chip issuer master key: secure messaging for integrity (maps to TR31 Translate rule-array keyword EMVSIMK and TR31 Key Create rule-array keyword EMVSI-E). ”E3” Derivation key for an EMV/chip issuer master key: data authentication code (maps to TR31 Translate rule-array keyword EMVDAMK and TR31 Key Create rule-array keyword EMVDA-E). ”E4” Derivation key for an EMV/chip issuer master key: dynamic numbers (maps to TR31 Translate rule-array keyword EMVDNMK and TR31 Key Create rule-array keyword EMVDN-E). ”E5” Derivation key for an EMV/chip issuer master key: card personalization (maps to TR31 Translate rule-array keyword EMVCPMK and TR31 Key Create rule-array keyword EMVCP-E).
5 (6 of 13)	2	ASCII Value Meaning ”F0” Maps to both TR31 Translate and TR31 Key Create rule-array keyword EMVAC-F. ”F1” Maps to both TR31 Translate and TR31 Key Create rule-array keyword EMVSC-F. ”F2” Maps to both TR31 Translate and TR31 Key Create rule-array keyword EMVSI-F. ”F3” Maps to both TR31 Translate and TR31 Key Create rule-array keyword EMVDA-F. ”F4” Maps to both TR31 Translate and TR31 Key Create rule-array keyword EMVDN-F.
5 (7 of 13)	2	ASCII Value Meaning "K0" Key encryption or wrapping key (maps to both TR31 Translate and TR31 Key Create rule-array keyword KEK). Note (also applies to key usage values "K1" and "K4"): CCA mode support is the same for key block version IDs "B" and "C" due to the lack of distinction between TR-31 "K0" and "K1" in CCA keys. CCA does not distinguish between targeted protocols, so there is no good way to represent the difference. Also, most wrapping mechanisms now involve derivation or key variation steps. Security consideration (also applies to key usage values "K1" and "K4"): The CCA OKEYXLAT, EXPORTER, IKEYXLAT, or IMPORTER KEK translation to a TR-31 "K0" key usage with mode of use "B" (both wrap and unwrap) is not allowed for security reasons. Even with access-control point control, this capability would give an immediate path to turn a CCA EXPORTER key into a CCA IMPORTER key and the other way around. ”K1” TR-31 key block protection key (maps to both TR31 Translate and TR31 Key Create rule-array keyword KEK-WRAP). ”K4” ISO 20038 key block protection key (maps to both TR31 Translate and TR31 Key Create rule-array keyword KEK-WRK4).
5 (8 of 13)	2	ASCII Value Meaning "M0" ISO 16609 MAC algorithm 1 key (maps to both TR31 Translate and TR31 Key Create rule-array keyword ISOMAC0). Note (also applies to key usage "M1" and "M3"): "M0" and "M1" are identical except that "M0" does not support single-length (8-byte) DES keys while "M1" does. A CCA control vector has no bits defined to limit key usage by algorithm, such as CBC MAC (TR-31 usage "M0" and "M1") or X9.19 (TR-31 usage "M3"). When importing a TR-31 key block, the resulting CCA key-token deviates from the restrictions of usages "M0", "M1", and "M3". Importing a TR-31 key block which allows MAC generation ("G" or "C") results in a control vector with the ANY-MAC attribute rather than for the restricted algorithm that is set in the TR-31 key block. The ANY-MAC attribute provides the same restrictions as what CCA currently uses for generating and verifying MACs. Security consideration (also applies to key usage values "M1" and "M3"): There is asymmetry in the translation from aCCA DATA key to a TR-31 key. The asymmetry results from CCA DATA keys having attributes of both data encryption keys and MAC keys, while TR-31 separates data encryption keys from MAC keys. A CCA DATA key can be exported to key usage "M0", "M1", "M3" or, beginning with Release 5.4, "M6", provided that one or both applicable MAC generate and MAC verify control vector bits are on. However, a key with key usage "M0", "M1", "M3", or "M6" cannot be imported to the lower-security CCA DATA key. It can only be imported to a CCA key type of MAC or MACVER. This restriction eliminates the ability to export a CCA MAC or MACVER key to a TR-31 key and re-importing it back as a CCA DATA key with the capability to Encipher, Decipher, or both. "M1" ISO 9797-1 MAC algorithm 1 key (maps to both TR31 Translate and TR31 Key Create rule-array keyword ISOMAC1). "M3" ISO 9797-1 MAC algorithm 3 key (maps to both TR31 Translate and TR31 Key Create rule-array keyword ISOMAC3). "M6" ISO 9797-1:2011 MAC algorithm 5/CMAC key (maps to both TR31 Translate and TR31 Key Create rule-array keyword ISOMAC6). "M7" HMAC algorithm key (maps to TR31 Translate rule-array keyword HMAC and TR31 Key Create rule-array keyword KEY-HMAC).
5 (9 of 13)	2	ASCII Value Meaning "P0" PIN encryption key (maps to both TR31 Translate and TR31 Key Create rule-array keyword PINENC). Note: Mode of use "E" (TR31 Translate rule-array keyword ENC-ONLY) restricts PIN encryption keys to encrypting a PIN block and may be used to create or re-encipher an encrypted PIN block (for key-to-key translation). Mode of use "D" (TR31 Translate rule-array keyword DEC-ONLY) restricts PIN encryption keys to decrypting a PIN block and is generally used in a PIN translation to decrypt the incoming PIN block. Security consideration: It is highly recommended that TR31 Translate rule-array keyword INCL-CV be used when exporting a DES key with key type IPINENC or OPINENC. This ensures the original CCA attributes are restored when importing the TR-31 key block back into CCA.
5 (10 of 13)	2	ASCII Value Meaning "V0" PIN verification, KPV, other algorithm key (maps to both TR31 Translate and TR31 Key Create rule-array keyword PINVO). These keys are used to generate or verify a PIN using a PIN-calculation method for that key type. Key usage "V0" is intended to be a PIN-calculation method "other" than those defined for "V1" (TR31 Key Create and TR31 Translate rule-array keyword PINV3624) or "V2" (TR31 Key Create and TR31 Translate rule-array keyword VISAPVV). Because CCA does not have a PIN-calculation method of "other" defined, it maps key usage "V0" with the subtype extension of NO-SPEC (CV bits 0 – 3 = B’0000’). Be aware that NO-SPEC allows any method, including "V1" and "V2", and this mapping is suboptimal. Note (also applies to key usage "V1" and "V2"): Mode of use "N" (TR31 Translate rule-array keyword ANY) has no special restrictions other than restrictions implied by the key usage. This is used by several vendors for a PIN generation or PIN verification key when the key block version ID is "A". Mode of use "G" (TR31 Translate rule-array keyword GEN-ONLY) is used for a PINGEN key that may not perform a PIN verification. This is the only mode available when the control vector in the CCA key-token, which is applicable with IBM-proprietary mode of use "10" (TR31 Translate rule-array keyword INCL-CV), does not have the EPINVER control vector bit on. Key usage "C" (TR31 Translate rule-array keyword GENVER) is the only output mode available for TR-31 when any of the CCA key-token PIN generating bits are on in the control vector (CPINGENA, EPINGENA, EPINGEN, or CPINGENA) in addition to the EPINVER bit. Security consideration: It is highly recommended that TR31 Translate rule-array keyword INCL-CV be used when exporting a DES key with key type PINGEN or PINVER. This ensures the original CCA attributes are restored when importing the TR-31 key block back into CCA. TR-31 key blocks that are protected under legacy key block version ID "A" (TR31 Translate rule-array keyword VARXOR-A) use the same mode of use "N" (keyword ANY) for PINGEN and PINVER keys. For version ID "A" keys only, enabling both the PINGEN and PINVER access-control points at the same time in the active role while enabling offset X'01B0' (for mode "N") is NOT recommended. In other words, for this key usage, enabling the following four commands in the active role at the same time allows changing PINGEN keys into PINVER, and PINVER keys into PINGEN: Offset Command X’014D' T31X Permit Version A TR-31 Key Blocks X’01B0' T31X Permit DES/TDES PINGEN and DES/TDES PINVER to V0/V1/V2:N X’0194' T31X Permit DES/TDES PINGEN: NO-SPEC to V0:N/C X’0193' T31X Permit DES/TDES PINVER: NO-SPEC to V0:N/V
5 (11 of 13)	2	ASCII Value Meaning "V1" PIN verification, IBM 3624 key (maps to both TR31 Translate and TR31 Key Create rule-array keyword PINV3624). The note for key usage "V0" also applies to this key usage. Security consideration: It is highly recommended that CSBNT31X rule-array keyword INCL-CV be used when exporting a DES key with key type PINGEN or PINVER. This ensures the original CCA attributes are restored when importing the TR-31 key block back into CCA. TR-31 key blocks that are protected under legacy key block version ID "A" (TR31 Translate rule-array keyword VARXOR-A) use the same mode of use "N" (keyword ANY) for PINGEN and PINVER keys. For version ID "A" keys only, enabling both the PINGEN and PINVER access-control points at the same time in the active role while enabling offset X'01B0' (for mode "N") is NOT recommended. In other words, for this key usage, enabling the following four commands in the active role at the same time allows changing PINGEN keys into PINVER, and PINVER keys into PINGEN: Offset Command X’014D' T31X - Permit version A TR-31 key blocks X’01B0' T31X - Permit DES PINGEN to V0:N and DES PINVER to V1/V2:N X’0196' T31X - Permit DES PINGEN:NO-SPEC/IBM-PIN/IBM-PINO to V1 X’0195' T31X - Permit DES PINVER:NO-SPEC/IBM-PIN/IBM-PINO to V1 As defined by TR-31, numeric key block version IDs are reserved for proprietary key block definitions. Note: DK is an abbreviation for Die Deutsch Kreditwirtschaft, which is the German Banking Industry Committee (GBIC). A supported DK proprietary block always includes a 16-byte optional block that is valued to the following ASCII characters: `"KS10DE#GBIC#OPT1"`
5 (12 of 13)	2	ASCII Value Meaning "V2" PIN verification, Visa PVV key (maps to both TR31 Translate and TR31 Key Create rule-array keyword VISAPVV). The note for key usage "V0" also applies to this key usage. Security consideration: It is highly recommended that TR31 Translate rule-array keyword INCL-CV be used when exporting a DES key with key type PINGEN or PINVER. This ensures the original CCA attributes are restored when importing the TR-31 key block back into CCA. TR-31 key blocks that are protected under legacy key block version ID "A" (TR31 Translate rule-array keyword VARXOR-A) use the same mode of use "N" (keyword ANY) for PINGEN and PINVER keys. For version ID "A" keys only, enabling both the PINGEN and PINVER access-control points at the same time in the active role while enabling offset X'01B0' (for mode "N") is NOT recommended. In other words, for this key usage, enabling the following four commands in the active role at the same time allows changing PINGEN keys into PINVER, and PINVER keys into PINGEN: Offset Command X’014D' T31X Permit Version A TR-31 Key Blocks X’01B0' T31X Permit DES/TDES PINGEN and DES/TDES PINVER to V0/V1/V2:N X’0198' T31X Permit DES/TDES PINGEN: NO-SPEC/VISA-PVV to V2:N/C X’0197' T31X Permit DES/TDES PINVER: NO-SPEC/VISA-PVV to V2:N/V As defined by TR-31, numeric key block version IDs are reserved for proprietary key block definitions. Note: DK is an abbreviation for Die Deutsch Kreditwirtschaft, which is the German Banking Industry Committee (GBIC). A supported DK proprietary block always includes a 16-byte optional block that is valued to the following ASCII characters: `"KS10DE#GBIC#OPT1"`
5 (13 of 13)		The following proprietary key usage values are the only ones supported by CCA: ASCII Value Meaning "10" IBM proprietary key usage that indicates usage is based on the DES control vector contained in an IBM proprietary optional block with the format defined in Table 1 (maps to TR31 Translate rule-array keyword ATTR-CV). "10" DK proprietary key usage for key diversification key generating key (AES KDKGENKY), KDKTYPEB to "10" (Release 5.4 or later) (maps to TR31 Translate rule-array keyword TYPBTO10). "11" DK proprietary key usage for key diversification key generating key (AES KDKGENKY), KDKTYPEA to "11" (Release 5.4 or later) (maps to TR31 Translate rule-array keyword TYPATO11). "12" DK proprietary key usage for key diversified key generating key (DES DKYGENKY), DKYL0, and DMPIN (Release 5.4 or later) (maps to TR31 Translate rule-array keyword DMP0TO12).
7	1	Algorithm. The approved algorithm for which the protected key may be used. The following algorithm values defined by TR-31 are the only ones supported by CCA: ASCII Value Meaning "A" Advanced Encryption Standard (AES) (maps to TR31 Translate AES key in the source key-token). "D" Data Encryption Algorithm (DEA) (maps to TR31 Translate single-length DES key in the source key-token). "H" (ASC X9 TR 31-2018) Hash-based message authentication code (HMAC) (specify the underlying hash algorithm in optional field with a block ID of "HM") (Release 5.6 or later) (maps to TR31 Translate HMAC key in the source key-token). "H" (ISO 20038) HMAC-SHA-1 (maps to TR31 Translate HMAC key in the source key-token). "I" (ISO 20038) HMAC-SHA-2 (Release 5.6 or later) (maps to TR31 Translate HMAC key in the source key-token). "T" Triple Data Encryption Algorithm (TDEA) (maps to TR31 Translate double-length or, beginning with Release 5.4, triple-length Triple-DES key in the source key-token).
8	1	Mode of use. Defines the operation the protected key can perform. The following mode of use values defined by TR-31 are the only ones supported by CCA: ASCII Value Meaning "B" Both encrypt and decrypt data, wrap and unwrap keys (maps to TR31 Translate rule-array keyword ENCDEC). "C" Both generate and verify of check/PIN values (maps to TR31 Translate rule-array keyword GENVER). "D" Decrypt data, unwrap keys only (maps to TR31 Translate rule-array keyword DEC-ONLY). "E" Encrypt data, wrap keys only (maps to TR31 Translate rule-array keyword ENC-ONLY). "G" Generate of check/PIN values only (maps to TR31 Translate rule-array keyword GEN-ONLY). "N" No special restrictions (other than restrictions implied by the key usage) (maps to TR31 Translate rule-array keyword ANY). Not valid in TR31 Key Create. "V" Verify of check/PIN values only (maps to TR31 Translate rule-array keyword VER-ONLY). "X" Key used to derive other key(s) (maps to TR31 Translate rule-array keyword DERIVE). "1" IBM proprietary mode for keys (maps to TR31 Translate rule-array keyword ATTR-CV). Not valid in TR31 Key Create.
9	2	Key version number. Version number used to indicate that contents of the key block is a component, or to prevent reinjection of old keys.
11	1	Exportability. Defines whether the protected key may be transferred outside the cryptographic domain in which the key is found. The following exportability values defined by TR-31 are the only ones supported by CCA: ASCII Value Meaning "E" Extra sensitive: key exportable under a key-encrypting key meeting the requirements of X9.24 Parts 1 or 2; no ECB mode KEK allowed (maps to TR31 Translate rule-array keyword EXP-TRST). "N" Non-exportable (maps to TR31 Translate rule-array keyword EXP-NONE). "S" Sensitive: key exportable under any key-encrypting key not necessarily meeting the requirements of X9.24 Parts 1 or 2 (maps to TR31 Translate rule-array keyword EXP-ANY).
12	2	Number of optional blocks. Defines the number of optional blocks included in the key block. The minimum value is zero and the maximum is 99.
14	2	Key Context: Defines whether the key block is in a key exchange context (wrapped by a transport key) or in a storage context, for example, wrapped by the master file key (MFK). The Key Context. value does not require a certain Exportability setting. The values are: "0" This is the equivalent to external CCA key tokens, and the key can be used in either a key storage or a key exchange context. This enables interoperability with legacy key blocks. "1" This is the equivalent to internal CCA key tokens, and the key can be used in a key storage context only. The key block is internal and can be used as an operational key but not as a transport key. "2" This is the equivalent to external CCA key tokens, and the key can be used in a key exchange context only. The key block is wrapped by a transport key for exchange between a communicating pair.