View a markdown version of this page

Key block optional headers - AWS Payment Cryptography

Key block optional headers

This topic describes the optional headers you can include in a TR-31 key block and how AWS Payment Cryptography processes each one. Understanding how the service handles these headers helps you avoid key block import failures and stay compatible with receiving systems. These headers apply to key blocks for both import and export. The following table lists commonly used headers and isn't exhaustive. X9.143 defines certain headers for common use cases. With the exception of the HM (HMAC hash) and PB (padding block) headers, which have specific purposes and meanings, AWS Payment Cryptography accepts and ignores any header you include and doesn't change its processing based on its value. It doesn't parse or validate these headers on import, including when you pass a TR-31 key block as a dynamic key. The TR-31 message authentication code (MAC) authenticates the entire key block, so a block wrapped under a different KBPK fails regardless of its header values. Some systems and HSMs don't accept unknown headers, so don't add a header unless the receiving side has asked for it.

Header Name Purpose Expected format Notes

BI

Base Derivation Key Identifier for DUKPT

2 hex characters (00 for TDES, 11 for AES) then 10 hex characters for TDES KSI or 8 hex characters for BDK ID (AES DUKPT).

Contains the (BDK ID, for AES DUKPT) or the Key Set Identifier (KSI, for TDES DUKPT). Can be used when exchanging the BDK ID or the KSI, but do not need to exchange the other data contained in the IK and KS blocks. Typically BI is used when transmitting to a KIF whereas IK or KS are used when injecting into the terminal itself.

HM

Specifies the hash type for HMAC operations

  • 10 – SHA-1

  • 20 – SHA-224 (supported)

  • 21 – SHA-256 (supported)

  • 22 – SHA-384 (supported)

  • 23 – SHA-512 (supported)

  • 24 – SHA-512/224

  • 25 – SHA-512/256

  • 30 – SHA3-224

  • 31 – SHA3-256

  • 32 – SHA3-384

  • 33 – SHA3-512

  • 40 – SHAKE128

  • 41 – SHAKE256

The service sets this field automatically on export and parses it on import. HM is the one optional header that AWS Payment Cryptography uses during cryptographic operations. AWS Payment Cryptography supports HMAC only with SHA-224, SHA-256, SHA-384, and SHA-512. If the HM value indicates any other hash, you can import the key block, but you can't use the key for cryptographic operations. These other hashes include SHA-1, SHA-512/224, SHA-512/256, the SHA3 family, SHAKE128, and SHAKE256.

IK

Initial Key Serial Number for AES DUKPT

16 hex characters

This value is used to instantiate the use of the Initial DUKPT key on the receiving device and it identifies the Initial Key derived from a BDK. This field typically contains the derivation data but no counter. Use KS for TDES DUKPT.

KS

Initial Key Serial Number for TDES DUKPT

20 hex characters

This value is used to instantiate the use of the Initial DUKPT key on the receiving device and it identifies the Initial Key derived from a BDK. This field typically contains the derivation data + a zeroized counter value. Use IK for AES DUKPT.

KC

Key check value of the wrapped key

2 hex characters represent the KCV method (00 for X9.24 method and 01 for CMAC method). Followed by KCV value which is typically 6 hex characters. For example 010FA329 represents KCV of 0FA329 calculated using 01(CMAC) method.

ANSI X9.24-1-2017 Annex A defines how to compute this key check value (see section 6.3.6.7). The KCV supports key validation, not integrity checking.

You can validate KC only after the import completes. Because the KCV is bound into the key block, it almost always matches. Checking it programmatically adds little value.

KC is most useful when you handle key blocks manually, because it gives a human-readable indication of which key a block contains. On export, AWS Payment Cryptography doesn't add KC automatically. To add it, use the optional headers feature.

KP

Key check value of the KBPK

2 hex characters represent the KCV method (00 for X9.24 method and 01 for CMAC method). Followed by KCV value which is typically 6 hex characters. For example 010FA329 represents KCV of 0FA329 calculated using 01(CMAC) method.

The KP value is computed according to ANSI X9.24-1-2017 Annex A and is informational. AWS Payment Cryptography doesn't validate it on import. On export, the service doesn't add it automatically. To add it, use the optional headers feature.

You can optionally use KP in two ways. First, to identify a wrapping-key mismatch before import, parse the KP value from the header and compare it with the KCV of the KBPK. This step is optional, because the service returns an error if a block is wrapped under the wrong KBPK. Second, use KP to reference the KBPK by alias, for example alias/KCV. Because KCVs are short, they aren't unique across large numbers of keys. Plan for duplicate matches when you look up a key this way.

PB

Padding block

random printable ASCII characters

The padding block is mandatory. The sending side sets this value so that the payload is the correct length (a multiple of the encryption block length). For export, AWS Payment Cryptography appends this value automatically.