Amazon S3加密客户端迁移 - AWS SDK for Java

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

Amazon S3加密客户端迁移

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

先决条件

Amazon S3客户端加密要求以下各项:

  • Java 8 或更高版本安装在您的应用程序环境中。这些区域有:AWS SDK for Java与结合使用甲骨文 Java SE 开发套件还有 Open Java 开发工具包 (OpenJDK) 的发行版,例如Amazon CorrettoRed Hat OpenJDK, 和AdoptOpenJDK.

  • 这些区域有:Bouncy Castle 加密包. 你可以将 Bouncy Castle .jar 文件放在应用程序环境的类路径上,或者添加对 artifactId 的依赖关系bcprov-ext-jdk15on(groupId 为org.bouncycastle) 致您的 Mavenpom.xml文件。

迁移概述

此迁移分两个阶段进行:

  1. 更新现有客户端以读取新格式。更新您的应用程序以使用 1.11.837 或更高版本的AWS SDK for Java然后重新部署应用程序。这会启用Amazon S3应用程序中的客户端加密服务客户端,用于解密 V2 服务客户端创建的对象。如果您的应用程序使用多个AWSSDK,必须单独更新每个 SDK。

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

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

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

在项目更新到最新开发工具包版本后,您就可以修改应用代码来使用 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();

上面的例子设置了cryptoModeAuthenticatedEncryption. 此设置允许 V2 加密客户端读取 V1 加密客户端写入的对象。如果您的客户端不需要读取 V1 客户端写入的对象的功能,则我们建议使用默认设置StrictAuthenticatedEncryption相反。

构建 V2 加密客户端

V2 加密客户端可以通过调用来构建亚马逊 S3EncryptionClientv2.encryptionBuilder ()

您可以将所有现有的 V1 加密客户端替换为 V2 加密客户端。V2 加密客户端将始终能够读取 V1 加密客户端写入的任何对象,前提是您允许,方法是将 V2 加密客户端配置为使用AuthenticatedEncryption`cryptoMode.

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

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

  • 默认cryptoModeV2 加密客户端的设置为StrictAuthenticatedEncryption. 对于 V1 加密客户端来说是EncryptionOnly.

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

注意

使用 AES-GCM 解密时,在开始使用解密的数据之前,请将整个对象读到最后。这是为了验证对象自加密以来是否尚未修改。

使用加密材料提供程序

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

配置 V2 加密客户端

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

的默认值CryptoConfigurationV2是:

  • cryptoMode = CryptoMode.StrictAuthenticatedEncryption

  • storageMode = CryptoStorageMode.ObjectMetadata

  • secureRandom= 的实例SecureRandom

  • rangeGetMode = CryptoRangeGetMode.DISABLED

  • unsafeUndecryptableObjectPassthrough = false

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

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

V1

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

V2

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

其他示例

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

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

要读取以前使用 V1 加密客户端写入的对象,请将cryptoModeAuthenticatedEncryption. 以下代码片段演示了如何使用此设置构造配置对象。

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

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

为了能够get来自加密 S3 对象的字节范围,启用新的配置设置rangeGetMode. 默认情况下,此设置在 V2 加密客户端上处于禁用状态。请注意,即使启用了,也有一个远程get仅适用于使用支持的算法加密的对象cryptoMode客户机的设置。有关更多信息,请参阅CryptoRangeGetMode中的AWS SDK for JavaAPI 参考。

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

以下代码片段演示了如何配置 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);