適用於 Java 的 AWS SDK 1.x 已於 2025 年 12 月 31 日end-of-support。我們建議您遷移至 [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html)，以繼續接收新功能、可用性改善和安全性更新。

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

# Amazon S3 使用 AWS KMS 受管金鑰的用戶端加密
<a name="examples-crypto-kms"></a>

下列範例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 類別來建立已啟用用戶端加密的 Amazon S3 用戶端。設定完成後，任何使用此用戶端上傳到 Amazon S3 的物件都會加密。您從 Amazon S3 使用此用戶端取得的任何物件都會自動解密。

**注意**  
下列範例示範如何搭配 AWS KMS 受管金鑰使用 Amazon S3 用戶端加密。若要了解如何使用加密搭配您自己的金鑰，請參閱[Amazon S3 用戶端加密搭配用戶端主金鑰](examples-crypto-masterkey.md)。

啟用用戶端加密時，您可以選擇兩種 Amazon S3 加密模式：嚴格驗證或驗證。下列各節說明如何啟用每種類型。若要了解每個模式使用哪些演算法，請參閱 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定義。

## 必要的匯入
<a name="required-imports"></a>

匯入下列類別以取得這些範例。

 **匯入** 

```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.kms.AWSKMS;
import com.amazonaws.services.kms.AWSKMSClientBuilder;
import com.amazonaws.services.kms.model.GenerateDataKeyRequest;
import com.amazonaws.services.kms.model.GenerateDataKeyResult;
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
import com.amazonaws.services.s3.model.CryptoMode;
import com.amazonaws.services.s3.model.EncryptionMaterials;
import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider;
```

## 嚴格驗證加密
<a name="strict-authenticated-encryption-kms"></a>

如果`CryptoMode`未指定 ，嚴格驗證加密是預設模式。

若要明確啟用此模式，請在 `withCryptoConfiguration`方法中指定 `StrictAuthenticatedEncryption`值。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

 **Code** 

```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.US_WEST_2)
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
         .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
         .build();

s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```

在 Amazon S3 加密用戶端上呼叫 `putObject`方法以上傳物件。

 **Code** 

```
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
```

您可以使用相同的用戶端擷取物件。此範例會呼叫 `getObjectAsString`方法，以擷取存放的字串。

 **Code** 

```
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```

## 已驗證的加密模式
<a name="authenticated-encryption-kms"></a>

當您使用 `AuthenticatedEncryption` 模式時，會在加密期間套用改進的金鑰包裝演算法。在此模式下解密時，演算法可以驗證解密物件的完整性，並在檢查失敗時擲回例外狀況。如需驗證加密運作方式的詳細資訊，請參閱[Amazon S3 用戶端驗證加密](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)部落格文章。

**注意**  
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。

若要啟用此模式，請在 `withCryptoConfiguration`方法中指定 `AuthenticatedEncryption`值。

 **Code** 

```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
         .withRegion(Regions.US_WEST_2)
         .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
         .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
         .build();
```

## 設定 AWS KMS 用戶端
<a name="configure-kms"></a>

除非明確指定，否則 Amazon S3 加密用戶端預設會建立 AWS KMS 用戶端。

若要為此自動建立的 AWS KMS 用戶端設定區域，請設定 `awsKmsRegion`。

 **Code** 

```
Region kmsRegion = Region.getRegion(Regions.AP_NORTHEAST_1);

AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
        .withRegion(Regions.US_WEST_2)
        .withCryptoConfiguration(new CryptoConfigurationV2().withAwsKmsRegion(kmsRegion))
        .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
        .build();
```

或者，您可以使用自己的 AWS KMS 用戶端來初始化加密用戶端。

 **Code** 

```
AWSKMS kmsClient = AWSKMSClientBuilder.standard()
        .withRegion(Regions.US_WEST_2);
        .build();

AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
        .withRegion(Regions.US_WEST_2)
        .withKmsClient(kmsClient)
        .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
        .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
        .build();
```