AWS payment-cryptography documentation change
Summary
Added 'Common Headers' section detailing X9.143 key block headers and their validation requirements
Security assessment
The change adds documentation about cryptographic header validation and HMAC hash type handling, which relates to secure key management practices but does not indicate a specific security vulnerability being fixed. It enhances documentation of existing security controls.
Diff
diff --git a/payment-cryptography/latest/userguide/keys-export.md b/payment-cryptography/latest/userguide/keys-export.md index a102b4417..c058afe52 100644 --- a//payment-cryptography/latest/userguide/keys-export.md +++ b//payment-cryptography/latest/userguide/keys-export.md @@ -5 +5 @@ -Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) keys +Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Specify key block headers for exportExport asymmetric (RSA) keys @@ -24,0 +25,2 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) + * [Common Headers](./keys-export.html#keys-export-commonheaders) + @@ -441 +443 @@ The counter portion of the KSN (32 bits for AES DUKPT) isn't used for IPEK/IK de -### Specify key block headers for export +## Specify key block headers for export @@ -555,0 +558,29 @@ This is specifically allowed by the standards. +### Common Headers + +X9.143 defines certain headers for common use cases. With the exception of the HM(HMAC Hash) header, AWS Payment Cryptography does not parse or utilize these headers. + +Header Name | Purpose | Typical Validation | 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 + * 21 – SHA-256 + * 22 – SHA-384 + * 23 – SHA-512 + * 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 automatically populates this field on export and will parse it on import. Hash types not supported by the service such as SHAKE128 can be imported but may not be usuable for cryptographic functions. +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. +KP | [KCV](./terminology.html#terms.kcv) of the wrapping 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. | 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. +PB | Padding block | random printable ASCII characters | The service automatically populates this field on export to ensure optional headers are multiples of encryption block length +