Amazon S3 加密客户端迁移 - 适用于 .NET 的 Amazon SDK (V3)
迁移概述将现有客户端更新为 V1 过渡客户端以读取新格式将 V1 过渡客户端迁移到 V2 客户端以写入新格式将 V2 客户端更新为不再读取 V1 格式
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

的版本 4 (V4) 适用于 .NET 的 Amazon SDK 已经发布！

要开始使用新版本的 SDK，请参阅 适用于 .NET 的 Amazon SDK (V4) 开发者指南，尤其是迁移到版本 4 的主题。

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

Amazon S3 加密客户端迁移

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

使用 V2 客户端加密的对象无法使用 V1 客户端解密。为了便于迁移到新客户端，而不必同时重新加密所有对象，我们提供了“V1 过渡”客户端。此客户端可以解密 V1 和 V2 加密的对象，但只能加密与 V1 兼容的格式的对象。V2 客户端可以解密 V1 和 V2 加密的对象（当为 V1 对象启用时），但只能加密与 V2 兼容的格式的对象。

迁移概述

这种迁移分三个阶段进行。此处将介绍这些阶段，稍后将详细介绍。在下一阶段开始之前，必须完成所有使用共享对象的客户端的每个阶段。

  1. 将现有客户端更新为 V1 过渡客户端以读取新格式。首先，更新您的应用程序，使其依赖于 V1 过渡客户端，而不是 V1 客户端。V1 过渡客户端使您的现有代码能够解密新 V2 客户端编写的对象和以 V1 兼容格式编写的对象。

    注意

    V1 过渡客户端仅用于迁移目的。移至 V1 过渡客户端后，继续升级到 V2 客户端。

  2. 将 V1 过渡客户端迁移到 V2 客户端以编写新格式。接下来，将应用程序中的所有 V1 过渡客户端替换为 V2 客户端，并将安全配置文件设置为 V2AndLegacy。在 V2 客户端上设置此安全配置文件可使这些客户端解密以 V1 兼容格式加密的对象。

  3. 更新 V2 客户端，使其不再读取 V1 格式。最后，在所有客户端都迁移到 V2 并且所有对象都已以 V2 兼容格式加密或重新加密之后，请将 V2 安全配置文件设置为 V2 而不是 V2AndLegacy。这可以防止解密 V1 兼容格式的对象。

将现有客户端更新为 V1 过渡客户端以读取新格式

V2 加密客户端使用旧版本客户端不支持的加密算法。迁移的第一步是更新您的 V1 解密客户端，以便它们可以读取新格式。

V1 过渡客户端使您的应用程序能够解密 V1 和 V2 加密的对象。此客户端是 Amazon.Extensions.S3.Encryption 软件包的一部分。 NuGet 在每个应用程序上执行以下步骤以使用 V1 过渡客户端。

  1. 接受 Amazon.Extensions.S3.Encryption 程序包的依赖项。如果您的项目直接依赖于 AWSSDK.S3 或AWSSDK. KeyManagementService软件包，您必须更新这些依赖项或将其删除，以便将它们的更新版本与这个新软件包一起引入。

  2. 将相应的 using 语句从 Amazon.S3.Encryption 更改为 Amazon.Extensions.S3.Encryption，如下所示：

    // using Amazon.S3.Encryption;
  using Amazon.Extensions.S3.Encryption;

  3. 重新构建并重新部署您的应用程序。

V1 过渡客户端与 V1 客户端的 API 完全兼容，因此无需更改其它代码。

将 V1 过渡客户端迁移到 V2 客户端以写入新格式

V2 客户端是 A mazon.Extensions. NuGet S3.Encryption 软件包的一部分。它使您的应用程序能够解密 V1 和 V2 加密的对象（如果配置为这样做），但只能加密 V2 兼容格式的对象。

更新现有客户端以读取新的加密格式后，您可以继续将应用程序安全更新到 V2 加密和解密客户端。在每个应用程序上执行以下步骤以使用 V2 客户端：

  1. 将 EncryptionMaterials 更改为 EncryptionMaterialsV2。

    1. 使用 KMS 时：

      1. 提供 KMS 密钥 ID。

      2. 声明您正在使用的加密方法；即 KmsType.KmsContext。

      3. 向 KMS 提供与该数据密钥关联的加密上下文。您可以发送空字典（Amazon 加密上下文仍将合并到其中），但鼓励提供更多上下文。

    2. 使用用户提供的密钥封装方法（对称或非对称加密）时：

      1. 提供包含加密材料的 AES 或 RSA 实例。

      2. 声明要使用哪种加密算法；也就是说，SymmetricAlgorithmType.AesGcm 还是 AsymmetricAlgorithmType.RsaOaepSha1。

  2. 将 AmazonS3CryptoConfiguration 更改为 AmazonS3CryptoConfigurationV2，SecurityProfile 属性设置为 SecurityProfile.V2AndLegacy。

  3. 将 AmazonS3EncryptionClient 更改为 AmazonS3EncryptionClientV2。此客户端采用前面步骤中新转换的 AmazonS3CryptoConfigurationV2 和 EncryptionMaterialsV2 对象。

示例：KMS 到 KMS+Context

迁移前

using System.Security.Cryptography;
using Amazon.S3.Encryption;

var encryptionMaterial = new EncryptionMaterials("1234abcd-12ab-34cd-56ef-1234567890ab");
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);

迁移后

using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

示例：对称算法（AES-CBC 到 AES-GCM 密钥封装）

StorageMode 可以是 ObjectMetadata 或 InstructionFile。

迁移前

using System.Security.Cryptography;
using Amazon.S3.Encryption;

var symmetricAlgorithm = Aes.Create();
var encryptionMaterial = new EncryptionMaterials(symmetricAlgorithm);
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);

迁移后

using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var symmetricAlgorithm = Aes.Create();
var encryptionMaterial = new EncryptionMaterialsV2(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
注意

使用 AES-GCM 解密时，在开始使用解密的数据之前，请通读整个对象。这是为了验证对象自加密以来是否未对其进行过修改。

示例：非对称算法（RSA 到 RSA-OAEP-SHA 1 密钥封装）

StorageMode 可以是 ObjectMetadata 或 InstructionFile。

迁移前

using System.Security.Cryptography;
using Amazon.S3.Encryption;

var asymmetricAlgorithm = RSA.Create();
var encryptionMaterial = new EncryptionMaterials(asymmetricAlgorithm);
var configuration = new AmazonS3CryptoConfiguration()
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClient(configuration, encryptionMaterial);

迁移后

using System.Security.Cryptography;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

var asymmetricAlgorithm = RSA.Create();
var encryptionMaterial = new EncryptionMaterialsV2(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

将 V2 客户端更新为不再读取 V1 格式

最终，所有对象都将使用 V2 客户端进行加密或重新加密。转换完成后，您可以通过将 SecurityProfile 属性设置为 SecurityProfile.V2，在 V2 客户端中禁用 V1 兼容性，如以下代码片段所示。

//var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy);
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);