AWS Encryption SDK
Developer Guide

Frequently Asked Questions

How is the AWS Encryption SDK different from the AWS SDKs?

The AWS SDKs provide libraries for interacting with Amazon Web Services (AWS). They integrate with AWS Key Management Service (AWS KMS) to generate, encrypt, and decrypt data keys. However, in most cases you can't use them to directly encrypt or decrypt raw data.

The AWS Encryption SDK provides an encryption library that optionally integrates with AWS KMS as a master key provider. The AWS Encryption SDK builds on the AWS SDKs to do the following things:

  • Generate, encrypt, and decrypt data keys

  • Use those data keys to encrypt and decrypt your raw data

  • Store the encrypted data keys with the corresponding encrypted data in a single object

You can also use the AWS Encryption SDK with no AWS integration by defining a custom master key provider.

How is the AWS Encryption SDK different from the Amazon S3 encryption client?

The Amazon S3 encryption client in the AWS SDK for Java, AWS SDK for Ruby, and AWS SDK for .NET provides encryption and decryption for data that you store in Amazon Simple Storage Service (Amazon S3). These clients are tightly coupled to Amazon S3 and are intended for use only with data stored there.

The AWS Encryption SDK provides encryption and decryption for data that you can store anywhere. The AWS Encryption SDK and the Amazon S3 encryption client are not compatible because they produce ciphertexts with different data formats.

Which cryptographic algorithms are supported by the AWS Encryption SDK, and which one is the default?

The AWS Encryption SDK uses the Advanced Encryption Standard (AES) algorithm in Galois/Counter Mode (GCM), known as AES-GCM. The SDK supports 256-bit, 192-bit, and 128-bit encryption keys. In all cases, the length of the initialization vector (IV) is 12 bytes; the length of the authentication tag is 16 bytes. By default, the SDK uses the data key as an input to the HMAC-based extract-and-expand key derivation function (HKDF) to derive the AES-GCM encryption key, and also adds an Elliptic Curve Digital Signature Algorithm (ECDSA) signature.

For information about choosing which algorithm to use, see Supported Algorithm Suites.

For implementation details about the supported algorithms, see Algorithms Reference.

How is the initialization vector (IV) generated and where is it stored?

In previous releases, the AWS Encryption SDK randomly generated a unique IV value for each encryption operation. The SDK now uses a deterministic method to construct a different IV value for each frame so that every IV is unique within its message. The SDK stores the IV in the encrypted message that it returns. For more information, see AWS Encryption SDK Message Format Reference.

How is each data key generated, encrypted, and decrypted?

The method depends on the master key provider and the implementation of its master keys. When AWS KMS is the master key provider, the SDK uses the AWS KMS GenerateDataKey API operation to generate each data key in both plaintext and encrypted forms. It uses the Decrypt operation to decrypt the data key. AWS KMS encrypts and decrypts the data key by using the customer master key (CMK) that you specified when configuring the master key provider.

How do I keep track of the data keys that were used to encrypt my data?

The AWS Encryption SDK does this for you. When you encrypt data, the SDK encrypts the data key and stores the encrypted key along with the encrypted data in the encrypted message that it returns. When you decrypt data, the AWS Encryption SDK extracts the encrypted data key from the encrypted message, decrypts it, and then uses it to decrypt the data.

How does the AWS Encryption SDK store encrypted data keys with their encrypted data?

The encryption operations in the AWS Encryption SDK return an encrypted message, a single data structure that contains the encrypted data and its encrypted data keys. The message format consists of at least two parts: a header and a body. In some cases, the message format consists of a third part known as a footer. The message header contains the encrypted data keys and information about how the message body is formed. The message body contains the encrypted data. The message footer contains a signature that authenticates the message header and message body. For more information, see AWS Encryption SDK Message Format Reference.

How much overhead does the AWS Encryption SDK's message format add to my encrypted data?

The amount of overhead added by the AWS Encryption SDK depends on several factors, including the following:

  • The size of the plaintext data

  • Which of the supported algorithms is used

  • Whether additional authenticated data (AAD) is provided, and the length of that AAD

  • The number and type of master key providers

  • The frame size (when framed data is used)

When you use the AWS Encryption SDK with its default configuration, with one CMK in AWS KMS as the master key, with no AAD, and encrypt nonframed data, the overhead is approximately 600 bytes. In general, you can reasonably assume that the AWS Encryption SDK adds overhead of 1 KB or less, not including the provided AAD. For more information, see AWS Encryption SDK Message Format Reference.

Can I use my own master key provider?

Yes. The implementation details vary depending on which of the supported programming languages you use. However, all supported languages allow you to define custom cryptographic materials managers (CMMs), master key providers, and master keys.

Can I encrypt data under more than one master key?

Yes. You can encrypt the data key with additional master keys to add redundancy in case a master key is in a different region or is unavailable for decryption.

To encrypt data under multiple master keys, create a master key provider with multiple master keys. You can see examples of this pattern in the example code for Java and Python.

When you encrypt data by using a master key provider that returns multiple master keys, the AWS Encryption SDK encrypts the data that you pass to the encryption methods with a data key and encrypts that data key with the same master key. Then, it encrypts the data with the other master keys that the master key provider returned. The resulting message includes the encrypted data and one encrypted data key for each master key. The resulting message can be decrypted by using any one of the master keys used in the encryption operation.

Which data types can I encrypt with the AWS Encryption SDK?

The AWS Encryption SDK can encrypt raw bytes (byte arrays), I/O streams (byte streams), and strings. We provide example code for each of the supported programming languages.

How does the AWS Encryption SDK encrypt and decrypt input/output (I/O) streams?

The AWS Encryption SDK creates an encrypting or decrypting stream that wraps an underlying I/O stream. The encrypting or decrypting stream performs a cryptographic operation on a read or write call. For example, it can read plaintext data on the underlying stream and encrypt it before returning the result. Or it can read ciphertext from an underlying stream and decrypt it before returning the result. We provide example code for encrypting and decrypting streams for each of the supported programming languages.