Amazon S3 加密客户端迁移 - 适用于 Java 的 AWS 开发工具包
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

Amazon S3 加密客户端迁移

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

Prerequisites

Amazon S3 客户端加密需要:

迁移概述

此迁移过程分为两个阶段:

  1. 更新现有客户端以读取新格式。 更新您的应用程序以使用适用于 Java 的 AWS 开发工具包版本 1.11.837 或更高版本并重新部署应用程序。这使您的应用程序中的 Amazon S3 客户端加密服务客户端能够解密 V2 服务客户端创建的对象。如果您的应用程序使用多个 AWS SDKs,则必须单独更新每个开发工具包。

  2. 将加密和解密客户端迁移到 V2。 一旦您的所有 V1 加密客户端均可读取 V2 加密格式,请更新应用程序代码中的 Amazon S3 客户端加密和解密客户端以使用其 V2 等效项。

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

V2 加密客户端使用较旧版本的适用于 Java 的 AWS 开发工具包不支持的加密算法。

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

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

更新项目配置中的依赖项

修改您的项目配置文件(例如 pom.xml 或 build.gradle),以使用适用于 Java 的 AWS 开发工具包 1.11.837 版或更高版本。然后,重新构建您的项目并重新部署它。

完成此步骤后,部署新的应用程序代码,有助于确保加密和解密操作在迁移过程中在整个队列中保持一致。

使用 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

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

这些代码段演示如何将客户端加密与适用于 Java 的 AWS 开发工具包结合使用,并提供 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 加密客户端

V2 加密客户端可通过调用 AmazonS3EncryptionClientV2.encryptionBuilder(). 来构造

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

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

  • 您将使用 CryptoConfigurationV2 对象配置客户端,而不是 CryptoConfiguration 对象。此参数为必需参数。

  • V2 加密客户端的默认 cryptoMode 设置为 StrictAuthenticatedEncryption。 对于 V1 加密客户端,它是 EncryptionOnly

  • 加密客户端生成器上的方法 withEncryptionMaterials() 已重命名为 ()withEncryptionMaterialsProvider。这只是一种更准确地反映参数类型的外观更改。配置服务客户端时,必须使用新方法。

注意

使用 AES-GCM 进行解密时,在开始使用解密的数据之前,将整个对象读取到末尾。这是为了验证对象自加密后是否未被修改。

使用加密材料提供程序

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

配置 V2 加密客户端

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

的默认值为:CryptoConfigurationV2

  • cryptoMode = CryptoMode.StrictAuthenticatedEncryption

  • storageMode = CryptoStorageMode.ObjectMetadata

  • secureRandom = 实例 SecureRandom

  • rangeGetMode = CryptoRangeGetMode.DISABLED

  • unsafeUndecryptableObjectPassthrough = false

请注意,EncryptionOnly 不是 V2 加密客户端中支持的 cryptoModeV2 加密客户端将始终使用经身份验证的加密来加密内容,并使用 V2 KeyWrap 对象保护内容加密密钥 (CEK)。

以下示例演示如何在 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 设置支持的算法加密的对象。有关更多信息,请参阅适用于 Java 的 AWS 开发工具包 API 参考中的 CryptoRangeGetMode

如果您计划使用 Amazon S3 TransferManager 通过 V2 加密客户端执行加密 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);