AWS payment-cryptography documentation change
Summary
Clarified ECDH key exchange process, fixed grammatical errors, improved certificate description accuracy, and updated terminology consistency
Security assessment
Changes focus on improving clarity and accuracy of existing ECDH key exchange documentation rather than addressing security vulnerabilities. While ECDH is a security mechanism, the modifications are editorial improvements (e.g., changing 'joint key' to 'shared key', fixing certificate chain description) without introducing new security controls or addressing specific vulnerabilities. The clarification about wrapping key strength requirements maintains existing security best practices but doesn't represent new security documentation.
Diff
diff --git a/payment-cryptography/latest/userguide/keys-export.md b/payment-cryptography/latest/userguide/keys-export.md index 1162c9ee6..d49a85b91 100644 --- a//payment-cryptography/latest/userguide/keys-export.md +++ b//payment-cryptography/latest/userguide/keys-export.md @@ -115 +115 @@ Call the **ExportKey** API with `KeyMaterialType` set to `TR34_KEY_BLOCK`. You n -ECDH uses ECC asymmetric cryptography to establish a joint key between two parties and does not rely on pre-exchanged keys. ECDH keys are intended to be ephemeral, so AWS Payment Cryptography does not store them. In this process a one-time [KBPK/KEK](./terminology.html#terms.kbpk) is established(derived) using ECDH. That derived key is immediately used to wrap the actual key that you wish to transfer, which could be another KBPK, a BDK, an IPEK key, etc. +Elliptic Curve Diffie-Hellman (ECDH) uses ECC asymmetric cryptography to establish a shared key between two parties without requiring pre-exchanged keys. ECDH keys are ephemeral, so AWS Payment Cryptography does not store them. In this process, a one-time [KBPK/KEK](./terminology.html#terms.kbpk) is derived using ECDH. That derived key is immediately used to wrap the key you want to transfer, which could be another KBPK, a BDK, an IPEK key, or other key types. @@ -117 +117 @@ ECDH uses ECC asymmetric cryptography to establish a joint key between two parti -When exporting, AWS Pricing Calculator is referred as Party U (Initiator) and the receiving system is known as Party V (Responder). +When exporting, AWS Pricing Calculator is referred to as Party U (Initiator) and the receiving system is known as Party V (Responder). @@ -121 +121 @@ When exporting, AWS Pricing Calculator is referred as Party U (Initiator) and th -ECDH can be used to exchange any symmetric key type, but is the only approach that can be used to transfer AES-256 keys if a KEK is not already established. +ECDH can be used to exchange any symmetric key type, but it is the only approach that can be used to transfer AES-256 keys if a KEK is not already established. @@ -125 +125 @@ ECDH can be used to exchange any symmetric key type, but is the only approach th -Call `create-key` to create an ECC key pair that will be used for this process. This API generates a key pair for key imports or exports. At creation, you will specify what kind of keys can be derived using this ECC key. When using ECDH to exchange (wrap) other keys, use a value of `TR31_K1_KEY_BLOCK_PROTECTION_KEY`. +Call `create-key` to create an ECC key pair for this process. This API generates a key pair for key imports or exports. At creation, specify what kind of keys can be derived using this ECC key. When using ECDH to exchange (wrap) other keys, use a value of `TR31_K1_KEY_BLOCK_PROTECTION_KEY`. @@ -129 +129 @@ Call `create-key` to create an ECC key pair that will be used for this process. -Although low-level ECDH generates a derived key that can be used for any purpose (or multiple purposes), AWS Payment Cryptography limits the accidental re-use of a key for multiple purposes by allowing a key to only be used for a single derived-key type. +Although low-level ECDH generates a derived key that can be used for any purpose, AWS Payment Cryptography limits the accidental reuse of a key for multiple purposes by allowing a key to only be used for a single derived-key type. @@ -165 +165 @@ Although low-level ECDH generates a derived key that can be used for any purpose -Call `get-public-key-certificate` to receive the public key as an X.509 certificate since by your account's CA that is specific to AWS Payment Cryptography in a specific region. +Call `get-public-key-certificate` to receive the public key as an X.509 certificate signed by your account's CA that is specific to AWS Payment Cryptography in a specific region. @@ -178 +178 @@ Call `get-public-key-certificate` to receive the public key as an X.509 certific -With many HSMs, you need to install, load, or trust the public certificate generated in step 1 to establish keys using it. This could include the entire certificate chain or just the root certificate from step 1, depending on the HSM. Consult your manual for more information. +With many HSMs, you need to install, load, or trust the public certificate generated in step 1 to establish keys. This could include the entire certificate chain or just the root certificate, depending on the HSM. Consult your HSM documentation for specific instructions. @@ -182 +182 @@ With many HSMs, you need to install, load, or trust the public certificate gener -In ECDH, each parties generate a key pair and agree on a common key. For AWS Payment Cryptography to the derived key, it will need the counterparties public key in X.509 public key format. +In ECDH, each party generates a key pair and agrees on a common key. For AWS Payment Cryptography to derive the key, it needs the counterparty's public key in X.509 public key format. @@ -184 +184 @@ In ECDH, each parties generate a key pair and agree on a common key. For AWS Pay -When transferring keys from an HSM, create a key pair on that HSM. For HSMs that support keyblocks, the key header will look similar to this one `D0144K3EX00E0000`. When creating the certificate, you will generally generate a CSR on the HSM and then the HSM, a third party, or a service such as AWS Private CA can generate the certificate. +When transferring keys from an HSM, create a key pair on that HSM. For HSMs that support key blocks, the key header will look similar to `D0144K3EX00E0000`. When creating the certificate, you generally generate a CSR on the HSM, and then the HSM, a third party, or a service such as AWS Private CA can generate the certificate. @@ -196 +196 @@ Don't import the leaf certificate. Provide it directly during the export command -When exporting, the service derives a key using ECDH and then immediately utilizes it as the [KBPK](./terminology.html#terms.kbpk) to wrap the key to export using TR-31. The key to be exported can be any TDES or AES key subject to TR-31 valid combinations and as long as the wrapping key is as strong if not stronger than the key to be exported. +When exporting, the service derives a key using ECDH and then immediately uses it as the [KBPK](./terminology.html#terms.kbpk) to wrap the key to export using TR-31. The key to be exported can be any TDES or AES key subject to TR-31 valid combinations, as long as the wrapping key is at least as strong as the key to be exported. @@ -223 +223 @@ When exporting, the service derives a key using ECDH and then immediately utiliz - 6. ###### **Derive one-time key using ECDH on partyV HSM** + 6. ###### **Derive one-time key using ECDH on Party V HSM** @@ -225 +225 @@ When exporting, the service derives a key using ECDH and then immediately utiliz -Many HSMs and related systems support establishing keys using ECDH. Specify the public key from step 1 as the public key and the key from step 3 as the private key. For allowable options, such as derivation methods, please see the [API guide](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ExportDiffieHellmanTr31KeyBlock.html). +Many HSMs and related systems support establishing keys using ECDH. Specify the public key from step 1 as the public key and the key from step 3 as the private key. For allowable options, such as derivation methods, see the [API guide](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ExportDiffieHellmanTr31KeyBlock.html). @@ -229 +229 @@ Many HSMs and related systems support establishing keys using ECDH. Specify the -The derivation parameters such as hash type must match exactly on both sides. Otherwise you will generate a different key +The derivation parameters such as hash type must match exactly on both sides. Otherwise, you will generate a different key. @@ -233 +233 @@ The derivation parameters such as hash type must match exactly on both sides. Ot -Finally, you'll want to import the key from AWS Payment Cryptography using standard TR-31 commands. You will specify the ECDH derived key as the KBPK and the TR-31 keyblock is the one that was previously exported from AWS Payment Cryptography +Finally, import the key from AWS Payment Cryptography using standard TR-31 commands. Specify the ECDH derived key as the KBPK and use the TR-31 key block that was previously exported from AWS Payment Cryptography.