What is the AWS Encryption SDK? - AWS Encryption SDK
Developed in open-source repositoriesCompatibility with encryption libraries and servicesSupport and maintenanceLearning moreSending feedback

What is the AWS Encryption SDK?

The AWS Encryption SDK is a client-side encryption library designed to make it easy for everyone to encrypt and decrypt data using industry standards and best practices. It enables you to focus on the core functionality of your application, rather than on how to best encrypt and decrypt your data. The AWS Encryption SDK is provided free of charge under the Apache 2.0 license.

The AWS Encryption SDK answers questions like the following for you:

  • Which encryption algorithm should I use?

  • How, or in which mode, should I use that algorithm?

  • How do I generate the encryption key?

  • How do I protect the encryption key, and where should I store it?

  • How can I make my encrypted data portable?

  • How do I ensure that the intended recipient can read my encrypted data?

  • How can I ensure my encrypted data is not modified between the time it is written and when it is read?

  • How do I use the data keys that AWS KMS returns?

With the AWS Encryption SDK, you define a master key provider (Python) or a keyring (C, C#/.NET, Java, and JavaScript) that determines which wrapping keys you use to protect your data. Then you encrypt and decrypt your data using straightforward methods provided by the AWS Encryption SDK. The AWS Encryption SDK does the rest.

Without the AWS Encryption SDK, you might spend more effort on building an encryption solution than on the core functionality of your application. The AWS Encryption SDK answers these questions by providing the following things.

A default implementation that adheres to cryptography best practices

By default, the AWS Encryption SDK generates a unique data key for each data object that it encrypts. This follows the cryptography best practice of using unique data keys for each encryption operation.

The AWS Encryption SDK encrypts your data using a secure, authenticated, symmetric key algorithm. For more information, see Supported algorithm suites in the AWS Encryption SDK.

A framework for protecting data keys with wrapping keys

The AWS Encryption SDK protects the data keys that encrypt your data by encrypting them under one or more wrapping keys. By providing a framework to encrypt data keys with more than one wrapping key, the AWS Encryption SDK helps make your encrypted data portable.

For example, encrypt data under an AWS KMS key in AWS KMS and a key from your on-premises HSM. You can use either of the wrapping keys to decrypt the data, in case one is unavailable or the caller doesn't have permission to use both keys.

A formatted message that stores encrypted data keys with the encrypted data

The AWS Encryption SDK stores the encrypted data and encrypted data key together in an encrypted message that uses a defined data format. This means you don't need to keep track of or protect the data keys that encrypt your data because the AWS Encryption SDK does it for you.

Some language implementations of the AWS Encryption SDK require an AWS SDK, but the AWS Encryption SDK doesn't require an AWS account and it doesn't depend on any AWS service. You need an AWS account only if you choose to use AWS KMS keys to protect your data.

Developed in open-source repositories

The AWS Encryption SDK is developed in open-source repositories on GitHub. You can use these repositories to view the code, read and submit issues, and find information that is specific to your language implementation.

Compatibility with encryption libraries and services

The AWS Encryption SDK is supported in several programming languages. All language implementations are interoperable. You can encrypt with one language implementation and decrypt with another. Interoperability might be subject to language constraints. If so, these constraints are described in the topic about the language implementation. Also, when encrypting and decrypting, you must use compatible keyrings, or master keys and master key providers. For details, see Keyring compatibility.

However, the AWS Encryption SDK cannot interoperate with other libraries. Because each library returns encrypted data in a different format, you cannot encrypt with one library and decrypt with another.

DynamoDB Encryption Client and Amazon S3 client-side encryption

The AWS Encryption SDK cannot decrypt data encrypted by the DynamoDB Encryption Client or Amazon S3 client-side encryption. These libraries cannot decrypt the encrypted message the AWS Encryption SDK returns. 

AWS Key Management Service (AWS KMS)

The AWS Encryption SDK can use AWS KMS keys and data keys to protect your data, including multi-Region KMS keys. For example, you can configure the AWS Encryption SDK to encrypt your data under one or more AWS KMS keys in your AWS account. However, you must use the AWS Encryption SDK to decrypt that data.

The AWS Encryption SDK cannot decrypt the ciphertext that the AWS KMS Encrypt or ReEncrypt operations return. Similarly, the AWS KMS Decrypt operation cannot decrypt the encrypted message the AWS Encryption SDK returns.

The AWS Encryption SDK supports only symmetric encryption KMS keys. You cannot use an asymmetric KMS key for encryption or signing in the AWS Encryption SDK. The AWS Encryption SDK generates its own ECDSA signing keys for algorithm suites that sign messages.

Support and maintenance

The AWS Encryption SDK uses the same maintenance policy that the AWS SDK and Tools use, including its versioning and life-cycle phases. As a best practice, we recommend that you use the latest available version of the AWS Encryption SDK for your programming language, and upgrade as new versions are released. When a version requires significant changes, such as the upgrade from AWS Encryption SDK versions earlier than 1.7.x to versions 2.0.x and later, we provide detailed instructions to help you.

Each programming language implementation of the AWS Encryption SDK is developed in a separate open-source GitHub repository. The life-cycle and support phase of each version is likely to vary among repositories. For example, a given version of the AWS Encryption SDK might be in the general availability (full support) phase in one programming language, but the end-of-support phase in a different programming language. We recommend that you use a fully supported version whenever possible and avoid versions that are no longer supported.

To find the life-cycle phase of AWS Encryption SDK versions for your programming language, see the SUPPORT_POLICY.rst file in each AWS Encryption SDK repository.

For more information, see Versions of the AWS Encryption SDK and AWS SDKs and Tools maintenance policy in the AWS SDKs and Tools Reference Guide.

Learning more

For more information about the AWS Encryption SDK and client-side encryption, try these sources.

For information about implementations of the AWS Encryption SDK in different programming languages.

Sending feedback

We welcome your feedback! If you have a question or comment, or an issue to report, please use the following resources.

  • If you discover a potential security vulnerability in the AWS Encryption SDK, please notify AWS security. Do not create a public GitHub issue.

  • To provide feedback on the AWS Encryption SDK, file an issue in the GitHub repository for the programming language you are using.

  • To provide feedback on this documentation, use the Feedback links on this page. You can also file an issue or contribute to aws-encryption-sdk-docs, the open-source repository for this documentation on GitHub.