Migrating to AWS Encryption SDK Versions 2.0.x and later - AWS Encryption SDK

Migrating to AWS Encryption SDK Versions 2.0.x and later

The AWS Encryption SDK supports multiple interoperable programming language implementations, each of which is developed in an open-source repository on GitHub. As a best practice, we recommend that you use the latest version of the AWS Encryption SDK for each language. However, the 2.0.x version of the AWS Encryption SDK introduces significant new security features, some of which are breaking changes. To provide a safe upgrade path from versions earlier than 1.7.x to versions 2.0.x and later, we provide a transition version, 1.7.x, in each programming language. The topics in this section are designed to help you understand the changes, select the correct version for your application, and migrate safely and successfully to the newest versions of the AWS Encryption SDK.

For information about significant versions of the AWS Encryption SDK, see Versions of the AWS Encryption SDK.

Important

Do not upgrade directly from a version earlier than 1.7.x to version 2.0.x or later without first upgrading to version 1.7.x. If you upgrade directly to version 2.0.x or later and enable all new features immediately, the AWS Encryption SDK won't be able to decrypt ciphertext encrypted under older versions of the AWS Encryption SDK.

Note

The earliest version of the AWS Encryption SDK for .NET is version 3.0.x. You do not need to update or migrate to another version if you are using this library.

AWS Encryption CLI: When reading this migration guide, use the 1.7.x migration instructions for AWS Encryption CLI 1.8.x and use the 2.0.x migration instructions for AWS Encryption CLI 2.1.x. For details, see .

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 in the aws-encryption-sdk-cli repository on GitHub.

New users

If you're new to the AWS Encryption SDK, start with the latest version of the AWS Encryption SDK for your programming language. The default values enable all security features of the AWS Encryption SDK, including encryption with signing, key derivation, and key commitment. of the AWS Encryption SDK

Current users

We recommend that you upgrade from your current version to the newest available version as soon as possible. AWS Encryption SDK versions 2.0.x and later provide new security features to help protect your data.

However, AWS Encryption SDK version 2.0.x includes breaking changes that are not backwards compatible. To assure a safe transition, begin by migrating from your current version to version 1.7.x. When version 1.7.x is fully deployed and operating successfully, you can safely migrate to version 2.0.x. This two-step process is critical especially for distributed applications.

For more information about the AWS Encryption SDK security features that underlie these changes, see Improved client-side encryption: Explicit KeyIds and key commitment in the AWS Security Blog.

Looking for help with using the AWS Encryption SDK for Java with the AWS SDK for Java 2.x? See Prerequisites.