AWS payment-cryptography documentation change
Summary
Expanded key import documentation to include ECDH key exchange, added ECC public key support, restructured content with detailed implementation steps, and updated TR-31 key usage references
Security assessment
Added documentation for ECDH key exchange method and ECC public key imports which are security-related features, but no evidence of addressing a specific vulnerability. Changes focus on expanding supported cryptographic methods rather than patching weaknesses.
Diff
diff --git a/payment-cryptography/latest/userguide/keys-import.md b/payment-cryptography/latest/userguide/keys-import.md index 44683a9a1..97d1794af 100644 --- a/payment-cryptography/latest/userguide/keys-import.md +++ b/payment-cryptography/latest/userguide/keys-import.md @@ -5 +5 @@ -Importing symmetric keysImport keys using asymmetric techniques (RSA Unwrap)Import symmetric keys using a pre-established key exchange key (TR-31)Importing asymmetric (RSA) keys +Importing symmetric keysImporting asymmetric (RSA, ECC) public keys @@ -13 +13 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m -###### Topics +###### Contents @@ -15 +15 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m - * Importing symmetric keys + * [Importing symmetric keys](./keys-import.html#keys-import-symmetric) @@ -17 +17 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m - * Import keys using asymmetric techniques (RSA Unwrap) + * [Import keys using asymmetric techniques (TR-34)](./keys-import.html#keys-import-tr34) @@ -19 +19 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m - * Import symmetric keys using a pre-established key exchange key (TR-31) + * [Import keys using asymmetric techniques (ECDH)](./keys-import.html#keys-import-ecdh) @@ -21 +21,9 @@ Examples require the latest version of the AWS CLI V2. Before getting started, m - * Importing asymmetric (RSA) keys + * [Import keys using asymmetric techniques (RSA Unwrap)](./keys-import.html#keys-import-rsaunwrap) + + * [Import symmetric keys using a pre-established key exchange key (TR-31)](./keys-import.html#keys-import-tr31) + + * [Importing asymmetric (RSA, ECC) public keys](./keys-import.html#keys-import-asymmetric) + + * [Importing RSA public keys](./keys-import.html#keys-import-rsapublickey) + + * [Importing ECC public keys](./keys-import.html#keys-import-eccpublickey) @@ -34 +42 @@ TR-34 uses RSA asymmetric cryptography to encrypt and sign symmetric keys for ex -To import your own keys, check out the AWS Payment Cryptography sample project on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export). For instructions on how to import/export keys from other platforms, review the sample code on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export/hsm/) or consult the user guide for those platforms. +To import your own keys, check out the AWS Payment Cryptography sample project on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export). For instructions on how to import/export keys from other platforms, sample code is available on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export/hsm/) or consult the user guide for those platforms. @@ -123 +131,152 @@ If the imported KeyUsage was TR31_K0_KEY_ENCRYPTION_KEY, you can use this key fo -## Import keys using asymmetric techniques (RSA Unwrap) +### Import 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 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. + +When importing, the sending system is commonly known as Party U (Initiator) and AWS Payment Cryptography is known as the Party V (Responder). + +###### Note + +While ECDH can be used to exchange any symmetric key type, it is the only approach that can securely transfer AES-256 keys. + + 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. For 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(PartyU)** + +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. + + 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 import commands. + +###### Note + +Don't import the leaf certificate. Provide it directly during the import command. + + 5. ###### **Derive one-time key using ECDH on partyU 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_ImportDiffieHellmanTr31KeyBlock.html). + +###### Note + +The derivation parameters such as hash type must match exactly on both sides. Otherwise you will generate a different key + + 6. ###### **Export key from source system** + +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. + + 7. ###### **Call Import Key** + +Call the importKey API with a KeyMaterialType of `TR34_KEY_BLOCK`. 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 import-token from step 1. + + $ aws payment-cryptography **import-key** \ + --key-material --key-material='{ + "DiffieHellmanTr31KeyBlock": { + "CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/swseahwtq2oj6zi5", + "DerivationData": { + "SharedInformation": "1234567890" + }, + "DeriveKeyAlgorithm": "AES_256", + "KeyDerivationFunction": "NIST_SP800", + "KeyDerivationHashAlgorithm": "SHA_256", + "PrivateKeyIdentifier": "", + "PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN....", + "WrappedKeyBlock": "D0112K1TB00E0000D603CCA8ACB71517906600FF8F0F195A38776A7190A0EF0024F088A5342DB98E2735084A7841CB00E16D373A70857E9A" + } + }' + + { + "Key": { + "CreateTimestamp": "2025-03-13T16:52:52.859000-04:00", + "Enabled": true, + "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza", + "KeyAttributes": { + "KeyAlgorithm": "TDES_3KEY", + "KeyClass": "SYMMETRIC_KEY", + "KeyModesOfUse": { + "Decrypt": true, + "DeriveKey": false, + "Encrypt": true, + "Generate": false, + "NoRestrictions": false, + "Sign": false, + "Unwrap": true, + "Verify": false, + "Wrap": true + }, + "KeyUsage": "TR31_K1_KEY_ENCRYPTION_KEY" + }, + "KeyCheckValue": "CB94A2", + "KeyCheckValueAlgorithm": "ANSI_X9_24", + "KeyOrigin": "EXTERNAL", + "KeyState": "CREATE_COMPLETE", + "UsageStartTimestamp": "2025-03-13T16:52:52.859000-04:00" + } + } + + 8. ###### **Use imported key for cryptographic operations or subsequent import** + +If the imported KeyUsage was TR31_K0_KEY_ENCRYPTION_KEY, you can use this key for subsequent key imports using TR-31. For other key types (such as TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY), you can use the key directly for cryptographic operations. + + + + +### Import keys using asymmetric techniques (RSA Unwrap) @@ -222 +381 @@ Call the **import-key** API with a `KeyMaterialType` of `KeyMaterial`. You need -If the imported `KeyUsage` was `TR31_K0_KEY_ENCRYPTION_KEY`, you can use this key for subsequent key imports using TR-31. If the key type was any other type (such as `TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY`), you can use the key directly for cryptographic operations. +If the imported `KeyUsage` was `TR31_K0_KEY_ENCRYPTION_KEY` or `TR31_K1_KEY_BLOCK_PROTECTION_KEY`, you can use this key for subsequent key imports using TR-31. If the key type was any other type (such as `TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY`), you can use the key directly for cryptographic operations. @@ -227 +386 @@ If the imported `KeyUsage` was `TR31_K0_KEY_ENCRYPTION_KEY`, you can use this ke -## Import symmetric keys using a pre-established key exchange key (TR-31) +### Import symmetric keys using a pre-established key exchange key (TR-31) @@ -290 +449,3 @@ When calling the **import-key** command, use the keyARN (or alias) of your key e -## Importing asymmetric (RSA) keys +## Importing asymmetric (RSA, ECC) public keys + +All certificates imported must be at least as strong as their issuing(predecessor) certificate in the chain. This means that a RSA_2048 CA can only be used to protect a RSA_2048 leaf certificate and an ECC certificate must be protected by another ECC certificate of equivalent strength. An ECC P384 certificate can only be issued by a P384 or P521 CA. All certificates must be unexpired at the time of import. @@ -340,5 +501 @@ Use the following command to import the root certificate: -You can now import a public key. There are two options for importing public keys: