Support for meta-providers.

This introduces the new concept of a ProviderStore which can be used to simplify managing
multiple providers on a named or versioned basis. The MetaStore is specificaly backed by
a DynamoDB Table and instance of DynamoDBEncryptor. This allows developers to build
key-hierarchies and caching layes.

Author: SalusaSecondus

src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/MostRecentProvider.java

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
+ * in compliance with the License. A copy of the License is located at
+ * 
+ * http://aws.amazon.com/apache2.0
+ * 
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+package com.amazonaws.services.dynamodbv2.datamodeling.encryption.providers;
+
+import com.amazonaws.services.dynamodbv2.datamodeling.internal.LRUCache;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.EncryptionContext;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.materials.DecryptionMaterials;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.materials.EncryptionMaterials;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.providers.store.ProviderStore;
+
+/**
+ * This meta-Provider encrypts data with the most recent version of keying materials from a
+ * {@link ProviderStore} and decrypts using whichever version is appropriate. It also caches the
+ * results from the {@link ProviderStore} to avoid excessive load on the backing systems. The cache
+ * is not currently configurable.
+ */
+public class MostRecentProvider implements EncryptionMaterialsProvider {
+    private final Object lock;
+    private final ProviderStore keystore;
+    private final String materialName;
+    private final long ttlInMillis;
+    private final LRUCache<EncryptionMaterialsProvider> cache;
+    private EncryptionMaterialsProvider currentProvider;
+    private long currentVersion;
+    private long lastUpdated;
+
+    /**
+     * Creates a new {@link MostRecentProvider}.
+     * 
+     * @param ttlInMillis
+     *            The length of time in milliseconds to cache the most recent provider
+     */
+    public MostRecentProvider(final ProviderStore keystore, final String materialName, final long ttlInMillis) {
+        this.keystore = checkNotNull(keystore, "keystore must not be null");
+        this.materialName = checkNotNull(materialName, "materialName must not be null");
+        this.ttlInMillis = ttlInMillis;
+        this.cache = new LRUCache<EncryptionMaterialsProvider>(1000);
+        this.lock = new Object();
+        currentProvider = null;
+        currentVersion = -1;
+        lastUpdated = 0;
+    }
+
+    @Override
+    public EncryptionMaterials getEncryptionMaterials(EncryptionContext context) {
+        synchronized (lock) {
+            if ((System.currentTimeMillis() - lastUpdated) > ttlInMillis) {
+                long newVersion = keystore.getMaxVersion(materialName);
+                if (newVersion < 0) {
+                    currentVersion = 0;
+                    currentProvider = keystore.getOrCreate(materialName, currentVersion);
+                } else if (newVersion != currentVersion) {
+                    currentVersion = newVersion;
+                    currentProvider = keystore.getProvider(materialName, currentVersion);
+                    cache.add(Long.toString(currentVersion), currentProvider);
+                }
+                lastUpdated = System.currentTimeMillis();
+            }
+            return currentProvider.getEncryptionMaterials(context);
+        }
+    }
+
+    public DecryptionMaterials getDecryptionMaterials(EncryptionContext context) {
+        final long version = keystore.getVersionFromMaterialDescription(
+                context.getMaterialDescription());
+        EncryptionMaterialsProvider provider = cache.get(Long.toString(version));
+        if (provider == null) {
+            provider = keystore.getProvider(materialName, version);
+            cache.add(Long.toString(version), provider);
+        }
+        return provider.getDecryptionMaterials(context);
+    }
+
+    /**
+     * Completely empties the cache of both the current and old versions.
+     */
+    @Override
+    public void refresh() {
+        synchronized (lock) {
+            lastUpdated = 0;
+            currentVersion = -1;
+            currentProvider = null;
+        }
+        cache.clear();
+    }
+
+    public String getMaterialName() {
+        return materialName;
+    }
+
+    public long getTtlInMills() {
+        return ttlInMillis;
+    }
+
+    /**
+     * The current version of the materials being used for encryption. Returns -1 if we do not
+     * currently have a current version.
+     */
+    public long getCurrentVersion() {
+        synchronized (lock) {
+            return currentVersion;
+        }
+    }
+
+    /**
+     * The last time the current version was updated. Returns 0 if we do not currently have a
+     * current version.
+     */
+    public long getLastUpdated() {
+        synchronized (lock) {
+            return lastUpdated;
+        }
+    }
+
+    private static <V> V checkNotNull(final V ref, final String errMsg) {
+        if (ref == null) {
+            throw new NullPointerException(errMsg);
+        } else {
+            return ref;
+        }
+    }
+}

