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

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

注意

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

本主题介绍如何将您的应用程序从亚马逊简单存储服务 (S3) Simple Service 加密客户端的版本 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 客户端后，继续升级到 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）