Menu
AWS Encryption SDK
Developer Guide

What Is the AWS Encryption SDK?

The AWS Encryption SDK provides client-side encryption libraries you can use to protect your data and the encryption keys used to encrypt that data. The SDK does the following things for you:

  • Provides an API to define and use a master key provider, an interface for the top-level key or keys under which your data is encrypted.

  • Tracks and protects the data encryption keys (DEKs) used to encrypt your data.

  • Performs the low-level cryptographic operations.

You determine the top-level master keys that protect your data, and the SDK does the rest. The SDK helps you connect the low-level cryptography to the top-level master keys. For more information about master keys, master key providers, data encryption keys, and other cryptography concepts related to this SDK, see Encryption Concepts and Architecture.

The SDK is similar to the Amazon DynamoDB Encryption Client for Java and the Amazon S3 Encryption Client, but unlike those clients the data encrypted by this SDK can be stored anywhere.

The SDK is provided for free under the Apache license and is available for the Java programming language at https://github.com/awslabs/aws-encryption-sdk-java.

Encryption Concepts

You can use the AWS Encryption SDK to protect your data and the encryption keys used to encrypt that data.

Encryption Basics

To encrypt data, you provide the raw data (plaintext) and a data key to an encryption algorithm. The algorithm uses those inputs to produce encrypted data (ciphertext). To decrypt data, you provide the encrypted data and the data key to a decryption algorithm that uses those inputs to return the original data.

Basic symmetric key encryption and decryption

Some algorithms use the same data key to encrypt and decrypt data. This is called symmetric key encryption. Other algorithms use a public key to encrypt data, and only a related private key can decrypt that data. This is called public key encryption.

For both types of encryption, the security of your encrypted data depends on protecting the data key that can decrypt it. One accepted best practice for protecting the data key is to encrypt it. To encrypt the data key you need another encryption key called a key encryption key (KEK). This practice of using KEKs to encrypt data keys is called envelope encryption.

Envelope Encryption

Envelope encryption is the practice of encrypting plaintext data with a unique data key, and then encrypting the data key with a KEK. You might choose to encrypt the KEK with another KEK, and so on, but eventually you must have a master key. The master key is an unencrypted (plaintext) key with which you can decrypt one or more other keys.

Some of the benefits of envelope encryption include:

  • Protecting data keys

    When you encrypt a data key, you do not have to worry about where to store the encrypted data key, because the security of that data key is inherently protected by encryption. You can safely store the encrypted data key alongside the encrypted data. The AWS Encryption SDK takes care of this for you by combining the encrypted data key and the encrypted data into a single encrypted message.

  • Encrypting the same data under multiple master keys

    Encryption operations can be time-consuming, particularly when the data being encrypted are large objects. Instead of re-encrypting raw data multiple times with different keys, you can re-encrypt only the data keys that protect the raw data.

  • Combining the strengths of multiple algorithms

    In general, symmetric key algorithms are faster and produce smaller ciphertexts than public key algorithms, but public key algorithms provide inherent separation of roles and easier key management. You might want to combine the strengths of each. For example, you might encrypt raw data with symmetric key encryption, and then encrypt the data key with public key encryption.

The following image provides an overview of envelope encryption. In this scenario, the data key is encrypted with a single KEK, which is the master key.

Envelope encryption

When you use envelope encryption, you must protect the master keys from unauthorized access. To protect your master keys, you can use a hardware security module (HSM) (for example, those offered by AWS CloudHSM), you can use the AWS Key Management Service (AWS KMS), or you can use your existing key management tools.

The AWS Encryption SDK supports the use of AWS KMS to protect your master keys, or you can use another master key provider, including a custom one. Even if you don't use AWS, you can still use this SDK.

Architecture

The AWS Encryption SDK provides methods that operate on byte arrays, byte streams, and strings. The following topics provide a high-level overview of how this SDK works.

For code samples in Java, see Example Code (Java).

Encryption

The following diagram shows how you can use the AWS Encryption SDK to encrypt data.

AWS Encryption SDK encryption workflow
  1. Your application passes data to one of the encryption methods.

  2. The encryption method uses a master key provider to determine which master key to use.

  3. The master key generates a data key.

  4. The master key creates two copies of the data key, one in plaintext and one encrypted by the master key.

  5. The encryption method uses the plaintext data key to encrypt the data, and then deletes the plaintext data key.

  6. The encryption method returns, in a single message, encrypted data that consists of the plaintext data and the encrypted data key.

Decryption

The following diagram shows a high-level overview of how you can use the AWS Encryption SDK to decrypt data.

AWS Encryption SDK decryption workflow
  1. Your application passes encrypted data to one of the decryption methods.

  2. The decryption method extracts the encrypted data key from the encrypted data, and then sends the encrypted data key to a master key provider for decryption.

  3. The master key provider decrypts the encrypted data key, and then returns the plaintext data key to the decryption method.

  4. The decryption method uses the plaintext data key to return the plaintext data, and then deletes the plaintext data key.

Getting Started

To get started with the AWS Encryption SDK, follow the steps in the following topics.

(Optional) Create an AWS Account

To use some of the example Java code in this guide, you need to create an AWS account and then create a customer master key (CMK) in AWS Key Management Service (AWS KMS). Some of the sample code demonstrates how to use a CMK in AWS KMS to protect the data keys that encrypt your data.

To create an AWS account

  1. Go to the Sign In or Create an AWS Account page.

  2. Type your email address or mobile phone number, and then choose I am a new user. Choose Sign in using our secure server.

  3. Follow the instructions on the website.

During the sign-up process, you receive a phone call and enter a PIN with the phone keypad. You must also enter a valid credit card number during the sign-up process.

To create a customer master key (CMK) in AWS KMS

  1. Open the Creating Keys page in the AWS Key Management Service Developer Guide.

  2. Follow the instructions on that page.

Download the AWS Encryption SDK

The AWS Encryption SDK is currently available for the Java programming language. Before you download the SDK, you must have the following:

If you already have these prerequisites, or after you have downloaded and installed them, you can download the AWS Encryption SDK at https://github.com/awslabs/aws-encryption-sdk-java.

If you use Apache Maven, you can specify the AWS Encryption SDK as a dependency in your project. Add the following dependency to your application's pom.xml file:

<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-encryption-sdk-java</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

After you download the AWS Encryption SDK, see Example Code (Java) for examples that demonstrate how to use it.