Troubleshooting migration to the latest versions
Before updating your application to version 2.0.x or later of the AWS Encryption SDK, update to the latest 1.x version of the AWS Encryption SDK and deploy it completely. That will help you avoid most errors you might encounter when updating to versions 2.0.x and later. For detailed guidance, including examples, see Migrating your AWS Encryption SDK.
Important
Verify that your latest 1.x version is version 1.7.x or later of the AWS Encryption SDK.
Note
AWS Encryption CLI: References in this guide to version 1.7.x of the AWS Encryption SDK apply to version 1.8.x of the AWS Encryption CLI. References in this guide to version 2.0.x of the AWS Encryption SDK apply to 2.1.x of the AWS Encryption CLI.
New security features were originally released in AWS Encryption CLI versions 1.7.x and 2.0.x.
However, AWS Encryption CLI version 1.8.x replaces version 1.7.x and AWS Encryption CLI 2.1.x replaces 2.0.x. For details, see the relevant security advisory
This topic is designed to help you recognize and resolve the most common errors you might encounter.
Topics
Deprecated or removed objects
Version 2.0.x includes several breaking changes, including removing legacy constructors, methods, functions, and classes that were deprecated in version 1.7.x. To avoid compiler errors, import errors, syntax errors, and symbol not found errors (depending on your programming language), upgrade first to the latest 1.x version of the AWS Encryption SDK for your programming language. (This must be version 1.7.x or later.) While using the latest 1.x version, you can begin using the replacement elements before the original symbols are removed.
If you need to upgrade to version 2.0.x or later immediately, consult the changelog for your programming language, and replace the legacy symbols with the symbols the changelog recommends.
Configuration conflict: Commitment policy and algorithm suite
If you specify an algorithm suite that conflicts with your commitment policy, the call to encrypt fails with a Configuration conflict error.
To avoid this type of error, don't specify an algorithm suite. By default, the AWS Encryption SDK chooses the most secure algorithm that is compatible with your commitment policy. However, if you must specify an algorithm suite, such as one without signing, be sure to choose an algorithm suite that is compatible with your commitment policy.
| Commitment policy | Compatible algorithm suites |
|---|---|
| ForbidEncryptAllowDecrypt | Any algorithm suite without key commitment, such as: AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384
(03 78) (with signing)
|
| RequireEncryptAllowDecrypt RequireEncryptRequireDecrypt |
Any algorithm suite with key commitment, such as: AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384
(05 78) (with signing)
|
If you encounter this error when you have not specified an algorithm suite, the conflicting algorithm suite might have been chosen by your cryptographic materials manager (CMM). The Default CMM won't select a conflicting algorithm suite, but a custom CMM might. For help, consult the documentation for your custom CMM.
Configuration conflict: Commitment policy and ciphertext
The RequireEncryptRequireDecrypt
commitment policy does not permit the
AWS Encryption SDK to decrypt a message that was encrypted without key commitment. If you ask the AWS Encryption SDK to
decrypt a message without key commitment, it returns a Configuration conflict error.
To avoid this error, before setting the RequireEncryptRequireDecrypt
commitment policy, be sure that all ciphertexts encrypted without key commitment are
decrypted and re-encrypted with key commitment, or handled by a different application.
If you encounter this error, you can return an error for the conflicting ciphertext or
change your commitment policy temporarily to
RequireEncryptAllowDecrypt.
If you are encountering this error because you upgraded to version 2.0.x or later from a version earlier than 1.7.x without first upgrading to the latest 1.x version (version 1.7.x or later), consider rolling back to the latest 1.x version and deploying that version to all hosts before upgrading to version 2.0.x or later. For help, see How to migrate and deploy the AWS Encryption SDK.
Key commitment validation failed
When you decrypt messages that are encrypted with key commitment, you might get a Key commitment validation failed error message. This indicates that the decrypt call failed because a data key in an encrypted message is not identical to the unique data key for the message. By validating the data key during decryption, key commitment protects you from decrypting a message that might result in more than one plaintext.
This error indicates that the encrypted message that you were trying to decrypt was not returned by the AWS Encryption SDK. It might be a manually crafted message or the result of data corruption. If you encounter this error, your application can reject the message and continue, or stop processing new messages.
Other encryption failures
Encryption can fail for multiple reasons. You cannot use an AWS KMS discovery keyring or a master key provider in discovery mode to encrypt a message.
Be sure that you specify a keyring or master key provider with wrapping keys that you have permission to use for encryption. For help with permissions on AWS KMS keys, see Viewing a key policy and Determining access to an AWS KMS key in the AWS Key Management Service Developer Guide.
Other decryption failures
If your attempt to decrypt an encrypted message fails, it means that the AWS Encryption SDK could not (or would not) decrypt any of the encrypted data keys in the message.
If you used a keyring or master key provider that specifies wrapping keys, the AWS Encryption SDK uses only
the wrapping keys you specify. Verify that you are using the wrapping keys that you
intend and that you have kms:Decrypt permission on at least one of the
wrapping keys. If you are using AWS KMS keys, as a fallback, you can try decrypting the
message with an AWS KMS discovery keyring or
a master key provider in discovery mode. If the operation
succeeds, before returning the plaintext, verify that the key used to decrypt the
message is one that you trust.
Rollback considerations
If your application is failing to encrypt or decrypt data, you can usually resolve the problem by updating the code symbols, keyrings, master key providers, or commitment policy. However, in some cases, you might decide that it's best to roll back your application to a previous version of the AWS Encryption SDK.
If you must roll back, do so with caution. Versions of the AWS Encryption SDK prior to 1.7.x cannot decrypt ciphertext encrypted with key commitment.
-
Rolling back from the latest 1.x version to a previous version of the AWS Encryption SDK is generally safe. You might have to undo changes you made to your code to use symbols and objects that are not supported in previous versions.
-
Once you have begun encrypting with key commitment (setting your commitment policy to
RequireEncryptAllowDecrypt) in version 2.0.x or later, you can roll back to version 1.7.x, but not to any earlier version. Versions of the AWS Encryption SDK prior to 1.7.x cannot decrypt ciphertext encrypted with key commitment.
If you accidentally enable encrypting with key commitment before all hosts can decrypt with key commitment, it might be best to continue with the roll out rather than to roll back. If messages are transient or can be safely dropped, then you might consider a rollback with loss of messages. If a rollback is required, you might consider writing a tool that decrypts and re-encrypts all messages.
