对迁移到至最新版本进行故障排除 - AWS Encryption SDK
弃用或移除的对象配置冲突：承诺策略和算法套件配置冲突：承诺策略和加密文字密钥承诺验证失败其他加密故障其他加密故障回滚注意事项

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

对迁移到至最新版本进行故障排除

在将应用程序更新到版本 AWS Encryption SDK 版本 2.0.x 或更高版本之前，首先更新到 AWS Encryption SDK 最新版本 1.x 并进行完整部署。这将有助于避免在更新到版本 2.0.x 及更高版本时可能遇到的多数错误。有关详细指南（包括示例），请参阅 迁移 AWS Encryption SDK。

重要

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

注意

AWS Encryption CLI：本指南中对 AWS Encryption SDK 版本 1.7.x 的引用适用于 AWS Encryption CLI 版本 1.8.x。本指南中对 AWS Encryption SDK 版本 2.0.x 的引用适用于 AWS Encryption CLI 2.1.x。

新的安全功能最初是在 AWS Encryption CLI 版本 1.7.x 和 2.0.x 中发布的。但是，AWS Encryption CLI 版本 1.8.x 取代版本 1.7.x，AWS Encryption CLI 2.1.x 取代 2.0.x。有关详细信息，请参阅 GitHub 上的 aws-encryption-sdk-cli 存储库中的相关安全通告。

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

弃用或移除的对象

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

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

配置冲突：承诺策略和算法套件

如果您指定的算法套件与您的承诺策略冲突，加密调用会失败并出现配置冲突错误。

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

承诺策略 兼容算法套件
ForbidEncryptAllowDecrypt

任何不具有密钥承诺的算法套件，例如：

AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384（03 78）（具有签名）

AES_256_GCM_IV12_TAG16_HKDF_SHA256（01 78）（不具有签名）
RequireEncryptAllowDecrypt

RequireEncryptRequireDecrypt

任何具有密钥承诺的算法套件，例如：

AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384（05 78）（具有签名）

AES_256_GCM_HKDF_SHA512_COMMIT_KEY（04 78）（不具有签名）

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

配置冲突：承诺策略和加密文字

RequireEncryptRequireDecrypt承诺策略不允许 AWS Encryption SDK 解密未使用密钥承诺加密的消息。如果您要求 AWS Encryption SDK 不使用密钥承诺解密消息，则会返回配置冲突错误。

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

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

密钥承诺验证失败

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

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

其他加密故障

加密故障原因多种多样。您不可使用 AWS KMS Discovery 密钥环或发现模式下的主密钥提供程序加密消息。

请确保指定包含您有权用其加密的包装密钥的密钥环或主密钥提供程序。有关 AWS KMS keys 权限的帮助，请参阅《AWS Key Management Service 开发人员指南》中的查看密钥政策 和确定对 AWS KMS key 的访问权限。

其他加密故障

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

如果您使用的是指定包装密钥的密钥环或主密钥提供程序，则 AWS Encryption SDK 仅使用您指定的包装密钥。请确认您使用的是打算使用且拥有至少一个包装密钥 kms:Decrypt 权限的包装密钥。如果您使用的是 AWS KMS keys，则可以尝试使用 AWS KMS Discovery 密钥环或发现模式下的主密钥提供程序解密消息。如果操作成功，在返回明文之前，请验证用于解密消息的密钥是否是您信任的密钥。

回滚注意事项

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

如果必须回滚，请谨慎操作。AWS Encryption SDK 1.7.x 之前的版本无法解密使用密钥承诺加密的加密文字。

  • 从最新版本 1.x 回滚到 AWS Encryption SDK 先前版本通常是安全的。您可能需要撤消对代码所做更改才能使用先前版本不支持的符号和对象。

  • 在版本 2.0.x 或更高版本中开始使用密钥承诺进行加密后（将您的承诺策略设置为 RequireEncryptAllowDecrypt），您可以回滚到版本 1.7.x 而非任何早期版本。AWS Encryption SDK 1.7.x 之前的版本无法解密使用密钥承诺加密的加密文字。

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