C C# / .NET Command line interface (CLI)Java Go JavaScript Python Rust Version details

Versions of the AWS Encryption SDK

The AWS Encryption SDK language implementations use semantic versioning to make it easier for you to identify the magnitude of changes in each release. A change in the major version number, such as 1.x.x to 2.x.x, indicates a breaking change that is likely to require code changes and a planned deployment. Breaking changes in a new version might not impact every use case, review the release notes to see if you're impacted. A change in a minor version, such as x.1.x to x.2.x, is always backward compatible, but might include deprecated elements.

Whenever possible, use the latest version of the AWS Encryption SDK in your chosen programming language. The maintenance and support policy for each version differs between programming language implementations. For details about the supported versions in your preferred programming language, see the SUPPORT_POLICY.rst file in its GitHub repository.

When upgrades include new features that require special configuration to avoid encryption or decryption error, we provide an intermediate version and detailed instructions for using it. For example, versions 1.7.x and 1.8.x are designed to be transitional versions that help you upgrade from versions earlier than 1.7.x to versions 2.0.x and later. For details, see Migrating your AWS Encryption SDK.

Note

The x in a version number represents any patch of the major and minor version. For example, version 1.7.x represents all versions that begin with 1.7, including 1.7.1 and 1.7.9.

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.

The following tables provide an overview of the major differences between supported versions of the AWS Encryption SDK for each programming language.

C

For a detailed description of all changes, see the CHANGELOG.md in the aws-encryption-sdk-c repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	End-of-Support phase
1.x	1.7	Updates to the AWS Encryption SDK that help users of earlier versions upgrade to versions 2.0.x and later. For more information, see version 1.7.x.	End-of-Support phase
2.x	2.0	Updates to the AWS Encryption SDK. For more information, see version 2.0.x.	General Availability (GA)
	2.2	Improvements to the message decryption process.
	2.3	Adds support for AWS KMS multi-Region keys.

C# / .NET

For a detailed description of all changes, see the CHANGELOG.md in the aws-encryption-sdk-net repository on GitHub.

Major version	Details	SDK major version life-cycle phase
3.x	3.1.0	Initial release.	End-of-Support Version 3.x of the AWS Encryption SDK for .NET has entered End of Support; please, upgrade to 4.x.
4.x	4.0	Adds support for the AWS KMS Hierarchical keyring, the required encryption context CMM, and asymmetric RSA AWS KMS keyrings.	General Availability (GA)
5.x	5.0	Updates to version 2.x of the Material Providers Library (MPL). Drops support for the AWS SDK for .NET v3 and requires the AWS SDK for .NET v4.	General Availability (GA)

Major version

Details

SDK major version life-cycle phase

3.x

3.1.0

Initial release.

End-of-Support

Version 3.x of the AWS Encryption SDK for .NET has entered End of Support; please, upgrade to 4.x.

4.x

4.0

Adds support for the AWS KMS Hierarchical keyring, the required encryption context CMM, and asymmetric RSA AWS KMS keyrings.

General Availability (GA)

5.x

5.0

Updates to version 2.x of the Material Providers Library (MPL). Drops support for the AWS SDK for .NET v3 and requires the AWS SDK for .NET v4.

General Availability (GA)

Command line interface (CLI)

For a detailed description of all changes, see Versions of the AWS Encryption CLI and the CHANGELOG.rst in the aws-encryption-sdk-cli repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	End-of-Support phase
1.x	1.7	Updates to the AWS Encryption SDK that help users of earlier versions upgrade to versions 2.0.x and later. For more information, see version 1.7.x.	End-of-Support phase
2.x	2.0	Updates to the AWS Encryption SDK. For more information, see version 2.0.x.	End-of-Support phase
	2.1	Removes the `--discovery` parameter and replaces it with the `discovery` attribute of the `--wrapping-keys` parameter. Version 2.1.0 of the AWS Encryption CLI is equivalent to version 2.0 in other programming languages.
	2.2	Improvements to the message decryption process.
