View a markdown version of this page

在適用於 Java 的 開發套件中使用 TLS - AWS SDK for Java 2.x
檢查 TLS 版本強制執行 TLS 版本遷移至 TLS 1.2

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在適用於 Java 的 開發套件中使用 TLS

適用於 Java 的 AWS SDK 使用其基礎 Java 平台的 TLS 功能。在本主題中，我們會示範使用 Amazon Corretto 17 所用 OpenJDK 實作的範例。

若要使用 AWS 服務，基礎 JDK 必須支援最低版本的 TLS 1.2，但建議使用 TLS 1.3。

TLS 1.3 是啟用量子後密碼編譯的先決條件，可能需要額外的動作或組態。若要進一步了解，請參閱啟用混合式後量子 TLS。

使用者應參閱其與 SDK 搭配使用的 Java 平台文件，以了解預設啟用哪些 TLS 版本，以及如何啟用和停用特定 TLS 版本。

如何檢查 TLS 版本資訊

使用 OpenJDK，下列程式碼顯示使用 SSLContext 來列印支援的 TLS/SSL 版本。

System.out.println(Arrays.toString(SSLContext.getDefault().getSupportedSSLParameters().getProtocols()));

例如，Amazon Corretto 17 (OpenJDK) 會產生下列輸出。

[TLSv1.3, TLSv1.2, TLSv1.1, TLSv1, SSLv3, SSLv2Hello]

要查看運作中的 SSL 交握和使用的 TLS 版本，您可以使用系統屬性 javax.net.debug。

例如，執行使用 TLS 的 Java 應用程式。

java app.jar -Djavax.net.debug=ssl:handshake

應用程式會記錄 SSL 交握，如下所示。

...
javax.net.ssl|DEBUG|10|main|2022-12-23 13:53:12.221 EST|ClientHello.java:641|Produced ClientHello handshake message (
"ClientHello": {
  "client version"      : "TLSv1.2",

...
javax.net.ssl|DEBUG|10|main|2022-12-23 13:53:12.295 EST|ServerHello.java:888|Consuming ServerHello handshake message (
"ServerHello": {
  "server version"      : "TLSv1.2",
...
AWS CRT HTTP 用戶端 TLS 偵錯

如果您使用 AWS CRT HTTP 用戶端，上述範例中顯示的 Java TLS 偵錯屬性不會有任何效果，因為 CRT 使用自己的 TLS 堆疊。若要使用 CRT HTTP 用戶端檢查網路層級請求詳細資訊，請啟用線路記錄。如需詳細資訊，請參閱啟用線路記錄。

強制執行最低 TLS 版本

適用於 Java 的 SDK 一律偏好平台和服務支援的最新 TLS 版本。強制執行特定最低 TLS 版本的方法取決於您使用的 HTTP 用戶端。

對於使用 Java TLS 堆疊的 Apache、Netty 和 URL Connection HTTP 用戶端，請使用系統屬性 jdk.tls.client.protocols。例如，若要針對 SDK 服務用戶端強制執行 TLS 1.3，請提供下列系統屬性。

java -Djdk.tls.client.protocols=TLSv1.3 -jar app.jar

如需設定 TLS 版本的詳細資訊，請參閱 Java 平台的文件。

對於使用自己的 TLS 堆疊的 AWS CRT HTTP 用戶端，jdk.tls.client.protocols系統屬性沒有效果。反之，請使用minTlsVersion建置器選項來強制執行最低 TLS 版本。

TlsVersion 列舉 (software.amazon.awssdk.http.crt.TlsVersion) 提供下列值：

TLS_1_3

強制執行 TLS 1.3 作為最低版本。

SYSTEM_DEFAULT

使用平台的預設 TLS 版本交涉行為。

下列範例會建立同步 AWS CRT HTTP 用戶端，強制執行 TLS 1.3 作為最低版本。

import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.TlsVersion;

AwsCrtHttpClient httpClient = AwsCrtHttpClient.builder()
        .minTlsVersion(TlsVersion.TLS_1_3)
        .build();

下列範例會建立非同步 AWS CRT HTTP 用戶端，強制執行 TLS 1.3 作為最低版本。

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.TlsVersion;

AwsCrtAsyncHttpClient asyncHttpClient = AwsCrtAsyncHttpClient.builder()
        .minTlsVersion(TlsVersion.TLS_1_3)
        .build();

然後，您可以將設定的 HTTP 用戶端傳遞給 AWS 服務用戶端。

import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.TlsVersion;

S3Client s3Client = S3Client.builder()
        .httpClientBuilder(AwsCrtHttpClient.builder()
                .minTlsVersion(TlsVersion.TLS_1_3))
        .build();
TLS 1.3 的 macOS 需求

Apple Secure Transport 是預設的 macOS CRT TLS 後端，不支援 TLS 1.3。若要TlsVersion.TLS_1_3在 macOS 上使用 ，您必須先將環境變數AWS_CRT_USE_NON_FIPS_TLS_13設定為非空白值，才能啟動應用程式。這會將 CRT 切換到其 s2n-tls 後端。

使用此環境變數時，請注意下列考量事項：

  • s2n-tls 後端未經 FIPS 驗證。

  • s2n-tls 後端未與 macOS Keychain 整合。

如果您未在 macOS 上設定此環境變數，第一個請求會失敗並出現 CRT 端錯誤。

使用後量子 TLS 設定進行互斥

您無法postQuantumTlsEnabled(false)與 合併minTlsVersion(TlsVersion.TLS_1_3)。這些選項在 CRT TLS 內容中互斥。如果您同時指定兩者，建置器會擲回 IllegalStateException。

AWS API 端點升級至 TLS 1.2

如需移至 TLS 1.2 的最低版本之 AWS API 端點的相關資訊，請參閱此部落格文章。