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

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

Amazon S3加密客户端迁移

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

先决条件

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

  • Java 8 或更高版本已安装在应用程序环境中。这些区域有:Amazon SDK for Java使用Oracle Java SE 开发套件以及与发行版的开源 Java 开发工具包 (OpenJDK),如Amazon CorrettoRed Hat OpenJDK, 和AdoptOpenJDK.

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

迁移概述

此迁移分两个阶段进行:

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

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

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

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

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

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

更新项目配置中的依赖关系

修改项目配置文件(例如 pom.xml 或 build.gradle)以使用版本 1.11.837 或更高版本Amazon 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 客户端。为此,首先更新代码以使用新的服务客户端构建器。然后在已重命名的构建器上使用方法提供加密材料,并根据需要进一步配置服务客户端。

这些代码段演示如何将客户端加密与结合使用Amazon 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. 加密生成器 ()。

您可以用 V2 加密客户端替换所有现有的 V1 加密客户端。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中的Amazon 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);