AWS payment-cryptography documentation change
Summary
Added detailed documentation for exporting keys using ECDH asymmetric techniques, including key generation, certificate exchange, and key derivation processes
Security assessment
The change adds documentation about secure key exchange using ECDH cryptography, which is a security feature for establishing shared keys. However, there is no evidence of addressing a specific vulnerability or security incident.
Diff
diff --git a/payment-cryptography/latest/userguide/keys-export.md b/payment-cryptography/latest/userguide/keys-export.md index 08a99e3ed..a31241f3c 100644 --- a/payment-cryptography/latest/userguide/keys-export.md +++ b/payment-cryptography/latest/userguide/keys-export.md @@ -9 +9 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) -###### Topics +###### Contents @@ -11 +11 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) - * Export symmetric keys + * [Export symmetric keys](./keys-export.html#keys-export-symmetric) @@ -13 +13 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) - * Export DUKPT Initial Keys (IPEK/IK) + * [Export keys using asymmetric techniques (TR-34)](./keys-export.html#keys-export-tr34) @@ -15 +15 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) - * Export asymmetric (RSA) keys + * [Export keys using asymmetric techniques (ECDH)](./keys-export.html#keys-export-ecdh) @@ -16,0 +17 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) + * [Export keys using asymmetric techniques (RSA Wrap)](./keys-export.html#keys-export-rsawrap) @@ -17,0 +19 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) + * [Export symmetric keys using a pre-established key exchange key (TR-31)](./keys-export.html#keys-export-tr31) @@ -18,0 +21 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) + * [Export DUKPT Initial Keys (IPEK/IK)](./keys-export.html#keys-export-ipek) @@ -20,5 +23 @@ Export symmetric keysExport DUKPT Initial Keys (IPEK/IK)Export asymmetric (RSA) -## Export symmetric keys - -###### Important - -Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + * [Specify key block headers for export](./keys-export.html#keys-export-optionalheaders) @@ -26 +25 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade -###### Topics + * [Export asymmetric (RSA) keys](./keys-export.html#keys-export-publickey) @@ -28 +26,0 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade - * Export keys using asymmetric techniques (TR-34) @@ -30 +27,0 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade - * Export keys using asymmetric techniques (RSA Wrap) @@ -32 +28,0 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade - * Export symmetric keys using a pre-established key exchange key (TR-31) @@ -33,0 +30 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade +## Export symmetric keys @@ -34,0 +32 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade +###### Important @@ -35,0 +34 @@ Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade +Make sure you have the latest version of AWS CLI V2 before you begin. To upgrade, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). @@ -111,0 +111,127 @@ Call the **ExportKey** API with `KeyMaterialType` set to `TR34_KEY_BLOCK`. You n +### Export keys using asymmetric techniques (ECDH) + + + +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. + +When exporting, AWS Pricing Calculator is referred as Party U (Initiator) and the receiving system is known as Party V (Responder). + +###### Note + +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. + + 1. ###### **Generate ECC Key Pair** + +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`. + +###### Note + +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. + + $ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=ECC_NIST_P256,KeyUsage=TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT,KeyClass=ASYMMETRIC_KEY_PAIR,KeyModesOfUse='{DeriveKey=true}' --derive-key-usage "TR31_K1_KEY_BLOCK_PROTECTION_KEY" + + { + "Key": { + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv", + "KeyAttributes": { + "KeyUsage": "TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT", + "KeyClass": "ASYMMETRIC_KEY_PAIR", + "KeyAlgorithm": "ECC_NIST_P256", + "KeyModesOfUse": { + "Encrypt": false, + "Decrypt": false, + "Wrap": false, + "Unwrap": false, + "Generate": false, + "Sign": false, + "Verify": false, + "DeriveKey": true, + "NoRestrictions": false + } + }, + "KeyCheckValue": "2432827F", + "KeyCheckValueAlgorithm": "CMAC", + "Enabled": true, + "Exportable": true, + "KeyState": "CREATE_COMPLETE", + "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", + "CreateTimestamp": "2025-03-28T22:03:41.087000-07:00", + "UsageStartTimestamp": "2025-03-28T22:03:41.068000-07:00" + } + } + + 2. ###### **Get Public Key Certificate** + +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. + + $ aws payment-cryptography **get-public-key-certificate** \ + --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv + + + { + "KeyCertificate": "LS0tLS1CRUdJTi...", + "KeyCertificateChain": "LS0tLS1CRUdJT..." + } + + 3. ###### **Install public certificate on counter party system(PartyV)** + +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. + + 4. ###### **Generate ECC key pair on source system and provide certificate chain to AWS Payment Cryptography** + +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. + +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. + +Load the root certificate to AWS Payment Cryptography using the `importKey` command with KeyMaterialType of `RootCertificatePublicKey` and KeyUsageType of `TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE`. + +For intermediate certificates, use the `importKey` command with KeyMaterialType of `TrustedCertificatePublicKey` and KeyUsageType of `TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE`. Repeat this process for multiple intermediate certificates. Use the `KeyArn` of the last imported certificate in the chain as an input to subsequent export commands. + +###### Note + +Don't import the leaf certificate. Provide it directly during the export command. + + 5. ###### **Derive key and export key from AWS Pricing Calculator** + +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. + + $ aws payment-cryptography **export-key** \ + --export-key-identifier arn:aws:payment-cryptography:us-west-2:529027455495:key/e3a65davqhbpjm4h \ + --key-material='{ + "DiffieHellmanTr31KeyBlock": { + "CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/swseahwtq2oj6zi5", + "DerivationData": { + "SharedInformation": "ADEF567890" + }, + "DeriveKeyAlgorithm": "AES_256", + "KeyDerivationFunction": "NIST_SP800", + "KeyDerivationHashAlgorithm": "SHA_256", + "PrivateKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv", + "PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUR..." + } + }' + + { + "WrappedKey": { + "WrappedKeyMaterialFormat": "TR31_KEY_BLOCK", + "KeyMaterial": "D0112K1TB00E00007012724C0FAAF64DA50E2FF4F9A94DF50441143294E0E995DB2171554223EAA56D078C4CFCB1C112B33BBF05597EE700", + "KeyCheckValue": "E421AD", + "KeyCheckValueAlgorithm": "ANSI_X9_24" + } + } + + 6. ###### **Derive one-time key using ECDH on partyV HSM** + +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). + +###### Note + +The derivation parameters such as hash type must match exactly on both sides. Otherwise you will generate a different key + + 7. ###### **Import key to target system** + +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 + + + +