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

# 对迁移到至最新版本进行故障排除
<a name="troubleshooting-migration"></a>

在将应用程序更新到 2.0 版之前。 *x* 或更高版本 AWS Encryption SDK，更新到最新的 1。 *x* 版本的， AWS Encryption SDK 然后将其完全部署。这将有助于避免在更新到版本 2.0.*x* 及更高版本时可能遇到的多数错误。有关详细指南（包括示例），请参阅 [迁移你的 AWS Encryption SDK](migration.md)。

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

**注意**  
**AWS 加密 CLI**：本指南中对版本 1.7 的参考。 其中的 *x* AWS Encryption SDK 适用于版本 1.8。 AWS 加密 CLI 中的 *x*。本指南中对版本 2.0 的引用。 其中的 *x* AWS Encryption SDK 适用于 2.1。 AWS 加密 CLI 中的 *x*。  
新的安全功能最初是在 AWS 加密 CLI 版本 1.7 中发布的。 *x* 和 2.0。 *x*。但是， AWS 加密 CLI 版本为 1.8。 *x* 取代了 1.7 版。 *x* 和 AWS 加密 CLI 2.1。 *x* 取代 2.0。 *x*。有关详细信息，请参阅[aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)存储库中的相关[安全公告](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) GitHub。

本主题旨在帮助您识别和解决可能遇到的最常见错误。

