AWS Encryption SDK
Developer Guide

Concepts in the AWS Encryption SDK

This section introduces the concepts used in the AWS Encryption SDK. The Encryption SDK is designed so that you can use the default implementations of the components without detailed knowledge about their functionality. This section is provided as a glossary and reference.

Data Keys

A data key consists of cryptographic material. It is the secret key that protects the data that you encrypt.

Data keys are generated by master keys. You do not need to implement or extend data keys to use the AWS Encryption SDK. When a master key generates a data key, it returns two copies of the data key; one in plaintext and one that is encrypted by the master key that generated it. The plaintext data key can be encrypted by multiple master keys, each of which returns an encrypted copy of the data key. Every encrypted data key is associated with the master key that encrypted it and the master key provider that supplied the master key.

When you encrypt data in the AWS Encryption SDK, the encrypted data keys are stored in an encrypted message along with the encrypted data.

In the Encryption SDK, we distinguish data keys from data encryption keys. Several of the supported algorithm suites, including the default suite, use a key derivation function that prevents the data key from hitting its cryptographic limits. The key derivation function takes the data key as input and returns a data encryption key that is actually used to encrypt the data. For this reason, we often say that data is encrypted "under" a data key rather than "by" the data key.

Master key

A master key encrypts, decrypts, and generates data keys.

The AWS Encryption SDK represents master keys as abstract classes or interfaces so you can implement the master key operations in the way that best meets the security requirements of your organization. For example, although they are called "keys," master keys might not have their own cryptographic material. Also, unlike data keys, whose use and algorithm suite are strictly defined by AWS Encryption SDK, master keys can use any algorithm suite or implementation.

Master keys are instrumental to envelope encryption. In envelope encryption, one master key generates and encrypts a data key that is used to encrypt data. Other master keys then re-encrypt the plaintext data key. As a result, any master key is sufficient to decrypt the data.

Each master key is associated with one master key provider that returns one or more master keys to the caller.

The AWS Encryption SDK provides several commonly used master keys, such as AWS Key Management Service (AWS KMS) customer master keys (CMKs), raw AES-GCM (Advanced Encryption Standard / Galois Counter Mode) keys, and RSA keys. You can implement your own master keys for other cryptographic algorithms and services. For example, you could implement master keys backed by implementations of Elliptical Curve Integrated Encryption Scheme (ECIES), Key Management Interoperability Program (KMIP), tokenization services, or other proprietary systems.

Master key operations: Generate, Encrypt, Decrypt

Master keys in the AWS Encryption SDK generate, encrypt, and decrypt data keys. You write methods to perform these operations when you create a master key, but your application does not call the methods directly. The SDK calls them when you ask it to encrypt or decrypt data.

You can implement the master key methods in the way that works best for your organization. For example, when asked to generate a data key, a master key can create or return a key in any way that fulfills the requirements of the algorithm suite that they use. Master keys can generate data keys locally or remotely. They can derive the keys algorithmically, call a service that generates the cryptographic material, or return previously-generated data keys. The SDK requires only that they return a valid data key object.

Also, although master keys must implement all three methods, you can create master keys that actually perform only one or two of the three operations. Calls to the remaining methods just fail or return errors. These limited master keys might be useful in a system with strict access controls that do not let the same users encrypt and decrypt data.

All master key operations take an encryption context as input. For optimal security, master key operations that encrypt data keys should cryptographically bind the encryption context to the encrypted data so that changing any key or value in the encryption context invalidates the encryption. Master key operations that decrypt should verify the encryption context and fail unless they include the same encryption context used to encrypt. The encryption context is most useful when there are users who have permission to decrypt, but not encrypt.

Master key provider

A master key provider returns objects that represent master keys. Each master key is associated with one master key provider, but a master key provider typically provides multiple master keys.

The simplest master key provider always returns the same master key. In fact, master keys are implemented as master keys providers that only return themselves. More complex master key providers might use key rotation, the encryption context, application permissions, and other factors to select master keys from among the set they can provide.

