AWS AmazonS3: S3 PQ-TLS guide: key exchange terms, defaults, CloudTrail check
Summary
Rewrites the Amazon S3 post-quantum TLS how-to: replaces 'cipher suites' with 'key exchange' terminology, updates the AWS CRT client example to v2.35.11, notes that hybrid PQ-TLS is now enabled by default (so postQuantumTlsEnabled(true) is a no-op), removes the outdated preview note, fixes a typo, and adds a new step 4 that verifies the negotiated key exchange (X25519MLKEM768 / SecP256r1MLKEM768) via the CloudTrail tlsDetails.keyExchange field with an AWS CLI example.
Security assessment
The diff is documentation-only for encryption in transit: it clarifies hybrid post-quantum key exchange (ECDH with ML-KEM), states that AWS CRT HTTP client v2.35.11+ enables hybrid PQ-TLS by default, and adds a CloudTrail-based verification step for the negotiated key exchange. No specific vulnerability, CVE, or incident is referenced, so it is not security_issue_related, but it does document a security feature and its audit/verification path.
Evidence
+A successful call doesn't show which key exchange the request used, because clients that prefer post-quantum TLS fall back to classical key exchange if the endpoint doesn't support it. To confirm, look up the `ListBuckets` event in AWS CloudTrail and check the `tlsDetails.keyExchange` field. A value of `X25519MLKEM768` or `SecP256r1MLKEM768` means that the request used hybrid post-quantum TLS. `ListBuckets` is a management event, so it appears in CloudTrail Event history within about 15 minutes, without a trail. For more information, see [Verifying hybrid post-quantum TLS with AWS CloudTrail](./UsingEncryptionInTransit.PQ-TLS.html#pqtls-verify).
Diff
diff --git a/AmazonS3/latest/userguide/pqtls-how-to.md b/AmazonS3/latest/userguide/pqtls-how-to.md index 9861a37..43fd4f8 100644 --- a//AmazonS3/latest/userguide/pqtls-how-to.md +++ b//AmazonS3/latest/userguide/pqtls-how-to.md @@ -11 +11 @@ Client configuration example: AWS SDK for Java 2 -To use PQ-TLS with Amazon S3, you need to configure your client to support post-quantum key exchange algorithms. Also ensure that your client supports the hybrid approach, which combines traditional elliptic curve cryptography with post-quantum algorithms like ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism). +To use PQ-TLS with Amazon S3, your client must support post-quantum key exchange algorithms. Also ensure that your client supports the hybrid approach, which combines traditional elliptic curve cryptography with post-quantum algorithms like ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism). @@ -13 +13 @@ To use PQ-TLS with Amazon S3, you need to configure your client to support post- -The specific configuration depends on your client library and programming language. For more information, see [Enabling hybrid post-quantum TLS](https://docs.aws.amazon.com/payment-cryptography/latest/userguide/pqtls-details.html). +The specific configuration depends on your client library and programming language. For other SDKs, tools, and platforms, see [Enabling hybrid post-quantum TLS](https://docs.aws.amazon.com/sdkref/latest/guide/pqtls-details.html) in the _AWS SDKs and Tools Reference Guide_. @@ -19,4 +18,0 @@ In this procedure, add a Maven dependency for the AWS Common Runtime HTTP Client -Note - -The AWS Common Runtime HTTP Client, which has been available as a preview, became generally available in February 2023. In that release, the `tlsCipherPreference` class and the `tlsCipherPreference()` method parameter are replaced by the `postQuantumTlsEnabled()` method parameter. If you were using this example during the preview, you need to update your code. - @@ -25 +21 @@ The AWS Common Runtime HTTP Client, which has been available as a preview, becam -For example, this statement adds version `2.30.22` of the AWS Common Runtime client to your Maven dependencies. +For example, this statement adds version `2.35.11` of the AWS Common Runtime client to your Maven dependencies. @@ -30 +26 @@ For example, this statement adds version `2.30.22` of the AWS Common Runtime cli - <version>2.30.22</version> + <version>2.35.11</version> @@ -33 +29 @@ For example, this statement adds version `2.30.22` of the AWS Common Runtime cli - 2. To enable the hybrid post-quantum cipher suites, add the AWS SDK for Java 2.x to your project and initialize it. Then enable the hybrid post-quantum cipher suites on your HTTP client as shown in the following example. + 2. To enable the hybrid post-quantum key exchange, add the AWS SDK for Java 2.x to your project and initialize it. Then enable it on your HTTP client as shown in the following example. @@ -35 +31 @@ For example, this statement adds version `2.30.22` of the AWS Common Runtime cli -This code uses the `postQuantumTlsEnabled()` method parameter to configure an [AWS common runtime HTTP client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-crt.html) that prefers the recommended hybrid post-quantum cipher suite, ECDH with ML-KEM. Then it uses the configured HTTP client to build an instance of the Amazon S3 asynchronous client, [`S3AsyncClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html). After this code completes, all [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/) requests on the `S3AsyncClient` instance use hybrid post-quantum TLS. +This code uses the `postQuantumTlsEnabled()` method parameter to configure an [AWS common runtime HTTP client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-crt.html) that prefers the recommended hybrid post-quantum key exchange, ECDH with ML-KEM. Then it uses the configured HTTP client to build an instance of the Amazon S3 asynchronous client, [`S3AsyncClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html). After this code completes, all [Amazon S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/) requests on the `S3AsyncClient` instance use hybrid post-quantum TLS when the endpoint supports it. @@ -39 +35 @@ Important -As of v2.35.11, callers no longer need to set `.postQuantumTlsEnabled(true)` to enable hybrid post-quantum TLS for your client. All versions newer than v2.35.11 enable post-quantum TLS by default. +Starting with version 2.35.11, the AWS CRT HTTP client enables hybrid post-quantum TLS by default, so you don't need to call `.postQuantumTlsEnabled(true)`. Setting it, as in the following example, has no effect on these versions but makes the behavior explicit. @@ -55 +51,18 @@ When you call Amazon S3 API operations on the configured Amazon S3 client, your - ListBucketsResponse reponse = s3Async.listBuckets(); + ListBucketsResponse response = s3Async.listBuckets().join(); + + 4. Confirm that the request used hybrid post-quantum TLS. + +A successful call doesn't show which key exchange the request used, because clients that prefer post-quantum TLS fall back to classical key exchange if the endpoint doesn't support it. To confirm, look up the `ListBuckets` event in AWS CloudTrail and check the `tlsDetails.keyExchange` field. A value of `X25519MLKEM768` or `SecP256r1MLKEM768` means that the request used hybrid post-quantum TLS. `ListBuckets` is a management event, so it appears in CloudTrail Event history within about 15 minutes, without a trail. For more information, see [Verifying hybrid post-quantum TLS with AWS CloudTrail](./UsingEncryptionInTransit.PQ-TLS.html#pqtls-verify). + +The following AWS CLI command lists recent `ListBuckets` events with their key exchange. Replace the Region with the Region of your S3 client, and the start time with a time shortly before your test. + + aws cloudtrail lookup-events \ + --region us-east-2 \ + --lookup-attributes AttributeKey=EventName,AttributeValue=ListBuckets \ + --start-time 2026-11-17T14:25:00Z \ + --query 'Events[].CloudTrailEvent' --output text \ + | jq -c '{eventTime, userAgent, keyExchange: .tlsDetails.keyExchange}' + +Example output: + + {"eventTime":"2026-11-17T14:28:24Z","userAgent":"aws-cli/2.40.1 ...","keyExchange":"X25519MLKEM768"} @@ -62 +75 @@ When you call Amazon S3 API operations on the configured Amazon S3 client, your -Consider running the following tests with hybrid cipher suites on your applications that call Amazon S3. +Consider running the following tests with hybrid key exchange on your applications that call Amazon S3. @@ -64 +77 @@ Consider running the following tests with hybrid cipher suites on your applicati - * Run load tests and benchmarks. The hybrid cipher suites perform differently than traditional key exchange algorithms. You might need to adjust your connection timeouts to allow for the longer handshake times. If you’re running inside an AWS Lambda function, extend the execution timeout setting. + * Run load tests and benchmarks. The hybrid key exchange performs differently than traditional key exchange algorithms. You might need to adjust your connection timeouts to allow for the longer handshake times. If you’re running inside an AWS Lambda function, extend the execution timeout setting. @@ -66 +79 @@ Consider running the following tests with hybrid cipher suites on your applicati - * Try connecting from different locations. Depending on the network path your request takes, you might discover that intermediate hosts, proxies, or firewalls with deep packet inspection (DPI) block the request. This might result from using the new cipher suites in the [ClientHello](https://tools.ietf.org/html/rfc5246#section-7.4.1.2) part of the TLS handshake, or from the larger key exchange messages. If you have trouble resolving these issues, work with your security team or IT administrators to update the relevant configuration and unblock the new TLS cipher suites. + * Try connecting from different locations. Depending on the network path your request takes, you might discover that intermediate hosts, proxies, or firewalls with deep packet inspection (DPI) block the request. This might result from using the new key exchange groups in the [ClientHello](https://tools.ietf.org/html/rfc5246#section-7.4.1.2) part of the TLS handshake, or from the larger key exchange messages. If you have trouble resolving these issues, work with your security team or IT administrators to update the relevant configuration and unblock the new TLS key exchange groups.