Incorporate Keyrings into AwsCrypto and deprecate MasterKeyProviders.

pom.xml

@@ -54,7 +54,7 @@
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>
-            <artifactId>junit-jupiter-engine</artifactId>
+            <artifactId>junit-jupiter</artifactId>
             <version>5.5.2</version>
             <scope>test</scope>
         </dependency>
@@ -197,7 +197,7 @@
         </profile>
 
         <profile>
-            <id>full-test-suite</id>
+            <id>test-suite</id>
             <activation>
                 <activeByDefault>true</activeByDefault>
             </activation>
@@ -208,30 +208,50 @@
                         <artifactId>maven-surefire-plugin</artifactId>
                         <version>2.22.0</version>
                         <configuration>
-                            <includes>
-                                <include>**/AllTestsSuite.java</include>
-                            </includes>
+                            <excludedGroups>ad_hoc</excludedGroups>
                         </configuration>
                     </plugin>
                 </plugins>
             </build>
         </profile>
 
+        <!-- This test profile is intended to assist in rapid development; it filters out some of the slower,
+             more exhaustive tests in the overall test suite to allow for a rapid edit-test cycle. -->
         <profile>
             <id>fast-tests-only</id>
-            <activation>
-                <activeByDefault>false</activeByDefault>
-            </activation>
             <build>
                 <plugins>
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-surefire-plugin</artifactId>
                         <version>2.22.0</version>
                         <configuration>
-                            <includes>
-                                <include>**/FastTestsOnlySuite.java</include>
-                            </includes>
+                            <excludedGroups>ad_hoc, integration</excludedGroups>
+                            <systemPropertyVariables>
+                                <fastTestsOnly>true</fastTestsOnly>
+                            </systemPropertyVariables>
+                            <!-- Require that this fast suite completes relatively quickly. If you're seeing
+                            this timeout get hit, it's time to pare down tests some more. As a general rule of
+                            thumb, we should avoid any single test taking more than 10s, and try to keep the
+                            number of such slow tests to a minimum. -->
+                            <forkedProcessTimeoutInSeconds>120</forkedProcessTimeoutInSeconds>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+
+        <!-- This test profile will run only the integration tests. -->
+        <profile>
+            <id>integration</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-surefire-plugin</artifactId>
+                        <version>2.22.0</version>
+                        <configuration>
+                            <groups>integration</groups>
                         </configuration>
                     </plugin>
                 </plugins>

src/examples/java/com/amazonaws/crypto/examples/EscrowedEncryptExample.java