3.x	3.0	Adds support for AWS KMS multi-Region keys.	End-of-Support phase
4.x	4.0	The AWS Encryption CLI no longer supports Python 2 or Python 3.4. As of major version 4.x of the AWS Encryption CLI, only Python 3.5 or later is supported.	General Availability (GA)
	4.1	The AWS Encryption CLI no longer supports Python 3.5. As of version 4.1.x of the AWS Encryption CLI, only Python 3.6 or later is supported.
	4.2	The AWS Encryption CLI no longer supports Python 3.6. As of version 4.2.x of the AWS Encryption CLI, only Python 3.7 or later is supported.

Java

For a detailed description of all changes, see the CHANGELOG.rst in the aws-encryption-sdk-java repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	End-of-Support phase
	1.3	Adds support for cryptographic materials manager and data key caching. Moved to deterministic IV generation.
	1.6.1	Deprecates `AwsCrypto.encryptString()` and `AwsCrypto.decryptString()` and replaces them with `AwsCrypto.encryptData()` and `AwsCrypto.decryptData()`.
	1.7	Updates to the AWS Encryption SDK that help users of earlier versions upgrade to versions 2.0.x and later. For more information, see version 1.7.x.
2.x	2.0	Updates to the AWS Encryption SDK. For more information, see version 2.0.x.	General Availability (GA) Version 2.x of the AWS Encryption SDK for Java will enter maintenance mode in 2024.
	2.2	Improvements to the message decryption process.
	2.3	Adds support for AWS KMS multi-Region keys.
	2.4	Adds support for AWS SDK for Java 2.x.
3.x	3.0	Integrates the AWS Encryption SDK for Java with the Material Providers Library (MPL). Adds support for symmetric and asymmetric RSA AWS KMS keyrings, AWS KMS ECDH keyrings, AWS KMS Hierarchical keyrings, Raw AES keyrings, Raw RSA keyrings, Raw ECDH keyrings, Multi-keyrings, and the required encryption context CMM.	General Availability (GA)

Go

For a detailed description of all changes, see the CHANGELOG.md in the Go directory of the aws-encryption-sdk repository on GitHub.

Major version	Details		SDK major version life-cycle phase
0.1.x	0.1.0	Initial release.	General Availability (GA)

JavaScript

For a detailed description of all changes, see the CHANGELOG.md in the aws-encryption-sdk-javascript repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	End-of-Support phase
1.x	1.7	Updates to the AWS Encryption SDK that help users of earlier versions upgrade to versions 2.0.x and later. For more information, see version 1.7.x.	End-of-Support phase
2.x	2.0	Updates to the AWS Encryption SDK. For more information, see version 2.0.x.	End-of-Support phase
	2.2	Improvements to the message decryption process.
	2.3	Adds support for AWS KMS multi-Region keys.
3.x	3.0	Removes CI coverage for Node 10. Upgrades dependencies to no longer support Node 8 and Node 10.	Maintenance Support for version 3.x of the AWS Encryption SDK for JavaScript will end on January 17, 2024.
4.x	4.0	Requires version 3 of the AWS Encryption SDK for JavaScript's `kms-client` to use the AWS KMS keyring.	General Availability (GA)

Python

For a detailed description of all changes, see the CHANGELOG.rst in the aws-encryption-sdk-python repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	End-of-Support phase
	1.3	Adds support for cryptographic materials manager and data key caching. Moved to deterministic IV generation.
	1.7	Updates to the AWS Encryption SDK that help users of earlier versions upgrade to versions 2.0.x and later. For more information, see version 1.7.x.
2.x	2.0	Updates to the AWS Encryption SDK. For more information, see version 2.0.x.	End-of-Support phase
	2.2	Improvements to the message decryption process.
	2.3	Adds support for AWS KMS multi-Region keys.
3.x	3.0	The AWS Encryption SDK for Python no longer supports Python 2 or Python 3.4. As of major version 3.x of the AWS Encryption SDK for Python, only Python 3.5 or later is supported.	General Availability (GA)
4.x	4.0	Integrates the AWS Encryption SDK for Python with the Material Providers Library (MPL).	General Availability (GA)

Rust

For a detailed description of all changes, see the CHANGELOG.md in the Rust directory of the aws-encryption-sdk repository on GitHub.