Many master keys providers wrap or extend other master key providers to customize their behavior and functionality. For example, a custom master key provider might select a master key provider from a collection, delegate requests, and combine their results.

Cryptographic Materials Manager

The cryptographic materials manager (CMM) gets the cryptographic materials that are used to encrypt and decrypt data. The cryptographic materials include plaintext and encrypted data keys, and an optional message signing key. You can use the Default CMM that the AWS Encryption SDK provides (DefaultCryptoMaterialsManager) or write a custom CMM.

Each Default CMM is associated with a master key provider. When it gets a materials request, the Default CMM gets master keys from its master key provider and uses them to generate the requested cryptographic material. This might involve a call to a cryptographic service, such as AWS Key Management Service (AWS KMS).

In each call to encrypt or decrypt data, you specify a CMM or a master key provider. This lets you choose a particular set of master keys for the operation. You can create a CMM explicitly and specify its master key provider, but that is not required. If you specify a master key provider in an encryption request, the SDK creates a Default CMM for the master key provider.

Because the CMM acts as a liaison between the SDK and a master key provider, it is an ideal point for customization and extension, such as support for policy enforcement and caching.

Algorithm Suite

The AWS Encryption SDK supports several algorithm suites, all of which use Advanced Encryption Standard (AES) as the primary algorithm, and combine it with other algorithm and values.

The AWS Encryption SDK establishes a recommended algorithm suite as the default for all encryption operations. The default might change as standards and best practices improve. You can specify an alternate algorithm suite in requests to encrypt data or when creating a cryptographic materials manager (CMM), but unless an alternate is required for your situation, it is best to use the default. The current default is AES-GCM with an HMAC-based extract-and-expand key derivation function (HKDF), Elliptic Curve Digital Signature Algorithm (ECDSA) signing, and a 256-bit encryption key.

If you specify an algorithm suite, we recommend an algorithm suite that uses a key derivation function and a message signing algorithm. Algorithm suites that have neither feature are supported only for backward compatibility.

Encryption Context

To improve the security of your cryptographic operations, use an encryption context in all requests to encrypt data. The encryption context is optional, but recommended.

An encryption context is a set of key–value pairs that contain arbitrary nonsecret data. The encryption context can contain any data you choose, but it typically consists of data that is useful in logging and tracking, such as data about the file type, purpose, or ownership.

In requests to encrypt data, you can include an encryption context along with the plaintext data and a master key provider. The Encryption SDK cryptographically binds the encryption context to the encrypted data so that the same encryption context is required to decrypt the data. The Encryption SDK also includes the encryption context in the encrypted message that it returns, along with the encrypted data and data keys. The encryption context in the encrypted message always includes the encryption context that you specified in the encryption request, along with elements that the operation might add, such as a public signing key.

To decrypt the data, you pass in the encrypted message. Because the Encryption SDK can extract the encryption context from the message, you do not need to pass it in separately. After decrypting the data, the Encryption SDK returns a result that includes that encryption context along with the plaintext data. The functions in your application that decrypt data should always verify that the encryption context in the decrypt result includes the values that you expect before it returns the plaintext data.

When choosing an encryption context, remember that it is not a secret. The encryption context is displayed in plaintext in the header of the encrypted message that the SDK returns. If you are using AWS Key Management Service, the encryption context also might appear in plaintext in audit records and logs, such as AWS CloudTrail.

Encrypted Message

Encrypt operations in the AWS Encryption SDK return an encrypted message and decrypt operations take an encrypted message as input. An encrypted message, a formatted data structure that includes the encrypted data along with encrypted copies of the data keys, the algorithm ID, and, optionally, an encryption context and a message signature.

Combining the encrypted data and its encrypted data keys streamlines the decryption operation and frees you from having to store and manage encrypted data keys independently of the data that they encrypt.

For technical information about the encrypted message, see Encrypted Message Format.