AWS payment-cryptography documentation change

Service: payment-cryptography · 2025-11-16 · Documentation low

File: payment-cryptography/latest/userguide/keys-import.md

Summary

Added introduction section explaining key import processes and header retention policies

Security assessment

The change documents key exchange methodologies and header handling during imports, which are security-related processes, but there is no evidence of addressing a specific vulnerability. It improves transparency about existing security features without indicating any resolved issues.

Diff

diff --git a/payment-cryptography/latest/userguide/keys-import.md b/payment-cryptography/latest/userguide/keys-import.md
index 9c8536812..3097eebc2 100644
--- a//payment-cryptography/latest/userguide/keys-import.md
+++ b//payment-cryptography/latest/userguide/keys-import.md
@@ -5 +5 @@
-Importing symmetric keysImporting asymmetric (RSA, ECC) public keys
+Introduction to importing keysImporting symmetric keysImporting asymmetric (RSA, ECC) public keys
@@ -14,0 +15,2 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m
+  * [Introduction to importing keys](./keys-import.html#keys-import-introduction)
+
@@ -33,0 +36,10 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m
+## Introduction to importing keys
+
+###### Note
+
+When importing keys using X9.143, TR-31 or TR-34 key blocks, AWS Payment Cryptography typically retains (but does not utilize) any optional headers. The HM(HMAC hash type) header is used during cryptographic operations. The KP header (KCV of wrapping key) is specific to the import process and is not retained. 
+
+When exchanging keys with a counterparty, it is typically to first exchange a key exchange key (KEK). This key will then be used to protect subsequent keys. Using electronic formats, the KEK may be exchanged use asymmetric techniques such as TR-34, ECDH or RSA wrap. Subsequent keys will be exchanged using a symmetric key exchange such as TR-31. This KEK will be long lived and may only be updated every few years based on policy and its defined crypto period. 
+
+If only one or two keys are being exchanged, you may also chose to use asymmetric techniques to directly exchange that key such as a BDK. AWS Payment Cryptography supports both methods of key exchange.
+