Major version	Details		SDK major version life-cycle phase
1.x	1.0	Initial release.	General Availability (GA)

Version details

The following list describes the major differences between supported versions of the AWS Encryption SDK.

Versions earlier than 1.7.x

Note

All 1.x.x versions of the AWS Encryption SDK are in the end-of-support phase. Upgrade to the latest available version of the AWS Encryption SDK for your programming language as soon as is practical. To upgrade from an AWS Encryption SDK version earlier than 1.7.x, you must first upgrade to 1.7.x. For details, see Migrating your AWS Encryption SDK.

Versions of the AWS Encryption SDK earlier than 1.7.x provide important security features, including encryption with the Advanced Encryption Standard algorithm in Galois/Counter Mode (AES-GCM), an HMAC-based extract-and-expand key derivation function (HKDF), signing, and a 256-bit encryption key. However, these versions don't support best practices that we recommend, including key commitment.

Show less

Version 1.7.x

Note

All 1.x.x versions of the AWS Encryption SDK are in the end-of-support phase.

Version 1.7.x is designed to help users of earlier versions of the AWS Encryption SDK to upgrade to versions 2.0.x and later. If you are new to the AWS Encryption SDK, you can skip this version and begin with the latest available version in your programming language.

Version 1.7.x is fully backward compatible; it does not introduce any breaking changes or change the behavior of the AWS Encryption SDK. It's also forwards compatible; it allows you to update your code so it's compatible with version 2.0.x. It includes new features, but doesn't fully enable them. And it requires configuration values that prevent you from immediately adopting all new features until you are ready.

Version 1.7.x includes the following changes:

AWS KMS master key provider updates (required)

Version 1.7.x introduces new constructors to the AWS Encryption SDK for Java and AWS Encryption SDK for Python that explicitly create AWS KMS master key providers in either strict or discovery mode. This version adds similar changes to the AWS Encryption SDK command-line interface (CLI). For details, see Updating AWS KMS master key providers.

In strict mode, AWS KMS master key providers require a list of wrapping keys, and they encrypt and decrypt with only the wrapping keys you specify. This is an AWS Encryption SDK best practice that assures that you are using the wrapping keys you intend to use.
In discovery mode, AWS KMS master key providers do not take any wrapping keys. You cannot use them for encrypting. When decrypting, they can use any wrapping key to decrypt an encrypted data key. However, you can limit the wrapping keys used for decryption to those in particular AWS accounts. Account filtering is optional, but it's a best practice that we recommend.

The constructors that create earlier versions of AWS KMS master key providers are deprecated in version 1.7.x and removed in version 2.0.x. These constructors instantiate master key providers that encrypt using the wrapping keys you specify. However, they decrypt encrypted data keys using the wrapping key that encrypted them, without regard to the specified wrapping keys. Users might unintentionally decrypt messages with wrapping keys they don't intend to use, including AWS KMS keys in other AWS accounts and Regions.

There are no changes to constructors for AWS KMS master keys. When encrypting and decrypting, AWS KMS master keys use only the AWS KMS key that you specify.

AWS KMS keyring updates (optional)

Version 1.7.x adds a new filter to the AWS Encryption SDK for C and AWS Encryption SDK for JavaScript implementations that limits AWS KMS discovery keyrings to particular AWS accounts. This new account filter is optional, but it's a best practice that we recommend. For details, see Updating AWS KMS keyrings.

There are no changes to constructors for AWS KMS keyrings. Standard AWS KMS keyrings behave like master key providers in strict mode. AWS KMS discovery keyrings are created explicitly in discovery mode.

Passing a key ID to AWS KMS Decrypt

Beginning in version 1.7.x, when decrypting encrypted data keys, the AWS Encryption SDK always specifies an AWS KMS key in its calls to the AWS KMS Decrypt operation. The AWS Encryption SDK gets the key ID value for the AWS KMS key from the metadata in each encrypted data key. This feature doesn't require any code changes.

Specifying the key ID of the AWS KMS key is not required to decrypt ciphertext that was encrypted under a symmetric encryption KMS key, but it is an AWS KMS best practice. Like specifying wrapping keys in your key provider, this practice assures that AWS KMS only decrypts using the wrapping key you intend to use.