自2024年7月31日起， AWS SDK for Java 1.x已进入维护模式，并将于2025年12月31日end-of-support上线。我们建议您迁移到AWS SDK for Java 2.x以继续接收新功能、可用性改进和安全更新。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon S3 加密客户端迁移

本主题介绍如何将应用程序从 () 加密客户端的版本 1 (V1) 迁移到版本 2 Amazon Simple Storage Service (Amazon S3 V2)，并确保应用程序在整个迁移过程中的可用性。

先决条件

Amazon S3 客户端加密需要以下内容：

迁移概述

此迁移分为两个阶段：

更新现有客户端以读取新格式

V2 加密客户端使用旧版本 AWS SDK for Java 不支持的加密算法。

迁移的第一步是更新您的 V1 加密客户端，使其使用版本 1.11.837 或更高版本的 AWS SDK for Java。（我们建议您更新到最新发行版本，您可以在 Java API 参考版本 1.x 中找到该版本。） 为此，请更新项目配置中的依赖项。更新项目配置后，重新构建项目并重新部署。

完成这些步骤后，应用程序的 V1 加密客户端将能够读取 V2 加密客户端写入的对象。

更新项目配置中的依赖项

修改项目配置文件（例如 pom.xml 或 build.gradle）以使用版本 1.11.837 或更高版本的 AWS SDK for Java。然后重新构建项目并重新部署。

在部署新的应用程序代码之前完成此步骤，有助于确保整个实例集在迁移过程中的加密和解密操作保持一致。

使用 Maven 的 示例

pom.xml 文件中的代码段：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>
      <version>1.11.837</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

使用 Gradle 的示例

build.gradle 文件中的代码段：

dependencies {
  implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
  implementation 'com.amazonaws:aws-java-sdk-s3'
}

将加密和解密客户端迁移到 V2

将项目更新为最新SDK版本后，您可以修改应用程序代码以使用 V2 客户端。为此，请先更新您的代码以使用新的服务客户端生成器。然后在该生成器上使用已重命名的方法提供加密材料，并根据需要进一步配置您的服务客户端。

这些代码片段演示了如何使用客户端加密 AWS SDK for Java，并提供了 V1 和 V2 加密客户端之间的比较。

V1

// minimal configuration in V1; default CryptoMode.EncryptionOnly.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder()
             .withEncryptionMaterials(encryptionMaterialsProvider)
             .build();

V2

// minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder()
             .withEncryptionMaterialsProvider(encryptionMaterialsProvider)
             .withCryptoConfiguration(new CryptoConfigurationV2()
                           // The following setting allows the client to read V1 encrypted objects
                           .withCryptoMode(CryptoMode.AuthenticatedEncryption)
             )
             .build();

上面的示例将 cryptoMode 设置为 AuthenticatedEncryption。此设置允许 V2 加密客户端读取 V1 加密客户端写入的对象。如果您的客户端不需要读取 V1 客户端写入的对象的功能，建议改用默认设置 StrictAuthenticatedEncryption。

构建 V2 加密客户端

可以通过调用 A mazonS3 EncryptionClient V2 来构建 V2 加密客户端。 encryptionBuilder()。

您可以将所有现有的 V1 加密客户端替换为 V2 加密客户端。只要您通过将 V2 加密客户端配置为使用 `来允许 V2 加密客户端写入的任何对象，V2 加密客户端将始终能够读取 V1 加密客户端写入的任何对象。AuthenticatedEncryption `cryptoMode

创建新的 V2 加密客户端与创建 V1 加密客户端的方式非常相似。但还是有几个区别：

使用加密材料提供程序

您可以继续使用与 V1 加密客户端相同的加密材料提供程序和加密材料对象。这些类负责提供加密客户端用来保护数据的密钥。它们可以在 V2 和 V1 加密客户端中互换使用。

配置 V2 加密客户端

V2 加密客户端配置了一个 CryptoConfigurationV2 对象。可以通过调用其默认构造函数，然后根据需要修改其属性的默认值来构造此对象。

CryptoConfigurationV2 默认值如下所示：

请注意 EncryptionOnly，V2 加密客户端不支持cryptoMode该功能。V2 加密客户端将始终使用经过身份验证的加密来加密内容，并使用 V KeyWrap 2 对象保护内容加密密钥 (CEKs)。

以下示例演示如何在 V1 中指定加密配置，以及如何实例化 CryptoConfigurationV2 对象以传递给 V2 加密客户端生成器。

V1

CryptoConfiguration cryptoConfiguration = new CryptoConfiguration()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

V2

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

其他示例

以下示例演示如何解决与从 V1 迁移到 V2 相关的特定用例。

将服务客户端配置为读取 V1 加密客户端创建的对象

要读取以前使用 V1 加密客户端写入的对象，请将设置 cryptoMode 为 AuthenticatedEncryption。以下代码段演示如何使用此设置构造配置对象。

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.AuthenticatedEncryption);

配置服务客户端以获取对象的字节范围

要能够从加密的 S3 对象中 get 字节范围，请启用新的配置设置 rangeGetMode。默认情况下，此设置在 V2 加密客户端上处于禁用状态。请注意，即使启用了此设置，具有范围的 get 也只能对使用客户端 cryptoMode 设置支持的算法进行加密的对象起作用。有关更多信息，请参阅 “ AWS SDK for Java API参考” CryptoRangeGetMode中的。

如果您计划使用 V2 加密客户端 Amazon S3 TransferManager 对加密 Amazon S3 对象执行分段下载，则必须先在 V2 加密客户端上启用该rangeGetMode设置。

以下代码段演示如何配置 V2 客户端以执行具有范围的 get。

// Allows range gets using AES/CTR, for V2 encrypted objects only
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withRangeGetMode(CryptoRangeGetMode.ALL);

// Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withCryptoMode(CryptoMode.AuthenticatedEncryption)
       .withRangeGetMode(CryptoRangeGetMode.ALL);