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

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

Amazon S3 加密客户端迁移

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

迁移概述

此迁移分为两个阶段：

1. 更新现有客户端以读取新格式。首先，将 AWS SDK for C++ 的已更新版本部署到应用程序中。这允许现有 V1 加密客户端解密由新的 V2 客户端写入的对象。如果您的应用程序使用多个 SDK AWS SDKs，则必须单独升级每个 SDK。

2. 将加密和解密客户端迁移到 V2。一旦所有 V1 加密客户端都能读取新格式，就可以将现有加密和解密客户端迁移到各自的 V2 版本。

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

您必须先将现有客户端更新到最新的 SDK 版本。完成此步骤后，您的应用程序的 V1 客户端将能够解密由 V2 加密客户端加密的对象，而无需更新应用程序的代码库。

生成并安装最新版本的 AWS SDK for C++

从源代码使用 SDK 的应用程序

如果您 AWS SDK for C++ 从源代码构建和安装，请从aws/aws-sdk-cpp上下载或克隆 SDK 源代码 GitHub。然后重复正常的构建和安装步骤。

如果您要 AWS SDK for C++ 从 1.8.x 之前的版本升级，请参阅此变更日志，了解每个主要版本中引入的重大更改。有关如何构建和安装的更多信息 AWS SDK for C++，请参阅AWS SDK for C++ 从源代码获取。

使用 Vcpkg 开发工具包的应用程序

如果您的应用程序使用 Vcpkg 来跟踪 SDK 更新，只需使用现有的 Vcpkg 升级方法将 SDK 升级到最新版本即可。请记住，版本发布与通过软件包管理器发布之间存在延迟。最新版本始终可以通过从源代码安装获得。

你可以运行以下命令来升级软件包aws-sdk-cpp：

vcpkg upgrade aws-sdk-cpp

并验证软件包的版本aws-sdk-cpp：

vcpkg list aws-sdk-cpp

该版本应至少为 1.8.24。

有关将 Vcpkg 与配合使用的更多信息 AWS SDK for C++，请参阅。AWS SDK for C++ 从包裹管理器那里获取

构建、安装和部署您的应用程序

如果您的应用程序静态链接到 AWS SDK for C++，则无需在应用程序中更改代码，但您必须重新构建应用程序才能使用最新的 SDK 更改。对于动态链接，此步骤不是必需的。

升级应用程序的依赖版本并验证应用程序功能后，继续将应用程序部署到队列中。应用程序部署完成后，您可以继续下一阶段，将应用程序迁移到使用 V2 加密和解密客户端。

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

以下步骤向您展示了如何成功地将您的代码从 Amazon S3 加密客户端的 V1 迁移到 V2。由于需要更改代码，因此无论应用程序是静态链接还是动态链接，您都需要重新构建应用程序。 AWS SDK for C++

使用新的加密材料

在 V2 Amazon S3 加密客户端和 V2 加密配置中，以下加密材料已被弃用：

它们已被以下安全加密材料所取代：

构建 V2 S3 加密客户端需要进行以下代码更改：

示例：使用 KMS/ KMSWith 上下文密钥封装算法

迁移前（KMS 密钥封装）

auto materials = Aws::MakeShared<KMSEncryptionMaterials>("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest);

迁移后（KMSWith上下文密钥换行）

auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
Aws::Map<Aws::String, Aws::String> kmsContextMap;
kmsContextMap.emplace("client", "aws-sdk-cpp");
kmsContextMap.emplace("version", "1.8.0");
encryptionClient.PutObject(putObjectRequest, kmsContextMap /* could be empty as well */);

示例：使用 AES/AES-GCM 密钥封装算法

迁移前（AES 密钥封装）

auto materials = Aws::MakeShared<SimpleEncryptionMaterials>("s3Encryption", HashingUtils::Base64Decode(AES_MASTER_KEY_BASE64));
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest);

迁移后（AES-GCM 密钥包装）

auto materials = Aws::MakeShared<SimpleEncryptionMaterialsWithGCMAAD>("s3EncryptionV2", HashingUtils::Base64Decode(AES_MASTER_KEY_BASE64));
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest, {} /* must be an empty map */);

其他示例

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

解密由旧版 Amazon S3 加密客户端加密的对象

默认情况下，您无法使用 V2 Amazon S3 加密客户端来解密使用已弃用的密钥封装算法或已弃用的内容加密架构加密的对象。

以下密钥封装算法已被弃用：

以下内容加密架构已被弃用：

如果您在中使用传统的 Amazon S3 加密客户端 AWS SDK for C++ 来加密对象，则在以下情况下，您可能会使用已弃用的方法：

要使用 V2 Amazon S3 加密客户端解密由已弃用的密钥封装算法或已弃用的内容加密架构加密的对象，您必须将 V2 加密配置SecurityProfile中的默认值从改为。V2 V2_AND_LEGACY

示例

迁移前

auto materials = Aws::MakeShared<KMSEncryptionMaterials>("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);

迁移后

auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
cryptoConfig.SetSecurityProfile(SecurityProfile::V2_AND_LEGACY);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);

使用范围解密对象

使用传统的 Amazon S3 加密客户端，您可以指定解密 S3 对象时要接收的字节范围。在 V2 Amazon S3 加密客户端中，此功能是DISABLED默认的。因此，您必须在 V2 加密配置ALL中重写默认值 from DISABLED 到。RangeGetMode

示例

迁移前

auto materials = Aws::MakeShared<KMSEncryptionMaterials>("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
getObjectRequest.WithRange("bytes=38-75");
encryptionClient.GetObject(getObjectRequest);

迁移后

auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
cryptoConfig.SetUnAuthenticatedRangeGet(RangeGetMode::ALL);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
getObjectRequest.WithRange("bytes=38-75");
encryptionClient.GetObject(getObjectRequest);

使用任意 CMK 解密对象

在解密使用加密的对象时KMSWithContextEncryptionMaterials，V2 Amazon S3 加密客户端能够通过提供空的主密钥让 KMS 找到正确的 CMK。DISABLED默认情况下，此功能已启用。您必须通过调用 KMS 加密材料对其SetKMSDecryptWithAnyCMK(true)进行明确配置。

示例

迁移前

auto materials = Aws::MakeShared<KMSEncryptionMaterials>("s3Encryption", ""/* provide an empty KMS Master Key*/);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);

迁移后

auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", ""/* provide an empty KMS Master Key*/);
materials.SetKMSDecryptWithAnyCMK(true);
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);

有关所有这些迁移场景的完整代码，请参阅 Github 上的 Amazon S3 加密示例。