本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 對遷移至最新版本進行故障診斷
將應用程式更新至 2.0.*x* 版或更新版本之前 AWS Encryption SDK，請將 更新至最新的 1.*x* 版 AWS Encryption SDK ，然後完全部署。這可協助您避免在更新至 2.0.*x* 版和更新版本時可能遇到的大多數錯誤。如需詳細指引，包括範例，請參閱 [遷移您的 AWS Encryption SDK](migration.md)。
**重要**
確認您最新的 1.*x* 版本是 1.7.*x* 或更新版本 AWS Encryption SDK。
**注意**
**AWS 加密 CLI**：本指南中 1.7.*x* 版的參考 AWS Encryption SDK 適用於 AWS 加密 CLI 1.8.*x* 版。本指南中 2.0.*x* 版的參考 AWS Encryption SDK 適用於 AWS 加密 CLI 的 2.1.*x*。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
本主題旨在協助您識別和解決可能遇到的最常見錯誤。
**Topics**
+ [已棄用或移除的物件](#deprecated-removed)
+ [組態衝突：承諾政策和演算法套件](#configuration-conflict_1)
+ [組態衝突：承諾政策和加密文字](#configuration-conflict_2)
+ [金鑰承諾驗證失敗](#commitment-failed)
+ [其他加密失敗](#encrypt-failed)
+ [其他解密失敗](#decrypt-failed)
+ [回復考量](#migration-rollback)
## 已棄用或移除的物件
2.0.*x* 版包含多項重大變更，包括移除在 1.7.*x* 版中棄用的傳統建構函數、方法、函數和類別。為了避免編譯器錯誤、匯入錯誤、語法錯誤和符號找不到錯誤 （取決於您的程式設計語言），請先升級到 AWS Encryption SDK 程式設計語言的最新 1.*x* 版本。（這必須是 1.7.*x* 版或更新版本。) 使用最新的 1.*x* 版本時，您可以在移除原始符號之前開始使用取代元素。
如果您需要立即升級至 2.0.*x* 版或更新版本，[請參閱變更日誌](about-versions.md)以取得您的程式設計語言，並使用變更日誌建議的符號取代舊版符號。
## 組態衝突：承諾政策和演算法套件
如果您指定的演算法套件與您的[承諾政策](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 的文件。
## 組態衝突：承諾政策和加密文字
`RequireEncryptRequireDecrypt` [承諾政策](concepts.md#commitment-policy)不允許 AWS Encryption SDK 解密在沒有[金鑰承諾](concepts.md#key-commitment)的情況下加密的訊息。如果您要求 AWS Encryption SDK 在沒有金鑰承諾的情況下解密訊息，它會傳回*組態衝突*錯誤。
為了避免此錯誤，在設定`RequireEncryptRequireDecrypt`承諾政策之前，請確保使用金鑰承諾解密和重新加密所有加密的加密文字，或由不同的應用程式處理。如果您遇到此錯誤，您可以傳回衝突加密文字的錯誤，或將承諾政策暫時變更為 `RequireEncryptAllowDecrypt`。
如果您因為從早於 1.7.*x* 的版本升級至 2.0.*x* 版或更新版本而遇到此錯誤，但未先升級至最新的 1.*x* 版本 (1.7.*x* 版或更新版本），請考慮[回復](#migration-rollback)至最新的 1.*x* 版本，並在升級至 2.0.*x* 版或更新版本之前將該版本部署至所有主機。如需協助，請參閱 [如何遷移和部署 AWS Encryption SDK](migration-guide.md)。
## 金鑰承諾驗證失敗
當您解密使用金鑰承諾加密的訊息時，您可能會收到*金鑰承諾驗證失敗*的錯誤訊息。這表示解密呼叫失敗，因為[加密訊息](concepts.md#DEK)中的資料金鑰與訊息的唯一資料金鑰不同。透過在解密期間驗證資料金鑰，[金鑰承諾](concepts.md#key-commitment)可保護您免於解密可能導致多個純文字的訊息。
此錯誤表示您嘗試解密的加密訊息並未由 傳回 AWS Encryption SDK。它可能是手動製作的訊息或資料損毀的結果。如果您遇到此錯誤，您的應用程式可以拒絕訊息並繼續，或停止處理新訊息。
## 其他加密失敗
加密可能會因為多種原因而失敗。您無法在[AWS KMS 探索模式中使用探索 keyring](use-kms-keyring.md#kms-keyring-discovery) 或主金鑰提供者來加密訊息。 [更新 AWS KMS 主金鑰提供者](migrate-mkps-v2.md)
請務必使用您有權[用於](use-kms-keyring.md#kms-keyring-permissions)加密的包裝金鑰來指定 keyring 或主金鑰提供者。如需 許可的說明 AWS KMS keys，請參閱《 *AWS Key Management Service 開發人員指南*》中的[檢視金鑰政策和](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html)[判斷對 的存取權 AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html)。
## 其他解密失敗
如果您嘗試解密加密的訊息失敗，表示 AWS Encryption SDK 無法 （或不會） 解密訊息中的任何加密資料金鑰。
如果您使用指定包裝金鑰的 keyring 或主金鑰提供者，則 只會 AWS Encryption SDK 使用您指定的包裝金鑰。確認您使用的是您想要的包裝金鑰，而且您至少擁有其中一個包裝金鑰的`kms:Decrypt`許可。如果您使用 做為備用 AWS KMS keys，則可以嘗試使用[AWS KMS 探索 keyring](use-kms-keyring.md#kms-keyring-discovery) 或[探索模式中的主金鑰提供者](migrate-mkps-v2.md)來解密訊息。如果操作成功，在傳回純文字之前，請確認用來解密訊息的金鑰是您信任的金鑰。
## 回復考量
如果您的應用程式無法加密或解密資料，您通常可以透過更新程式碼符號、 keyring、主金鑰提供者或[承諾政策](concepts.md#commitment-policy)來解決問題。不過，在某些情況下，您可能會決定最好將應用程式復原至舊版的 AWS Encryption SDK。
如果您必須復原，請謹慎執行。1.7.*x* AWS Encryption SDK 之前的 版本無法解密以[金鑰承諾](concepts.md#key-commitment)加密的加密文字。
+ 從最新的 1.*x* 版本轉返到舊版 通常 AWS Encryption SDK 很安全。您可能需要復原對程式碼所做的變更，才能使用先前版本中不支援的符號和物件。
+ 一旦您開始加密 2.0.*x* 版或更新版本中的金鑰承諾 （將承諾政策設定為 `RequireEncryptAllowDecrypt`)，即可轉返至 1.7.*x* 版，但無法轉返至任何較早版本。1.7.*x* AWS Encryption SDK 之前的 版本無法解密以[金鑰承諾](concepts.md#key-commitment)加密的加密文字。
如果您在所有主機都可以使用金鑰承諾解密之前不小心啟用使用金鑰承諾加密，最好繼續進行推出，而不是轉返。如果訊息是暫時性的，或可以安全地捨棄，則您可能會考慮訊息遺失的轉返。如果需要轉返，您可以考慮撰寫工具來解密並重新加密所有訊息。