Add a key manager interface, capable of providing encryption keys.

Default implementation is unchanged.

Author: MMcM

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/common/TransformedRecordSerializerJCE.java

@@ -31,48 +31,43 @@
 import java.security.GeneralSecurityException;
 import java.security.Key;
 import java.security.SecureRandom;
+import java.util.Random;
 
 /**
  * An extension of {@link TransformedRecordSerializer} to use JCE to encrypt and decrypt records.
  * @param <M> type of {@link Message} that underlying records will use
  */
 @API(API.Status.UNSTABLE)
 public class TransformedRecordSerializerJCE<M extends Message> extends TransformedRecordSerializer<M> {
-
-    @Nullable
-    protected final String cipherName;
-    @Nullable
-    protected final Key encryptionKey;
     @Nullable
-    protected final SecureRandom secureRandom;
+    protected final TransformedRecordSerializerKeyManager keyManager;
 
     protected TransformedRecordSerializerJCE(@Nonnull RecordSerializer<M> inner,
                                              boolean compressWhenSerializing,
                                              int compressionLevel,
                                              boolean encryptWhenSerializing,
                                              double writeValidationRatio,
-                                             @Nullable String cipherName,
-                                             @Nullable Key encryptionKey,
-                                             @Nullable SecureRandom secureRandom) {
+                                             @Nullable TransformedRecordSerializerKeyManager keyManager) {
         super(inner, compressWhenSerializing, compressionLevel, encryptWhenSerializing, writeValidationRatio);
-        this.cipherName = cipherName;
-        this.encryptionKey = encryptionKey;
-        this.secureRandom = secureRandom;
+        this.keyManager = keyManager;
     }
 
     @Override
     protected void encrypt(@Nonnull TransformedRecordSerializerState state, @Nullable StoreTimer timer) throws GeneralSecurityException {
-        if (cipherName == null || encryptionKey == null || secureRandom == null) {
-            throw new RecordSerializationException("attempted to encrypt without setting cipher name and key");
+        if (keyManager == null) {
+            throw new RecordSerializationException("attempted to encrypt without setting key manager (cipher name and key)");
         }
         long startTime = System.nanoTime();
 
+        int keyNumber = keyManager.getSerializationKey();
+        state.keyNumber = keyNumber;
+
         byte[] ivData = new byte[CipherPool.IV_SIZE];
-        secureRandom.nextBytes(ivData);
+        keyManager.getRandom(keyNumber).nextBytes(ivData);
         IvParameterSpec iv = new IvParameterSpec(ivData);
-        Cipher cipher = CipherPool.borrowCipher(cipherName);
+        Cipher cipher = CipherPool.borrowCipher(keyManager.getCipher(keyNumber));
         try {
-            cipher.init(Cipher.ENCRYPT_MODE, encryptionKey, iv);
+            cipher.init(Cipher.ENCRYPT_MODE, keyManager.getKey(keyNumber), iv);
 
             byte[] plainText = state.getDataArray();
             byte[] cipherText = cipher.doFinal(plainText);
@@ -93,7 +88,7 @@ protected void encrypt(@Nonnull TransformedRecordSerializerState state, @Nullabl
 
     @Override
     protected void decrypt(@Nonnull TransformedRecordSerializerState state, @Nullable StoreTimer timer) throws GeneralSecurityException {
-        if (cipherName == null || encryptionKey == null || secureRandom == null) {
+        if (keyManager == null) {
             throw new RecordSerializationException("missing encryption key or provider during decryption");
         }
         long startTime = System.nanoTime();
@@ -104,9 +99,9 @@ protected void decrypt(@Nonnull TransformedRecordSerializerState state, @Nullabl
 
         byte[] cipherText = new byte[state.length - CipherPool.IV_SIZE];
         System.arraycopy(state.data, state.offset + CipherPool.IV_SIZE, cipherText, 0, cipherText.length);
-        Cipher cipher = CipherPool.borrowCipher(cipherName);
+        Cipher cipher = CipherPool.borrowCipher(keyManager.getCipher(state.keyNumber));
         try {
-            cipher.init(Cipher.DECRYPT_MODE, encryptionKey, iv);
+            cipher.init(Cipher.DECRYPT_MODE, keyManager.getKey(state.keyNumber), iv);
 
             byte[] plainText = cipher.doFinal(cipherText);
             state.setDataArray(plainText);
@@ -155,6 +150,8 @@ public static <M extends Message> Builder<M> newBuilder(@Nonnull RecordSerialize
      * @param <M> type of {@link Message} that underlying records will use
      */
     public static class Builder<M extends Message> extends TransformedRecordSerializer.Builder<M> {
+        @Nullable
+        protected TransformedRecordSerializerKeyManager keyManager;
         @Nullable
         protected String cipherName;
         @Nullable
@@ -272,6 +269,26 @@ public Builder<M> clearSecureRandom() {
             return this;
         }
 
+        /**
+         * Sets the key manager used during cryptographic operations.
+         * @param keyManager key manager to use for encrypting and decrypting
+         * @return this <code>Builder</code>
+         */
+        public Builder<M> setKeyManager(@Nonnull TransformedRecordSerializerKeyManager keyManager) {
+            this.keyManager = keyManager;
+            return this;
+        }
+
+        /**
+         * Clears a previously set key manager
+         * that might have been passed to this <code>Builder</code>.
+         * @return this <code>Builder</code>
+         */
+        public Builder<M> clearKeyManager() {
+            this.keyManager = null;
+            return this;
+        }
+
         /**
          * Construct a {@link TransformedRecordSerializerJCE} from the
          * parameters specified by this builder. If one has enabled
@@ -282,17 +299,18 @@ public Builder<M> clearSecureRandom() {
          */
         @Override
         public TransformedRecordSerializerJCE<M> build() {
-            if (encryptWhenSerializing) {
-                if (encryptionKey == null) {
+            if (keyManager == null) {
+                if (encryptionKey != null) {
+                    keyManager = new FixedZeroKeyManager(encryptionKey, cipherName, secureRandom);
+                } else if (encryptWhenSerializing) {
                     throw new RecordCoreArgumentException("cannot encrypt when serializing if encryption key is not set");
                 }
-            }
-            if (encryptionKey != null) {
-                if (cipherName == null) {
-                    cipherName = CipherPool.DEFAULT_CIPHER;
+            } else {
+                if (encryptionKey != null) {
+                    throw new RecordCoreArgumentException("cannot specify both key manager and encryption key");
                 }
-                if (secureRandom == null) {
-                    secureRandom = new SecureRandom();
+                if (cipherName != null) {
+                    throw new RecordCoreArgumentException("cannot specify both key manager and cipher name");
                 }
             }
             return new TransformedRecordSerializerJCE<>(
@@ -301,10 +319,56 @@ public TransformedRecordSerializerJCE<M> build() {
                     compressionLevel,
                     encryptWhenSerializing,
                     writeValidationRatio,
-                    cipherName,
-                    encryptionKey,
-                    secureRandom
+                    keyManager
             );
         }
+
+    }
+
+    static class FixedZeroKeyManager implements TransformedRecordSerializerKeyManager {
+        private final Key encryptionKey;
+        private final String cipherName;
+        private final SecureRandom secureRandom;
+
+        public FixedZeroKeyManager(@Nonnull Key encryptionKey, @Nullable String cipherName, @Nullable SecureRandom secureRandom) {
+            if (cipherName == null) {
+                cipherName = CipherPool.DEFAULT_CIPHER;
+            }
+            if (secureRandom == null) {
+                secureRandom = new SecureRandom();
+            }
+            this.encryptionKey = encryptionKey;
+            this.cipherName = cipherName;
+            this.secureRandom = secureRandom;
+        }
+
+        @Override
+        public int getSerializationKey() {
+            return 0;
+        }
+
+        @Override
+        public Key getKey(int keyNumber) {
+            if (keyNumber != 0) {
+                throw new RecordSerializationException("only provide key number 0");
+            }
+            return encryptionKey;
+        }
+
+        @Override
+        public String getCipher(int keyNumber) {
+            if (keyNumber != 0) {
+                throw new RecordSerializationException("only provide key number 0");
+            }
+            return cipherName;
+        }
+
+        @Override
+        public Random getRandom(int keyNumber) {
+            if (keyNumber != 0) {
+                throw new RecordSerializationException("only provide key number 0");
+            }
+            return secureRandom;
+        }
     }
 }

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/common/TransformedRecordSerializerKeyManager.java

@@ -0,0 +1,63 @@
+/*
+ * TransformedRecordSerializerKeyManager.java
+ *
+ * This source file is part of the FoundationDB open source project
+ *
+ * Copyright 2015-2018 Apple Inc. and the FoundationDB project authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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.apple.foundationdb.record.provider.common;
+
+import com.apple.foundationdb.annotation.API;
+
+import java.security.Key;
+import java.util.Random;
+
+/**
+ * An interface between {@link TransformedRecordSerializerJCE} and a source of keys with associated cipher algorithms.
+ * Each key is identified by a unique <em>key number</em>, which is persisted in serialized records so that the key
+ * can be recovered at deserialization time.
+ */
+@API(API.Status.EXPERIMENTAL)
+public interface TransformedRecordSerializerKeyManager {
+    /**
+     * Get the key number to be used for <em>serializing</em> a record.
+     * Typically, this would be the <em>latest</em> key.
+     * @return the key number to use
+     */
+    int getSerializationKey();
+
+    /**
+     * Get the key with the given key number.
+     * @param keyNumber the unique key identifier
+     * @return the cipher used with this key
+     */
+    Key getKey(int keyNumber);
+
+    /**
+     * Get the name of the cipher used with the given key number.
+     * @param keyNumber the unique key identifier
+     * @return the cipher used with this key
+     */
+    String getCipher(int keyNumber);
+
+    /**
+     * Get a random generator to fill IVs when encrypting.
+     * Normally this would be a {@link java.security.SecureRandom} and would not depend on the key.
+     */
+    // TODO: Perhaps it would be better to have the KM give out an IvParameterSpec or something?
+    //  Maybe wait until we have another algorithm that's different enough.
+    Random getRandom(int keyNumber);
+}