src/main/java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/store/MetaStore.java

@@ -0,0 +1,242 @@
+/*
+ * Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except
+ * in compliance with the License. A copy of the License is located at
+ * 
+ * http://aws.amazon.com/apache2.0
+ * 
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+package com.amazonaws.services.dynamodbv2.datamodeling.encryption.providers.store;
+
+import java.nio.ByteBuffer;
+import java.security.GeneralSecurityException;
+import java.security.SecureRandom;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import javax.crypto.SecretKey;
+import javax.crypto.spec.SecretKeySpec;
+
+import com.amazonaws.AmazonClientException;
+import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.DynamoDBEncryptor;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.EncryptionContext;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.providers.EncryptionMaterialsProvider;
+import com.amazonaws.services.dynamodbv2.datamodeling.encryption.providers.WrappedMaterialsProvider;
+import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
+import com.amazonaws.services.dynamodbv2.model.AttributeValue;
+import com.amazonaws.services.dynamodbv2.model.ComparisonOperator;
+import com.amazonaws.services.dynamodbv2.model.Condition;
+import com.amazonaws.services.dynamodbv2.model.ConditionalCheckFailedException;
+import com.amazonaws.services.dynamodbv2.model.CreateTableResult;
+import com.amazonaws.services.dynamodbv2.model.ExpectedAttributeValue;
+import com.amazonaws.services.dynamodbv2.model.GetItemRequest;
+import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
+import com.amazonaws.services.dynamodbv2.model.KeyType;
+import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
+import com.amazonaws.services.dynamodbv2.model.PutItemRequest;
+import com.amazonaws.services.dynamodbv2.model.QueryRequest;
+import com.amazonaws.services.dynamodbv2.model.ScalarAttributeType;
+
+/**
+ * Provides a simple collection of EncryptionMaterialProviders backed by an encrypted DynamoDB
+ * table. This can be used to build key hierarchies or meta providers.
+ *
+ * Currently, this only supports AES-256 in AESWrap mode and HmacSHA256 for the providers persisted
+ * in the table.
+ *
+ * @author rubin
+ */
+public class MetaStore extends ProviderStore {
+    private static final String INTEGRITY_ALGORITHM_FIELD = "intAlg";
+    private static final String INTEGRITY_KEY_FIELD = "int";
+    private static final String ENCRYPTION_ALGORITHM_FIELD = "encAlg";
+    private static final String ENCRYPTION_KEY_FIELD = "enc";
+    private static final Pattern COMBINED_PATTERN = Pattern.compile("([^#]+)#(\\d*)");
+    private static final String DEFAULT_INTEGRITY = "HmacSHA256";
+    private static final String DEFAULT_ENCRYPTION = "AES";
+    private static final String MATERIAL_TYPE_VERSION = "t";
+    private static final String META_ID = "amzn-ddb-meta-id";
+
+    private static final String DEFAULT_HASH_KEY = "N";
+    private static final String DEFAULT_RANGE_KEY = "V";
+
+    private final SecureRandom rng = new SecureRandom();
+    private final Map<String, ExpectedAttributeValue> doesNotExist;
+    private final String tableName;
+    private final AmazonDynamoDB ddb;
+    private final DynamoDBEncryptor encryptor;
+    private final EncryptionContext ddbCtx;
+
+    public MetaStore(final AmazonDynamoDB ddb, final String tableName,
+            final DynamoDBEncryptor encryptor) {
+        this.ddb = checkNotNull(ddb, "ddb must not be null");
+        this.tableName = checkNotNull(tableName, "tableName must not be null");
+        this.encryptor = checkNotNull(encryptor, "encryptor must not be null");
+
+        ddbCtx = new EncryptionContext.Builder().withTableName(this.tableName)
+                .withHashKeyName(DEFAULT_HASH_KEY).withRangeKeyName(DEFAULT_RANGE_KEY).build();
+
+        final Map<String, ExpectedAttributeValue> tmpExpected = new HashMap<String, ExpectedAttributeValue>();
+        tmpExpected.put(DEFAULT_HASH_KEY, new ExpectedAttributeValue().withExists(false));
+        tmpExpected.put(DEFAULT_RANGE_KEY, new ExpectedAttributeValue().withExists(false));
+        doesNotExist = Collections.unmodifiableMap(tmpExpected);
+    }
+    
+    @Override
+    public EncryptionMaterialsProvider getProvider(final String materialName, final long version) {
+        final Map<String, AttributeValue> ddbKey = new HashMap<String, AttributeValue>();
+        ddbKey.put(DEFAULT_HASH_KEY, new AttributeValue().withS(materialName));
+        ddbKey.put(DEFAULT_RANGE_KEY, new AttributeValue().withN(Long.toString(version)));
+        final Map<String, AttributeValue> item = ddbGet(ddbKey);
+        if (item == null || item.isEmpty()) {
+            throw new IndexOutOfBoundsException("No material found: " + materialName + "#" + version);
+        }
+        return decryptProvider(item);
+    }
+
+    @Override
+    public EncryptionMaterialsProvider getOrCreate(final String materialName, final long nextId) {
+        final byte[] rawEncKey = new byte[32];
+        rng.nextBytes(rawEncKey);
+        final byte[] rawIntKey = new byte[32];
+        rng.nextBytes(rawIntKey);
+        final SecretKeySpec encryptionKey = new SecretKeySpec(rawEncKey, DEFAULT_ENCRYPTION);
+        final SecretKeySpec integrityKey = new SecretKeySpec(rawIntKey, DEFAULT_INTEGRITY);
+        final Map<String, AttributeValue> ciphertext = conditionalPut(encryptKeys(materialName,
+                nextId, encryptionKey, integrityKey));
+        return decryptProvider(ciphertext);
+    }
+
+    @Override
+    public long getMaxVersion(final String materialName) {
+        final List<Map<String, AttributeValue>> items = ddb.query(
+                new QueryRequest()
+                .withTableName(tableName)
+                .withConsistentRead(Boolean.TRUE)
+                .withKeyConditions(
+                        Collections.singletonMap(
+                                DEFAULT_HASH_KEY,
+                                new Condition().withComparisonOperator(
+                                        ComparisonOperator.EQ).withAttributeValueList(
+                                                new AttributeValue().withS(materialName))))
+                                                .withLimit(1).withScanIndexForward(false)
+                                                .withAttributesToGet(DEFAULT_RANGE_KEY)).getItems();
+        if (items.isEmpty()) {
+            return -1L;
+        } else {
+            return Long.valueOf(items.get(0).get(DEFAULT_RANGE_KEY).getN());
+        }
+    }
+
+    @Override
+    public long getVersionFromMaterialDescription(final Map<String, String> description) {
+        final Matcher m = COMBINED_PATTERN.matcher(description.get(META_ID));
+        if (m.matches()) {
+            return Long.valueOf(m.group(2));
+        } else {
+            throw new IllegalArgumentException("No meta id found");
+        }
+    }
+    /**
+     * Creates a DynamoDB Table with the correct properties to be used with a ProviderStore.
+     */
+    public static CreateTableResult createTable(final AmazonDynamoDB ddb, final String tableName,
+            final ProvisionedThroughput provisionedThroughput) {
+        return ddb.createTable(Arrays.asList(new AttributeDefinition(DEFAULT_HASH_KEY,
+                ScalarAttributeType.S), new AttributeDefinition(DEFAULT_RANGE_KEY,
+                        ScalarAttributeType.N)), tableName, Arrays.asList(new KeySchemaElement(
+                                DEFAULT_HASH_KEY, KeyType.HASH), new KeySchemaElement(DEFAULT_RANGE_KEY,
+                                        KeyType.RANGE)), provisionedThroughput);
+
+    }
+
+    private Map<String, AttributeValue> conditionalPut(final Map<String, AttributeValue> item) {
+        try {
+            final PutItemRequest put = new PutItemRequest().withTableName(tableName).withItem(item)
+                    .withExpected(doesNotExist);
+            ddb.putItem(put);
+            return item;
+        } catch (final ConditionalCheckFailedException ex) {
+            final Map<String, AttributeValue> ddbKey = new HashMap<String, AttributeValue>();
+            ddbKey.put(DEFAULT_HASH_KEY, item.get(DEFAULT_HASH_KEY));
+            ddbKey.put(DEFAULT_RANGE_KEY, item.get(DEFAULT_RANGE_KEY));
+            return ddbGet(ddbKey);
+        }
+    }
+
+    private Map<String, AttributeValue> ddbGet(final Map<String, AttributeValue> ddbKey) {
+        return ddb.getItem(
+                new GetItemRequest().withTableName(tableName).withConsistentRead(true)
+                .withKey(ddbKey)).getItem();
+    }
+
+    private Map<String, AttributeValue> encryptKeys(final String name, final long version,
+            final SecretKeySpec encryptionKey, final SecretKeySpec integrityKey) {
+        final Map<String, AttributeValue> plaintext = new HashMap<String, AttributeValue>();
+        plaintext.put(DEFAULT_HASH_KEY, new AttributeValue().withS(name));
+        plaintext.put(DEFAULT_RANGE_KEY, new AttributeValue().withN(Long.toString(version)));
+        plaintext.put(MATERIAL_TYPE_VERSION, new AttributeValue().withS("0"));
+        plaintext.put(ENCRYPTION_KEY_FIELD,
+                new AttributeValue().withB(ByteBuffer.wrap(encryptionKey.getEncoded())));
+        plaintext.put(ENCRYPTION_ALGORITHM_FIELD, new AttributeValue().withS(encryptionKey.getAlgorithm()));
+        plaintext
+        .put(INTEGRITY_KEY_FIELD, new AttributeValue().withB(ByteBuffer.wrap(integrityKey.getEncoded())));
+        plaintext.put(INTEGRITY_ALGORITHM_FIELD, new AttributeValue().withS(encryptionKey.getAlgorithm()));
+
+        try {
+            return encryptor.encryptAllFieldsExcept(plaintext, ddbCtx, DEFAULT_HASH_KEY,
+                    DEFAULT_RANGE_KEY);
+        } catch (final GeneralSecurityException e) {
+            throw new AmazonClientException(e);
+        }
+    }
+
+    private EncryptionMaterialsProvider decryptProvider(final Map<String, AttributeValue> item) {
+        try {
+            final Map<String, AttributeValue> plaintext = encryptor.decryptAllFieldsExcept(item,
+                    ddbCtx, DEFAULT_HASH_KEY, DEFAULT_RANGE_KEY);
+
+            final String type = plaintext.get(MATERIAL_TYPE_VERSION).getS();
+            final SecretKey encryptionKey;
+            final SecretKey integrityKey;
+            // This switch statement is to make future extensibility easier and more obvious
+            switch (type) {
+                case "0": // Only currently supported type
+                    encryptionKey = new SecretKeySpec(plaintext.get(ENCRYPTION_KEY_FIELD).getB().array(),
+                            plaintext.get(ENCRYPTION_ALGORITHM_FIELD).getS());
+                    integrityKey = new SecretKeySpec(plaintext.get(INTEGRITY_KEY_FIELD).getB().array(), plaintext
+                            .get(INTEGRITY_ALGORITHM_FIELD).getS());
+                    break;
+                default:
+                    throw new IllegalStateException("Unsupported material type: " + type);
+            }
+            return new WrappedMaterialsProvider(encryptionKey, encryptionKey, integrityKey,
+                    buildDescription(plaintext));
+        } catch (final GeneralSecurityException e) {
+            throw new AmazonClientException(e);
+        }
+    }
+
+    private Map<String, String> buildDescription(final Map<String, AttributeValue> plaintext) {
+        return Collections.singletonMap(META_ID, plaintext.get(DEFAULT_HASH_KEY).getS() + "#"
+                + plaintext.get(DEFAULT_RANGE_KEY).getN());
+    }
+
+    private static <V> V checkNotNull(final V ref, final String errMsg) {
+        if (ref == null) {
+            throw new NullPointerException(errMsg);
+        } else {
+            return ref;
+        }
+    }
+}