AWS payment-cryptography high security documentation change
Summary
Clarified ECDH key exchange process, corrected API parameter names (e.g., 'signing-key-certificate' to 'public-key-certificate'), emphasized key strength requirements, and improved documentation accuracy.
Security assessment
The correction of the API parameter from 'signing-key-certificate' to 'public-key-certificate' addresses a potential misconfiguration that could lead to using incorrect certificates during key imports, which might compromise secure key exchange. Additionally, clarifying that the wrapping key must be 'at least as strong' as the exported key enforces cryptographic best practices to prevent weak key usage.
Diff
diff --git a/payment-cryptography/latest/userguide/keys-import.md b/payment-cryptography/latest/userguide/keys-import.md index 665a92ec4..a74800b46 100644 --- a//payment-cryptography/latest/userguide/keys-import.md +++ b//payment-cryptography/latest/userguide/keys-import.md @@ -135 +135 @@ If the imported KeyUsage was TR31_K0_KEY_ENCRYPTION_KEY, you can use this key fo -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, 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 actual key that you want to transfer, which could be another KBPK, an IPEK key, or other key types. @@ -137 +137 @@ ECDH uses ECC asymmetric cryptography to establish a joint key between two parti -When importing, the sending system is commonly known as Party U (Initiator) and AWS Payment Cryptography is known as the Party V (Responder). +When importing, the sending system is commonly known as Party U (Initiator) and AWS Payment Cryptography is known as Party V (Responder). @@ -145 +145 @@ While ECDH can be used to exchange any symmetric key type, it is the only approa -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. For 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`. @@ -149 +149 @@ 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. @@ -185 +185 @@ 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. @@ -198 +198 @@ 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 export 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 export keys using it. This could include the entire certificate chain or just the root certificate from step 1, depending on the HSM. Consult your HSM documentation for more information. @@ -202 +202 @@ 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. @@ -204 +204 @@ 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. @@ -214 +214 @@ Don't import the leaf certificate. Provide it directly during the import command - 5. ###### **Derive one-time key using ECDH on partyU HSM** + 5. ###### **Derive one-time key using ECDH on Party U HSM** @@ -216 +216 @@ Don't import the leaf certificate. Provide it directly during the import command -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_ImportDiffieHellmanTr31KeyBlock.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_ImportDiffieHellmanTr31KeyBlock.html). @@ -220 +220 @@ 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. @@ -224 +224 @@ The derivation parameters such as hash type must match exactly on both sides. Ot -Finally, you'll want to export the key you wish to transport to AWS Payment Cryptography using standard TR-31 commands. You will specify the ECDH derived key as the KBPK. 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. +Finally, export the key you want to transport to AWS Payment Cryptography using standard TR-31 commands. Specify the ECDH derived key as the KBPK. 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. @@ -228 +228 @@ Finally, you'll want to export the key you wish to transport to AWS Payment Cryp -Call the importKey API with a KeyMaterialType of `DiffieHellmanTr31KeyBlock`. Use the keyARN of the last CA imported in step 3 for `certificate-authority-public-key-identifier`, the wrapped key material from step 4 for `key-material`, and the leaf certificate from step 3 for `signing-key-certificate`. Include the private key arn from step 1. +Call the `import-key` API with a KeyMaterialType of `DiffieHellmanTr31KeyBlock`. Use the KeyARN of the last CA imported in step 3 for `certificate-authority-public-key-identifier`, the wrapped key material from step 4 for `key-material`, and the leaf certificate from step 3 for `public-key-certificate`. Include the private key ARN from step 1.