迁移概述将现有客户端更新为 V1-transitional 客户机以阅读新格式将 V1-transitional 客户端迁移到 V2 客户端以编写新格式将 V2 客户端更新为不再读取 V1 格式

Amazon S3 加密客户端迁移（V1 到 V2）

注意

如果您使用的是 V2 并想迁移到 V4，请参阅Amazon S3 加密客户端迁移（V2 到 V4）。

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

使用 V2 客户端加密的对象无法使用 V1 客户端解密。为了便于迁移到新客户机而不必同时重新加密所有对象，提供了 V1-transitional “” 客户端。该客户端可以解密 V1 和 V2-encrypted 对象，但只能以格式加密对象。 V1-compatible V2 客户端可以解密 V1 和 V2-encrypted 对象（启用 V1 对象时），但只能以格式加密对象。 V2-compatible

迁移概述

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

将现有客户端更新为 V1-transitional 客户机以阅读新格式。首先，更新您的应用程序，使其依赖于 V1-transitional客户端，而不是 V1 客户端。该 V1-transitional 客户端使您的现有代码能够解密由新 V2 客户端编写的对象和以 V1-compatible 格式编写的对象。

注意
提供的 V1-transitional 客户端仅用于迁移目的。迁移到客户端后，继续升级到 V2 V1-transitional 客户端。
将 V1-transitional 客户端迁移到 V2 客户端以编写新格式。接下来，将应用程序中的所有 V1-transitional 客户端替换为 V2 客户端，并将安全配置文件设置为V2AndLegacy。在 V2 客户端上设置此安全配置文件使这些客户端能够解密以 V1-compatible格式加密的对象。
更新 V2 客户端，使其不再读取 V1 格式。最后，在所有客户端都已迁移到 V2 且所有对象均已按 V2-compatible 格式加密或重新加密后，将 V2 安全配置文件设置为V2而不是。V2AndLegacy这可以防止对 V1-compatible格式化对象进行解密。

将现有客户端更新为 V1-transitional 客户机以阅读新格式

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

该 V1-transitional 客户端使您的应用程序能够解密 V1 和 V2-encrypted 对象。这个客户端是Amazon.Extensions.S3.Encryption NuGet 软件包的一部分。要使用 V1-transitional 客户端，请在每个应用程序上执行以下步骤。

对Amazon.Extensions.S3.Encryption软件包建立新的依赖关系。如果您的项目直接依赖于AWSSDK.S3或AWSSDK.KeyManagementService包，则必须更新这些依赖项或将其删除，以便将它们的更新版本与该新包一起使用。
将相应的 using 语句从 Amazon.S3.Encryption 更改为 Amazon.Extensions.S3.Encryption，如下所示：
```
// using Amazon.S3.Encryption;
  using Amazon.Extensions.S3.Encryption;
```
重新构建并重新部署您的应用程序。

该 V1-transitional 客户端完全 API-compatible 使用 V1 客户端，因此无需更改其他代码。

将 V1-transitional 客户端迁移到 V2 客户端以编写新格式

V2 客户端是Amazon.Extensions.S3.Encryption NuGet 软件包的一部分。它使您的应用程序能够解密 V1 和 V2-encrypted 对象（如果配置为解密），但只能以格式加密对象。 V2-compatible

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

将 EncryptionMaterials 更改为 EncryptionMaterialsV2。
1. 使用 KMS 时：
  1. 提供 KMS 密钥 ID。
  2. 声明您正在使用的加密方法；即 KmsType.KmsContext。
  3. 向 KMS 提供与该数据密钥关联的加密上下文。您可以发送空字典（Amazon 加密上下文仍将合并到其中），但鼓励提供更多上下文。
2. 使用用户提供的密钥封装方法（对称或非对称加密）时：
  1. 提供包含加密材料的 AES 或 RSA 实例。
  2. 声明要使用哪种加密算法；也就是说，SymmetricAlgorithmType.AesGcm 还是 AsymmetricAlgorithmType.RsaOaepSha1。
将 AmazonS3CryptoConfiguration 更改为 AmazonS3CryptoConfigurationV2，SecurityProfile 属性设置为 SecurityProfile.V2AndLegacy。
将 AmazonS3EncryptionClient 更改为 AmazonS3EncryptionClientV2。此客户端采用前面步骤中新转换的 AmazonS3CryptoConfigurationV2 和 EncryptionMaterialsV2 对象。

示例：KMS 到 KMS+Context

Pre-migration


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);

Post-migration


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。

Pre-migration


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);

Post-migration


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-SHA1 密钥换行）

StorageMode 可以是 ObjectMetadata 或 InstructionFile。

Pre-migration


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);

Post-migration


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);

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

强制实施最低 TLS 版本

S3 加密客户端迁移（V2 到 V4）