@@ -89,7 +89,7 @@ private static byte[] standardEncrypt(final AwsKmsCmkId kmsArn, final PublicKey
 
         // 3. Instantiate a RawRsaKeyring
         //    Because the user does not have access to the private escrow key,
-        //    they pass in "null" for the private key parameter.
+        //    they do not provide the private key parameter.
         final Keyring rsaKeyring = StandardKeyrings.rawRsa()
                 .keyNamespace("Escrow")
                 .keyName("Escrow")

src/examples/java/com/amazonaws/crypto/examples/FileStreamingExample.java

@@ -99,7 +99,7 @@ static void encryptAndDecrypt(final File srcFile, final File encryptedFile, fina
         }
 
         // 7. Create the decrypting input stream with the keyring.
-        try(final AwsCryptoInputStream decryptingStream = crypto.createDecryptingInputStream(
+        try (final AwsCryptoInputStream decryptingStream = crypto.createDecryptingInputStream(
                 CreateDecryptingInputStreamRequest.builder()
                         .keyring(keyring)
                         .inputStream(new FileInputStream(encryptedFile)).build())) {
@@ -143,7 +143,6 @@ private static void compareFiles(File file1, File file2) throws IOException {
                     (file2Line = file2Reader.readLine()) != null) {
                 assert Objects.equals(file1Line, file2Line);
             }
-
         }
     }
 

src/main/java/com/amazonaws/encryptionsdk/AwsCrypto.java

@@ -18,6 +18,7 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Collections;
 import java.util.Map;
+import java.util.function.Consumer;
 
 import com.amazonaws.encryptionsdk.exception.AwsCryptoException;
 import com.amazonaws.encryptionsdk.exception.BadCiphertextException;
@@ -54,8 +55,8 @@
  * byte-arrays and streams. This data is encrypted using the specified {@link CryptoAlgorithm} and a
  * {@code plaintextDataKey} which is unique to each encrypted message. This {@code plaintextDataKey} is then encrypted
  * using one (or more) {@link MasterKey MasterKeys} or a {@link Keyring}. The process is reversed on decryption with the
- * code selecting a copy of the {@code EncryptedDataKey} protected by a usable {@code MasterKey} or {@code Keyring},
- * decrypting the {@code EncryptedDataKey}, and then decrypting the message.
+ * code selecting an {@code EncryptedDataKey} embedded in the encrypted message, decrypting the {@code EncryptedDataKey}
+ * using a {@link MasterKey MasterKey} or {@link Keyring}, and then decrypting the message.
  *
  * <p>
  * Note:
@@ -255,6 +256,21 @@ public long estimateCiphertextSize(final EstimateCiphertextSizeRequest request)
         return cryptoHandler.estimateOutputSize(request.plaintextSize());
     }
 
+    /**
+     * Returns the best estimate for the output length of encrypting a plaintext with the plaintext size specified in
+     * the provided {@link EstimateCiphertextSizeRequest}. The actual ciphertext may be shorter.
+     * <p>
+     * This is a convenience which creates an instance of the {@link EstimateCiphertextSizeRequest.Builder} avoiding the need to
+     * create one manually via {@link EstimateCiphertextSizeRequest#builder()}
+     * </p>
+     *
+     * @param request A Consumer that will call methods on EstimateCiphertextSizeRequest.Builder to create a request.
+     * @return The estimated output length in bytes
+     */
+    public long estimateCiphertextSize(final Consumer<EstimateCiphertextSizeRequest.Builder> request) {
+        return estimateCiphertextSize(EstimateCiphertextSizeRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Returns an encrypted form of {@code plaintext} that has been protected with {@link DataKey}s
      * that are in turn protected by {@link MasterKey MasterKeys} provided by
@@ -355,6 +371,21 @@ public AwsCryptoResult<byte[]> encrypt(final EncryptRequest request) {
                 cryptoHandler.getMasterKeys(), cryptoHandler.getHeaders());
     }
 
+    /**
+     * Returns an encrypted form of {@code plaintext} that has been protected with either the {@link CryptoMaterialsManager}
+     * or the {@link Keyring} specified in the {@link EncryptRequest}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link EncryptRequest.Builder} avoiding the need to
+     * create one manually via {@link EncryptRequest#builder()}
+     * </p>
+     *
+     * @param request A Consumer that will call methods on EncryptRequest.Builder to create a request.
+     * @return An {@link AwsCryptoResult} containing the encrypted data
+     */
+    public AwsCryptoResult<byte[]> encrypt(final Consumer<EncryptRequest.Builder> request) {
+        return encrypt(EncryptRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Calls {@link #encryptData(MasterKeyProvider, byte[], Map)} on the UTF-8 encoded bytes of
      * {@code plaintext} and base64 encodes the result.
@@ -525,6 +556,21 @@ public AwsCryptoResult<byte[]> decrypt(final DecryptRequest request) {
                 cryptoHandler.getMasterKeys(), cryptoHandler.getHeaders());
     }
 
+    /**
+     * Decrypts the provided {@link ParsedCiphertext} using the {@link CryptoMaterialsManager} or the {@link Keyring}
+     * specified in the {@link DecryptRequest}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link DecryptRequest.Builder} avoiding the need to
+     * create one manually via {@link DecryptRequest#builder()}
+     * </p>
+     *
+     * @param request A Consumer that will call methods on DecryptRequest.Builder to create a request.
+     * @return An {@link AwsCryptoResult} containing the decrypted data
+     */
+    public AwsCryptoResult<byte[]> decrypt(final Consumer<DecryptRequest.Builder> request) {
+        return decrypt(DecryptRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Base64 decodes the {@code ciphertext} prior to decryption and then treats the results as a
      * UTF-8 encoded string.
@@ -658,6 +704,21 @@ public AwsCryptoOutputStream createEncryptingOutputStream(final CreateEncrypting
                 request.cryptoMaterialsManager(), request.encryptionContext()));
     }
 
+    /**
+     * Returns a {@link AwsCryptoOutputStream} which encrypts the data prior to passing it onto the
+     * underlying {@link OutputStream}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link CreateEncryptingOutputStreamRequest.Builder} avoiding the need to
+     * create one manually via {@link CreateEncryptingOutputStreamRequest#builder()}
+     * </p>
+     *
+     * @see #encrypt(EncryptRequest)
+     * @see javax.crypto.CipherOutputStream
+     */
+    public AwsCryptoOutputStream createEncryptingOutputStream(final Consumer<CreateEncryptingOutputStreamRequest.Builder> request) {
+        return createEncryptingOutputStream(CreateEncryptingOutputStreamRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Returns a {@link CryptoInputStream} which encrypts the data after reading it from the
      * underlying {@link InputStream}.
@@ -748,6 +809,21 @@ public AwsCryptoInputStream createEncryptingInputStream(final CreateEncryptingIn
         return new AwsCryptoInputStream(request.inputStream(), cryptoHandler);
     }
 
+    /**
+     * Returns a {@link AwsCryptoInputStream} which encrypts the data after reading it from the
+     * underlying {@link InputStream}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link CreateEncryptingInputStreamRequest.Builder} avoiding the need to
+     * create one manually via {@link CreateEncryptingInputStreamRequest#builder()}
+     * </p>
+     *
+     * @see #encrypt(EncryptRequest)
+     * @see javax.crypto.CipherInputStream
+     */
+    public AwsCryptoInputStream createEncryptingInputStream(final Consumer<CreateEncryptingInputStreamRequest.Builder> request) {
+        return createEncryptingInputStream(CreateEncryptingInputStreamRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Returns a {@link CryptoOutputStream} which decrypts the data prior to passing it onto the
      * underlying {@link OutputStream}.
@@ -812,6 +888,22 @@ public AwsCryptoOutputStream createDecryptingOutputStream(final CreateDecrypting
         return new AwsCryptoOutputStream(request.outputStream(), cryptoHandler);
     }
 
+
+    /**
+     * Returns a {@link AwsCryptoOutputStream} which decrypts the data prior to passing it onto the
+     * underlying {@link OutputStream}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link CreateDecryptingOutputStreamRequest.Builder} avoiding the need to
+     * create one manually via {@link CreateDecryptingOutputStreamRequest#builder()}
+     * </p>
+     *
+     * @see #decrypt(DecryptRequest)
+     * @see javax.crypto.CipherOutputStream
+     */
+    public AwsCryptoOutputStream createDecryptingOutputStream(final Consumer<CreateDecryptingOutputStreamRequest.Builder> request) {
+        return createDecryptingOutputStream(CreateDecryptingOutputStreamRequest.builder().applyMutation(request).build());
+    }
+
     /**
      * Returns a {@link CryptoInputStream} which decrypts the data after reading it from the
      * underlying {@link InputStream}.
@@ -844,6 +936,21 @@ public AwsCryptoInputStream createDecryptingInputStream(final CreateDecryptingIn
         return new AwsCryptoInputStream(request.inputStream(), cryptoHandler);
     }
 
+    /**
+     * Returns a {@link AwsCryptoInputStream} which decrypts the data after reading it from the
+     * underlying {@link InputStream}.
+     * <p>
+     * This is a convenience which creates an instance of the {@link CreateDecryptingInputStreamRequest.Builder} avoiding the need to
+     * create one manually via {@link CreateDecryptingInputStreamRequest#builder()}
+     * </p>
+     *
+     * @see #encrypt(EncryptRequest)
+     * @see javax.crypto.CipherInputStream
+     */
+    public AwsCryptoInputStream createDecryptingInputStream(final Consumer<CreateDecryptingInputStreamRequest.Builder> request) {
+        return createDecryptingInputStream(CreateDecryptingInputStreamRequest.builder().applyMutation(request).build());
+    }
+
     private MessageCryptoHandler getEncryptingStreamHandler(
             CryptoMaterialsManager materialsManager, Map<String, String> encryptionContext
     ) {

src/main/java/com/amazonaws/encryptionsdk/AwsCryptoRequest.java

@@ -11,7 +11,11 @@
  * specific language governing permissions and limitations under the License.
  */
 
-package com.amazonaws.encryptionsdk;import com.amazonaws.encryptionsdk.keyrings.Keyring;
+package com.amazonaws.encryptionsdk;
+
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
+
+import java.util.function.Consumer;
 
 import static java.util.Objects.requireNonNull;
 import static org.apache.commons.lang3.Validate.isTrue;
@@ -65,5 +69,10 @@ public T keyring(Keyring keyring) {
         }
 
         abstract T getThis();
+
+        T applyMutation(Consumer<T> mutator) {
+            mutator.accept(getThis());
+            return getThis();
+        }
     }
 }

src/main/java/com/amazonaws/encryptionsdk/AwsCryptoResult.java

@@ -76,7 +76,7 @@ public Map<String, String> getEncryptionContext() {
     }
 
     /**
-     * Convenience method equivalent to {@link #getHeaders()}.{@code getCryptoAlgoId()}.
+     * Convenience method equivalent to {@link #getHeaders()}{@code .getCryptoAlgoId()}.
      */
     public CryptoAlgorithm getAlgorithmSuite() {
         return headers.getCryptoAlgoId();

src/main/java/com/amazonaws/encryptionsdk/internal/DecryptionHandler.java

@@ -34,6 +34,7 @@
 import com.amazonaws.encryptionsdk.MasterKeyProvider;
 import com.amazonaws.encryptionsdk.exception.AwsCryptoException;
 import com.amazonaws.encryptionsdk.exception.BadCiphertextException;
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.KeyringTrace;
 import com.amazonaws.encryptionsdk.model.CiphertextFooters;
 import com.amazonaws.encryptionsdk.model.CiphertextHeaders;
@@ -111,8 +112,11 @@ private DecryptionHandler(final CryptoMaterialsManager materialsManager, final C
      *            the key blobs encoded in the provided ciphertext.
      * @throws AwsCryptoException
      *             if the master key is null.
+     * @deprecated MasterKeyProviders have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #create(CryptoMaterialsManager)} instead.
      */
     @SuppressWarnings("unchecked")
+    @Deprecated
     public static <K extends MasterKey<K>> DecryptionHandler<K> create(
             final MasterKeyProvider<K> customerMasterKeyProvider
     ) throws AwsCryptoException {
@@ -136,8 +140,11 @@ public static <K extends MasterKey<K>> DecryptionHandler<K> create(
      *            {@link #processBytes(byte[], int, int, byte[], int)}
      * @throws AwsCryptoException
      *             if the master key is null.
+     * @deprecated MasterKeyProviders have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #create(CryptoMaterialsManager, CiphertextHeaders)} instead.
      */
     @SuppressWarnings("unchecked")
+    @Deprecated
     public static <K extends MasterKey<K>> DecryptionHandler<K> create(
             final MasterKeyProvider<K> customerMasterKeyProvider, final CiphertextHeaders headers
     ) throws AwsCryptoException {
@@ -537,7 +544,15 @@ public CiphertextHeaders getHeaders() {
         return ciphertextHeaders_;
     }
 
+    /**
+     * The master key that was used to decrypt the encrypted data key. This returns an
+     * empty list if Keyrings are in use.
+     *
+     * @deprecated MasterKeys have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #getKeyringTrace()} to view which key was used in decryption.
+     */
     @Override
+    @Deprecated
     public List<K> getMasterKeys() {
         if(dataKey_.getMasterKey() == null) {
             return Collections.emptyList();

src/main/java/com/amazonaws/encryptionsdk/internal/EncryptionHandler.java

@@ -21,12 +21,14 @@
 import java.security.Signature;
 import java.security.SignatureException;
 import java.security.interfaces.ECPrivateKey;
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
 import javax.crypto.Cipher;
 import javax.crypto.SecretKey;
 
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.KeyringTrace;
 import org.bouncycastle.asn1.ASN1Encodable;
 import org.bouncycastle.asn1.ASN1Integer;
@@ -408,8 +410,19 @@ private CiphertextHeaders signCiphertextHeaders(final CiphertextHeaders unsigned
         return unsignedHeaders;
     }
 
+    /**
+     * The master keys that were used to encrypt the data key. This returns an
+     * empty list if Keyrings are in use.
+     *
+     * @deprecated MasterKeys have been deprecated in favor of {@link Keyring}s.
+     *             Use {@link #getKeyringTrace()} to view which key were used in encryption.
+     */
     @Override
+    @Deprecated
     public List<? extends MasterKey<?>> getMasterKeys() {
+        if(masterKeys_ == null) {
+            return Collections.emptyList();
+        }
         //noinspection unchecked
         return (List)masterKeys_; // This is unmodifiable
     }