Frequently asked questions - AWS Encryption SDK

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), including AWS Key Management Service (AWS KMS). Some of the language implementations of the AWS Encryption SDK, such as the AWS Encryption SDK for .NET, always require the AWS SDK in the same programming language. Other language implementations require the corresponding AWS SDK only when you use AWS KMS keys in your keyrings or master key providers. For details, see the topic about your programming language in AWS Encryption SDK programming languages.

You can use the AWS SDKs to interact with AWS KMS, including encrypting and decrypting small amounts of data (up to 4,096 bytes with a symmetric encryption key) and generating data keys for client-side encryption. However, when you generate a data key, you must manage the entire encryption and decryption process, including encrypting your data with the data key outside of AWS KMS, safely discarding the plaintext data key, storing the encrypted data key, and then decrypting the data key and decrypting your data. The AWS Encryption SDK handles this process for you.

The AWS Encryption SDK provides a library that encrypts and decrypts data using industry standards and best practices. It generates the data key, encrypts it under the wrapping keys you specify, and returns an encrypted message, a portable data object that includes the encrypted data and the encrypted data keys you need to decrypt it. When it's time to decrypt, you pass in the encrypted message and at least one of the wrapping keys (optional), and the AWS Encryption SDK returns your plaintext data.

You can use AWS KMS keys as wrapping keys in the AWS Encryption SDK, but it is not required. You can use encryption keys that you generate and those from your key manager or on-premises hardware security module. You can use the AWS Encryption SDK even if you don't have an AWS account.

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

The Amazon S3 encryption client in the AWS SDKs 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) symmetric algorithm in Galois/Counter Mode (GCM), known as AES-GCM, to encrypt your data. It lets you choose from several symmetric and asymmetric algorithms to encrypt the data keys that encrypt your data.

For AES-GCM, the default algorithm suite is AES-GCM with a 256-bit key, key derivation (HKDF), digital signatures, and key commitment. AWS Encryption SDK also supports 192-bit, and 128-bit encryption keys and encryption algorithms without digital signatures and key commitment.

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?

The AWS Encryption SDK uses a deterministic method to construct a different IV value for each frame. This procedure guarantees that IVs are never repeated within a message. (Prior to version 1.3.0 of the AWS Encryption SDK for Java and the AWS Encryption SDK for Python, the AWS Encryption SDK randomly generated a unique IV value for each frame.)

The IV is stored in the encrypted message that the AWS Encryption SDK returns. For more information, see the AWS Encryption SDK message format reference.

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

The method depends on the keyring or master key provider you use.

The AWS KMS keyrings and master key providers in the AWS Encryption SDK use the AWS KMS GenerateDataKey API operation to generate each data key and encrypt it under its wrapping key. To encrypt copies of the data key under additional KMS keys, they use the AWS KMS Encrypt operation. To decrypt the data keys, they use the AWS KMS Decrypt operation. For details, see AWS KMS keyring in the AWS Encryption SDK Specification in GitHub.

Other keyrings generate the data key, encrypt, and decrypt using best practice methods for each programming language. For details, see the specification of the keyring or master key provider in the Framework section of the AWS Encryption SDK Specification in GitHub.

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. The message header contains the encrypted data keys and information about how the message body is formed. The message body contains the encrypted data. If the algorithm suite includes a digital signature, the message format includes a footer that contains the signature. For more information, see AWS Encryption SDK message format reference.

How much overhead does the AWS Encryption SDK 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 wrapping keys or master keys

  • The frame size (when framed data is used)

When you use the AWS Encryption SDK with its default configuration (one AWS KMS key as the wrapping key (or master key), no AAD, nonframed data, and an encryption algorithm with signing), 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, keyrings, master keys, and wrapping keys.

Can I encrypt data under more than one wrapping key?

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

To encrypt data under multiple wrapping keys, create a keyring or master key provider with multiple wrapping keys. When working with keyrings, you can create a single keyring with multiple wrapping keys or a multi-keyring.

When you encrypt data with multiple wrapping keys, the AWS Encryption SDK uses one wrapping key to generate a plaintext data key. The data key is unique and mathematically unrelated to the wrapping key. The operation returns the plaintext data key and a copy of the data key encrypted by the wrapping key. Then the encryption method, encrypts the data key with the other wrapping keys. The resulting encrypted message includes the encrypted data and one encrypted data key for each wrapping key.

The encrypted message can be decrypted by using any one of the wrapping keys used in the encryption operation. The AWS Encryption SDK uses a wrapping key to decrypt an encrypted data key. Then, it uses the plaintext data key to decrypt the data.

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

Most programming language implementations of the AWS Encryption SDK can encrypt raw bytes (byte arrays), I/O streams (byte streams), and strings. The AWS Encryption SDK for .NET does not support I/O streams. 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 that supports streaming.

The AWS Encryption SDK for .NET does not support I/O streams.