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

# 如何迁移和部署 AWS Encryption SDK
<a name="migration-guide"></a>

从 1.7 之前的 AWS Encryption SDK 版本迁移时。 *x* 到 2.0 版。 *x* 或更高版本，您必须安全地过渡到使用密[钥承诺](concepts.md#key-commitment)进行加密。否则，您的应用程序将遇到无法解密的加密文字。如果您使用的是 AWS KMS 主密钥提供程序，则必须更新到在严格模式或发现模式下创建主密钥提供程序的新构造函数。

**注意**  
本主题专为从 AWS Encryption SDK 早期版本迁移到版本 2.0.*x* 或更高版本的用户而设计。如果您不熟悉 AWS Encryption SDK，则可以在默认设置下立即开始使用最新的可用版本。

为避免出现无法解密需要读取的加密文字的严重情况，我们建议您分多个不同阶段进行迁移和部署。在开始下一阶段之前，请确认各阶段均已结束并全面部署。这对于具有多台主机的分布式应用程序尤其重要。

## 阶段 1：将您的应用程序更新到最新版本 1.*x*
<a name="migrate-stage1"></a>

更新到适用于您的编程语言的最新版本 1.*x*。在开始阶段 2 之前，请仔细测试、部署更改并确认更新已传播到所有目标主机。

**重要**  
验证最新版本 1.*x* 为 AWS Encryption SDK版本 1.7.*x* 或更高版本。

最新的 1. *x* 版本向后兼容的旧版本， AWS Encryption SDK 向前兼容版本 2.0。 AWS Encryption SDK *x* 及更高版本。最新版本包括版本 2.0.*x* 的新功能，但也包括为此迁移设计的安全默认值。它们允许您在必要时升级 AWS KMS 主密钥提供程序，并使用可通过密钥承诺解密密文的算法套件进行全面部署。
+ 替换弃用元素，包括旧版 AWS KMS 主密钥提供程序的构造函数。在 [Python](https://docs.python.org/3/library/warnings.html) 中，请确保打开弃用警告。最新版本 1.*x* 弃用的代码元素已从版本 2.0.*x* 及更高版本中移除。
+ 将您的承诺策略明确设置为 `ForbidEncryptAllowDecrypt`。尽管这是最新版本中唯一的有效值 1. *x* 版本，当您使用本版本中 APIs 引入的版本时，需要此设置。当您迁移到版本 2.0.*x* 及更高版本时，其可防止您的应用程序拒绝未使用密钥承诺加密的加密文字。有关更多信息，请参阅 [设置您的承诺策略](migrate-commitment-policy.md)。
+ 如果您使用 AWS KMS 主密钥提供程序，则必须将旧版主密钥提供程序更新为支持*严格模式和*发现模式**的主密钥提供程序。 AWS Encryption SDK for Java、 AWS Encryption SDK for Python和 AWS 加密 CLI 需要进行此更新。如果您在发现模式下使用主密钥提供程序，我们建议您实施发现筛选条件，将使用的包装密钥限制为特定 AWS 账户的密钥。此项更新为可选项，但却是我们建议的[最佳实践](best-practices.md)。有关更多信息，请参阅 [更新 AWS KMS 主密钥提供程序](migrate-mkps-v2.md)。
+ 如果您使用 [AWS KMS Discovery 密钥环](use-kms-keyring.md#kms-keyring-discovery)，我们建议您纳入将可用于解密的包装密钥限制为特定 AWS 账户密钥的发现筛选条件。此项更新为可选项，但却是我们建议的[最佳实践](best-practices.md)。有关更多信息，请参阅 [更新 AWS KMS 钥匙圈](migrate-keyrings-v2.md)。

## 阶段 2：将您的应用程序更新到最新版本
<a name="migrate-stage2"></a>

所有主机成功部署最新版本 1.*x* 版本后，您可以升级到版本 2.0.*x* 及更高版本。版本 2.0。 *x* 包括对所有早期版本的重大更改 AWS Encryption SDK。但是，如果您按照阶段 1 的建议更改代码，可以避免在迁移到最新版本时出错。

在更新到最新版本之前，请确认您的承诺策略始终设置为 `ForbidEncryptAllowDecrypt`。然后，根据您的数据配置，您可以按照自己的节奏迁移到 `RequireEncryptAllowDecrypt`，然后迁移到默认设置 `RequireEncryptRequireDecrypt`。我们建议采取一系列过渡步骤，例如以下模式。

1. 首先，将您的[承诺策略](migrate-commitment-policy.md)设置为 `ForbidEncryptAllowDecrypt`。 AWS Encryption SDK 可以使用密钥承诺解密消息，但尚未使用密钥承诺进行加密。

1. 准备就绪后，将承诺策略更新为 `RequireEncryptAllowDecrypt`。 AWS Encryption SDK 开始使用密[钥承诺](concepts.md#key-commitment)对您的数据进行加密。其可使用也可不使用密钥承诺解密加密文字。

   在将您的承诺策略更新为 `RequireEncryptAllowDecrypt` 之前，请确认您的最新版本 1.*x* 部署到所有主机，包括解密您生成的加密文字的任何应用程序的主机。1.7 AWS Encryption SDK 之前版本的版本。 *x* 无法解密使用密钥承诺加密的消息。

   这也是向应用程序添加指标的好时机，以衡量您是否仍在未使用密钥承诺处理加密文字。这将帮助您确定何时可以安全地将承诺策略设置更新为 `RequireEncryptRequireDecrypt`。对于某些应用程序，例如对 Amazon SQS 队列中的消息进行加密的应用程序，这可能意味着要等待足够长的时间才能重新加密或删除使用旧版本加密的所有加密文字。对于其他应用程序，例如加密的 S3 对象，您可能需要下载、重新加密和重新上传所有对象。

1. 如果您确定没有任何未使用密钥承诺加密的消息，则可以将承诺策略更新为 `RequireEncryptRequireDecrypt`。此值可确保您的数据始终使用密钥承诺进行加密和解密。此设置为默认设置，因此您无需明确设置，但我们建议您这样做。如果您的应用程序遇到未使用密钥承诺加密的加密文字，明确设置将[协助调试](troubleshooting-migration.md)和可能需要的任何潜在回滚。