**Topics**
+ [弃用或移除的对象](#deprecated-removed)
+ [配置冲突：承诺策略和算法套件](#configuration-conflict_1)
+ [配置冲突：承诺策略和加密文字](#configuration-conflict_2)
+ [密钥承诺验证失败](#commitment-failed)
+ [其他加密故障](#encrypt-failed)
+ [其他加密故障](#decrypt-failed)
+ [回滚注意事项](#migration-rollback)

## 弃用或移除的对象
<a name="deprecated-removed"></a>

版本 2.0.*x* 包含几项重大更改，包括移除版本 1.7.*x* 中弃用的旧版构造函数、方法、函数和类。为避免编译器错误、导入错误、语法错误和未找到符号错误（取决于您的编程语言），请先升级到最新的 1。 AWS Encryption SDK 适用于您的编程语言的 *x* 版本。（此版本必须为版本 1.7.*x* 或更高版本。） 在使用最新版本 1.*x* 时，您可以在移除原始符号之前开始使用替换元素。

如果需要立即升级到版本 2.0.*x* 或更高版本，[请查阅您的编程语言的更改日志](about-versions.md)，然后用更改日志建议的符号替换旧版符号。

## 配置冲突：承诺策略和算法套件
<a name="configuration-conflict_1"></a>

如果您指定的算法套件与您的[承诺策略](concepts.md#commitment-policy)冲突，加密调用会失败并出现*配置冲突*错误。

为避免此类错误，请勿指定算法套件。默认情况下， AWS Encryption SDK 会选择与您的承诺策略兼容的最安全的算法。但是，如果您必须指定算法套件（例如不具有签名的算法套件），请确保选择与您的承诺策略兼容的算法套件。


| 承诺策略 | 兼容算法套件 | 
| --- | --- | 
| ForbidEncryptAllowDecrypt | 任何*不具有*密钥承诺的算法套件，例如：AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384（[03 78](algorithms-reference.md)）（具有签名） `AES_256_GCM_IV12_TAG16_HKDF_SHA256`（[01 78](algorithms-reference.md)）（不具有签名） | 
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | 任何*具有*密钥承诺的算法套件，例如：AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384（[05 78](algorithms-reference.md)）（具有签名） `AES_256_GCM_HKDF_SHA512_COMMIT_KEY`（[04 78](algorithms-reference.md)）（不具有签名） | 

如果您在未指定算法套件时遇到此错误，则可能是您的[加密材料管理器](concepts.md#crypt-materials-manager) （CMM）选择了冲突算法套件。默认 CMM 不会选择冲突算法套件，但自定义 CMM 可能会。如需帮助，请参阅自定义 CMM 相关文档。

## 配置冲突：承诺策略和加密文字
<a name="configuration-conflict_2"></a>

`RequireEncryptRequireDecrypt`[承诺策略](concepts.md#commitment-policy)不允许 AWS Encryption SDK 解密未使用[密钥承诺](concepts.md#key-commitment)加密的消息。如果您要求解 AWS Encryption SDK 密未承诺密钥的消息，则会返回*配置冲突错误*。

为避免此错误，在设置 `RequireEncryptRequireDecrypt` 承诺策略之前，请确保所有未使用密钥承诺加密的加密文字均使用密钥承诺进行解密和重新加密，或者由其他应用程序处理。如果您遇到此错误，可以针对冲突加密文字返回错误，或者将您的承诺策略暂时更改为 `RequireEncryptAllowDecrypt`。

如果您因为在未首先升级到最新版本 1.*x*（1.7.*x* 或更高版本）的情况下，从 1.7.*x* 之前的版本升级到版本 2.0.*x* 或更高版本遇到此错误，可以考虑[回滚](#migration-rollback)到最新版本 1.*x*，并在升级到版本 2.0.*x* 或更高版本之前将该版本部署到所有主机。有关帮助信息，请参阅 [如何迁移和部署 AWS Encryption SDK](migration-guide.md)。

## 密钥承诺验证失败
<a name="commitment-failed"></a>

解密使用密钥承诺加密的消息时，可能会收到*密钥承诺验证失败*的错误消息。这表示解密调用失败，因为[加密消息](concepts.md#DEK)中的数据密钥与消息的唯一数据密钥不同。通过在解密过程中验证数据密钥，[密钥承诺](concepts.md#key-commitment)可以避免解密可能生成多个明文的消息。

此错误表示 AWS Encryption SDK未返回您尝试解密的加密消息。此错误可能是手动制作的消息或数据损坏的结果。如果您遇到此错误，您的应用程序可能会拒绝该消息并继续，或者停止处理新消息。

## 其他加密故障
<a name="encrypt-failed"></a>

加密故障原因多种多样。您不可使用 [AWS KMS Discovery 密钥环](use-kms-keyring.md#kms-keyring-discovery)或[发现模式下的主密钥提供程序](migrate-mkps-v2.md)加密消息。

请确保指定包含您[有权用其](use-kms-keyring.md#kms-keyring-permissions)加密的包装密钥的密钥环或主密钥提供程序。有关权限的帮助 AWS KMS keys，请参阅《*AWS Key Management Service 开发者指南》 AWS KMS key*中的[查看密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html)和[确定对的访问](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html)权限。

## 其他加密故障
<a name="decrypt-failed"></a>

如果加密消息解密尝试失败，则意味着 AWS Encryption SDK 无法（或不会）解密消息中的任何加密数据密钥。

如果您使用的是指定包装密钥的密钥环或主密钥提供程序，则仅 AWS Encryption SDK 使用您指定的包装密钥。请确认您使用的是打算使用且拥有至少一个包装密钥 `kms:Decrypt` 权限的包装密钥。如果您使用的是备用方法 AWS KMS keys，则可以尝试在发现模式下使用[AWS KMS 发现密钥环或主密钥](use-kms-keyring.md#kms-keyring-discovery)[提供程序](migrate-mkps-v2.md)来解密消息。如果操作成功，在返回明文之前，请验证用于解密消息的密钥是否是您信任的密钥。

## 回滚注意事项
<a name="migration-rollback"></a>

如果您的应用程序无法加密或解密数据，则通常可以通过更新代码符号、密钥环、主密钥提供程序或[承诺策略](concepts.md#commitment-policy)来解决问题。但是，在某些情况下，您可能会决定最好将应用程序回滚到 AWS Encryption SDK先前版本。

如果必须回滚，请谨慎操作。1.7 AWS Encryption SDK 之前的版本。 *x* [无法解密使用密钥承诺加密的密文。](concepts.md#key-commitment)
+ 从最新版本 1.*x* 回滚到 AWS Encryption SDK 先前版本通常是安全的。您可能需要撤消对代码所做更改才能使用先前版本不支持的符号和对象。
+ 在版本 2.0.*x* 或更高版本中开始使用密钥承诺进行加密后（将您的承诺策略设置为 `RequireEncryptAllowDecrypt`），您可以回滚到版本 1.7.*x* 而非任何早期版本。1.7 AWS Encryption SDK 之前的版本。 *x* [无法解密使用密钥承诺加密的密文。](concepts.md#key-commitment)

如果您在所有主机均可使用密钥承诺解密之前意外启用了使用密钥承诺进行加密，则最好继续推出而非回滚。如果消息是暂时的，或者可以安全删除，则可以考虑在消息丢失的情况下进行回滚。如果需要回滚，您可以考虑编写解密和重新加密所有消息的工具。