Encryption Context (AAD) with AWS KMS

Introduction - AAD 

AWS KMS API supports authenticated encryption using additional authentication data (AAD). The concept of AAD is explained in AWS’ documentation. However, as this is not trivial, I have decided to put that into a live example in this blog post and a simple web application example (available at this GitHub repository).


Problem statement

Let’s assume a team developed a web interface (RESTful API) providing users with a secrets store; the service has two simple APIs:

  • The first API call (POST) is used to upload a secret (providing a secret name and value)
  • Another API call (GET) is used to retrieve secrets uploaded using the API above

In memory the secrets are stored encrypted (standard envelope encryption). For service authentication the team had setup BASIC AUTH on the REST API access. So far pretty simple – not brilliant but a straight forward example which can demonstrate the usage if AAD.

Pretty soon the team discovers that some users had found out that they could fetch other users’ secrets just by tampering the URL. The problem can be described using a few simple steps as:

  1. Alice stores a secret named ‘secret-a’ (HTTP POST to http://server/secrets/secret-a)
  2. The server encrypts the secret and stores it in memory
  3. After a while Bob finds out he could access the URL to fetch Alice's secret (GET to the same URL as above)
  4. In that case the server decrypts the secret and returns it 


NB: In real life we would expect a service like that to tag a secret with the owner and handle that but I am taking the simplest path in here to the benefit of AAD demonstration.

Encryption Context as AAD

The idea behind Additional Authenticated Data (AAD) is that encrypted data belongs to a context and that context should be validated when we attempt to decrypt the ciphertext. If we provide AAD to AWS KMS encryption API call it will tag the ciphertext with some context. When we attempt to decrypt that ciphertext an identical context must be provided, otherwise the decryption will fail.

In the example above the simplest context we could use is the user owning the secret – only Alice should be able to access her secrets, Bob belongs to a different context. AWS implementation refers to that context as EncryptionContext which is, essentially, a Map<String, String>. The two code samples below illustrate the usage of EncryptionContext in AWS, starting with the encryption API. 


// We start by generating a data key and binding it to a context
GenerateDataKeyRequest dataKeyRequest = new GenerateDataKeyRequest()
  .withKeyId(cmkAlias).withKeySpec("AES_128")
  .withEncryptionContext(
    Collections.singletonMap("user", principal.getName()));
GenerateDataKeyResult dataKeyResult = 
  awskms.generateDataKey(dataKeyRequest);

// The data key is just raw material - build a JCE key for Java
Key key = buildJCEKey(dataKeyResult.getPlaintext().asReadOnlyBuffer());
dataKeyResult.getPlaintext().clear(); // Clear it ASAP!!

// Encryption: standard Java API
String encrypted = encrypt(value, key);

// Envelope:
// - The data key in the encrypted form (needs the master key to open)
// - The encrypted payload

Envelop envelope = new Envelope(dataKeyResult.getCiphertextBlob(), encrypted);

The code above creates a unique data key for my envelope encryption (see here about envelope encryption) and tags that key’s encryption with AAD. As I have a mapping of one to one between data keys and the encrypted data I, effectively, tag the encrypted data with its context. Opening the encryption will involve code similar to the following:


// Get the encrypted data key and open using the CMK
DecryptRequest decryptRequest = new DecryptRequest().withCiphertextBlob(envelope.key)
.withEncryptionContext(
Collections.singletonMap("user", principal.getName()));
DecryptResult decryptResult = awskms.decrypt(decryptRequest);

// Build a JCE Key out of it - for Java to use
Key key = buildJCEKey(decryptResult.getPlaintext().asReadOnlyBuffer());
decryptResult.getPlaintext().clear();

// Decrypt the actual secret
String cleartext = decrypt(envelope.payload, key);

The most important part of that example is the usage of ‘withEncryptionContext’ on both sides of the encryption – as I calculate the context (in this case the authenticated user) at runtime the encrypted form of the data key is tagged with that username (‘user=Alice’ when Alice stores a secret). If Bob changes the URL to point to Alice's secrets he will still fail: as long as he logged in as Bob the system will calculate ‘user=Bob’ as the context and fail to decrypt the data key - Alice's secret is now secured.

What Should be In the Context?

There are a few aspects to be aware of when deciding on the context:
  • Reproducible – obviously I would like to be able to reproduce the context otherwise I will not be able to decrypt the cipher text, so any context containing random generated values (e.g. UUID, timestamps) is not valid unless I store it somewhere
  • Context can be stored (for reproducibility) but it is better to store the minimal required to calculate the full context at runtime. By that we reduce the surface attack of moving around the ciphertext and the context to trick the system
  • Don’t include any sensitive data in the context – at least in AWS the context is logged to CloudTrail

Giving it a try

The code above available on both Github (here) and as a Docker image on Docker Hub (here). Before running the example do remember that as this using AWS KMS it does imply that (1) it will attempt to create a CMK on the KMS if it cannot find one with the ‘aad-example’ alias (this alias can be overridden using standard Spring boot facilities), (2) CMKs cost money – so running this will be charged by AWS and (3) it needs to connect with AWS using access key and secret to be provided to the SDK.

To read more about build and executing the example check the README in GitHub.

Once the service is running try the following commands to see it in action:
[eyal@localhost]$ curl -X POST  'Content-type: text/plain' -vv -d 'my-secret-value' --user alice:alice  http://localhost:8080/secrets/my-secret

[eyal@localhost]$ curl -X GET -H 'Content-type: text/plain' -vv --user alice:alice  http://localhost:8080/secrets/my-secret

[eyal@localhost]$ #The next should fail since Bob is trying to fetch Alice’s secret
[eyal@localhost]$ curl -X GET -H 'Content-type: text/plain' -vv --user bob:bob  http://localhost:8080/secrets/my-secret
Location: Reading, UK

Comments

Post a Comment

Popular posts from this blog

New in Spring MVC 3.1: CSRF Protection using RequestDataValueProcessor

Image
Introduction As a software architect one of the common tasks I have to deal with is web applications security. Usually I would try to make sure that security is automatically enforced by the infrastructure, however this is not always that easy – sometimes the underlying frameworks don’t provide any built in support or configuration which globally turns on a security attribute. This is why the new org.springframework.web.servlet.support.RequestDataValueProcessor interface in Spring MVC 3.1 seems to be very interesting: it provides a clean way to implement automatic CSRF protection.
Read More >>

Hibernate Exception - Simultaneously Fetch Multiple Bags

One of my customers has just upgraded to JBoss 4.0.4-GA, the process also required us to upgrade Hibernate products to the following versions: Hibernate core – 3.2.0CR2 Hibernate Entity Manager – 3.2.0CR1 Hibernate annotations- 3.2.0CR1 We fixed some minor changes and improvements and then we bumped into the following exception javax.persistence.PersistenceException: org.hibernate.HibernateException: cannot simultaneously fetch multiple bags at org.hibernate.ejb.Ejb3Configuration.createEntityManagerFactory(Ejb3Configuration.java:217) at org.hibernate.ejb.HibernatePersistence.createEntityManagerFactory(HibernatePersistence.java:114) ........ The Exception is thrown by org.hibernate.loader.BasicLoader and it means that when loading an entity Hibernate might has to simultaneously fetch two or more bags.
Read More >>

Hibernate Derived Properties - Performance and Portability

Hi all, This time about derived properties, maybe this is not a commonly used feature, and maybe even a little bit hidden one (I don't think I have ever been asked about it in any of the Hibernate courses I had lectured in and this usually a sign that people are not familiar with that feature) but once you're familiar with that it is a powerful feature - however, as always, there are considerations regarding of how and when to use it. What Is a Derived Property? A derived, or calculated, property is a read only property which its value is calculated at fetch time using SQL expressions. For example a Product class might have a price and a calculated final price which is the price including VAT. The first (not so good) solution might be something like that: @Entity @Table(name="PRODUCTS") public class Product { @Column(name="PRICE") private float price; public float getFinalPrice() { return VAT*price; } } The getFinalPrice() method...
Read More >>