适用于 Java 的 AWS SDK 1.x于2025年 end-of-support 12月31日达到。我们建议您迁移到 [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) 以继续获得新功能、可用性改进和安全更新。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Amazon S3 客户端加密
使用 Amazon S3 加密客户端加密数据是您可以用于为存储在 Amazon S3 中的敏感信息提供一层额外保护的一种方法。此部分中的示例演示如何为您的应用程序创建和配置 Amazon S3 加密客户端。
如果您不熟悉加密，请参阅《AWS KMS 开发人员指南》中的[加密基础知识](https://docs.aws.amazon.com/kms/latest/developerguide/crypto-intro.html)，大致了解加密术语和加密算法。要了解有关所有 AWS SDK 的加密支持信息，请参阅 Amazon Web Services 一般参考中的 [Amazon S3 客户端加密的 AWS SDK 支持](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html)。
**注意**
这些代码示例假定您了解[使用适用于 Java 的 AWS SDK](basics.md) 中的内容，并且已使用[设置用于开发的 AWS 凭证和区域](setup-credentials.md)中的信息配置默认 AWS 凭证。
如果您使用的是 1.11.836 或更低版本的适用于 Java 的 AWS SDK，请参阅 [Amazon S3 加密客户端迁移](s3-encryption-migration.md)，了解有关将应用程序迁移到更高版本的信息。如果您无法迁移，请参阅 GitHub 上的[此完整示例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java)。
如果您使用的是 1.11.837 或更高版本的适用于 Java 的 AWS SDK，请浏览下面列出的示例主题以使用 Amazon S3 客户端加密。
**Topics**
+ [Amazon S3 客户端加密配合客户端主密钥](examples-crypto-masterkey.md)
+ [Amazon S3 客户端加密配合 AWS KMS 托管密钥](examples-crypto-kms.md)
# Amazon S3 客户端加密配合客户端主密钥
以下示例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 类创建启用客户端加密的 Amazon S3 客户端。启用后，您使用此客户端上传到 Amazon S3 的任何对象都将加密。您使用此客户端从 Amazon S3 获取的任何对象都将自动解密。
**注意**
以下示例演示如何配合使用 Amazon S3 客户端加密和客户托管的客户端主密钥。要了解如何配合使用加密和 AWS KMS 托管密钥，请参阅 [Amazon S3 客户端加密配合 AWS 托管密钥](examples-crypto-kms.md)。
启用客户端 Amazon S3 加密时，您可以从两种加密模式中进行选择：经严格身份验证或经身份验证。以下部分说明了如何启用每种类型。要了解每种模式使用哪种算法，请参阅 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定义。
## 必需的导入
为这些示例导入以下类。
**导入**。
```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
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.StaticEncryptionMaterialsProvider;
```
## 经严格身份验证加密
如果未指定 `CryptoMode`，则默认模式为经严格身份验证加密。
要显式启用此模式，请在 `withCryptoConfiguration` 方法中指定 `StrictAuthenticatedEncryption` 值。
**注意**
要使用客户端经身份验证加密，您必须将最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 文件加入应用程序的类路径中。
**代码**
```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
.build();
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt");
```
## 经身份验证加密模式
使用 `AuthenticatedEncryption` 模式时，在加密期间会应用改进的密钥包装算法。在此模式下解密时，该算法会验证已解密对象的完整性，如果检查失败，则引发异常。有关经身份验证加密模式工作原理的更多详细信息，请参阅博客文章 [Amazon S3 Client-Side Authenticated Encryption](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)。
**注意**
要使用客户端经身份验证加密，您必须将最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 文件加入应用程序的类路径中。
要启用此模式，请在 `AuthenticatedEncryption` 方法中指定 `withCryptoConfiguration` 值。
**代码**
```
AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.DEFAULT_REGION)
.withClientConfiguration(new ClientConfiguration())
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption))
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
.build();
s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt");
```
# Amazon S3 客户端加密配合 AWS KMS 托管密钥
以下示例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 类创建启用客户端加密的 Amazon S3 客户端。配置后，您使用此客户端上传到 Amazon S3 的任何对象都将加密。您使用此客户端从 Amazon S3 获取的任何对象都将自动解密。
**注意**
以下示例演示如何将 Amazon S3 客户端加密和 AWS 托管密钥配合使用。要了解如何将加密与您自己的密钥配合使用，请参阅 [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) 定义。
## 必需的导入
为这些示例导入以下类。
**导入**。
```
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;
```
## 经严格身份验证加密
如果未指定 `CryptoMode`，则默认模式为经严格身份验证加密。
要显式启用此模式，请在 `withCryptoConfiguration` 方法中指定 `StrictAuthenticatedEncryption` 值。
**注意**
要使用客户端经身份验证加密，您必须将最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 文件加入应用程序的类路径中。
**代码**
```
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));
```
对 `putObject` 加密客户端调用 Amazon S3 方法以上传对象。
**代码**
```
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
```
您可以使用同一个客户端检索该对象。此示例调用 `getObjectAsString` 方法以检索存储的字符串。
**代码**
```
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```
## 经身份验证加密模式
使用 `AuthenticatedEncryption` 模式时，在加密期间会应用改进的密钥包装算法。在此模式下解密时，该算法会验证已解密对象的完整性，如果检查失败，则引发异常。有关经身份验证加密模式工作原理的更多详细信息，请参阅博客文章 [Amazon S3 Client-Side Authenticated Encryption](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)。
**注意**
要使用客户端经身份验证加密，您必须将最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 文件加入应用程序的类路径中。
要启用此模式，请在 `AuthenticatedEncryption` 方法中指定 `withCryptoConfiguration` 值。
**代码**
```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
.build();
```
## 配置 AWS KMS 客户端
除非明确指定了 AWS KMS 客户端，否则默认情况下，Amazon S3 加密客户端会创建一个该客户端。
要为这个自动创建的 AWS KMS 客户端设置区域，请设置 `awsKmsRegion`。
**代码**
```
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 客户端来初始化加密客户端。
**代码**
```
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();
```