Create builders for the standard keyrings

Author: WesleyRosenblum

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

@@ -24,9 +24,6 @@
 import com.amazonaws.encryptionsdk.EncryptRequest;
 import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.StandardKeyrings;
-import com.amazonaws.encryptionsdk.kms.AwsKmsClientSupplier;
-
-import static java.util.Collections.emptyList;
 
 /**
  * <p>
@@ -53,17 +50,12 @@ static void encryptAndDecrypt(final String keyArn) {
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate an AWS KMS Client Supplier. This example uses the default client supplier but you can
-        //    also configure the credentials provider, client configuration and other settings as necessary
-        final AwsKmsClientSupplier clientSupplier = AwsKmsClientSupplier.builder().build();
-
-        // 3. Instantiate an AWS KMS Keyring, supplying the key ARN as the generator for generating a data key. While
+        // 2. Instantiate an AWS KMS Keyring, supplying the key ARN as the generator for generating a data key. While
         //    using a key ARN is a best practice, for encryption operations it is also acceptable to use a CMK alias or
-        //    an alias ARN. For this example, empty lists are provided for grant tokens and additional keys to encrypt
-        //    the data key with, but those can be supplied as necessary.
-        final Keyring keyring = StandardKeyrings.awsKms(clientSupplier, emptyList(), emptyList(), keyArn);
+        //    an alias ARN.
+        final Keyring keyring = StandardKeyrings.awsKms(keyArn);
 
-        // 4. Create an encryption context
+        // 3. Create an encryption context
         //
         //    Most encrypted data should have an associated encryption context
         //    to protect integrity. This sample uses placeholder values.
@@ -72,28 +64,28 @@ static void encryptAndDecrypt(final String keyArn) {
         //    blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
         final Map<String, String> encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
 
-        // 5. Encrypt the data with the keyring and encryption context
+        // 4. Encrypt the data with the keyring and encryption context
         final AwsCryptoResult<byte[]> encryptResult = crypto.encrypt(
                 EncryptRequest.builder()
                     .keyring(keyring)
                     .encryptionContext(encryptionContext)
                     .plaintext(EXAMPLE_DATA).build());
         final byte[] ciphertext = encryptResult.getResult();
 
-        // 6. Decrypt the data. The same keyring may be used to encrypt and decrypt, but for decryption
+        // 5. Decrypt the data. The same keyring may be used to encrypt and decrypt, but for decryption
         //    the key IDs must be in the key ARN format.
         final AwsCryptoResult<byte[]> decryptResult = crypto.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)
                         .ciphertext(ciphertext).build());
 
-        // 7. Before verifying the plaintext, inspect the Keyring Trace to verify that the CMK used
+        // 6. Before verifying the plaintext, inspect the Keyring Trace to verify that the CMK used
         //    to decrypt the encrypted data key was the CMK in the encryption keyring.
         if(!decryptResult.getKeyringTrace().getEntries().get(0).getKeyName().equals(keyArn)) {
             throw new IllegalStateException("Wrong key ID!");
         }
 
-        // 8. Also, verify that the encryption context in the result contains the
+        // 7. Also, verify that the encryption context in the result contains the
         //    encryption context supplied to the encryptData method. Because the
         //    SDK can add values to the encryption context, don't require that
         //    the entire context matches.
@@ -102,7 +94,7 @@ static void encryptAndDecrypt(final String keyArn) {
             throw new IllegalStateException("Wrong Encryption Context!");
         }
 
-        // 9. Verify that the decrypted plaintext matches the original plaintext
+        // 8. Verify that the decrypted plaintext matches the original plaintext
         assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
     }
 }

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

@@ -18,7 +18,6 @@
 import com.amazonaws.encryptionsdk.EncryptRequest;
 import com.amazonaws.encryptionsdk.keyrings.Keyring;
 import com.amazonaws.encryptionsdk.keyrings.StandardKeyrings;
-import com.amazonaws.encryptionsdk.kms.AwsKmsClientSupplier;
 
 import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
@@ -28,8 +27,6 @@
 import java.security.PublicKey;
 import java.util.Arrays;
 
-import static java.util.Collections.emptyList;
-
 /**
  * <p>
  * Encrypts data using both KMS and an asymmetric key pair.
@@ -75,7 +72,7 @@ static void escrowEncryptAndDecrypt(String kmsArn) throws GeneralSecurityExcepti
         byte[] standardDecryptedData = standardDecrypt(kmsArn, encryptedData);
 
         // Decrypt the data using the escrowed RSA Key
-        byte[] escrowedDecryptedData = escrowDecrypt(encryptedData, escrowKeyPair.getPublic(), escrowKeyPair.getPrivate());
+        byte[] escrowedDecryptedData = escrowDecrypt(encryptedData, escrowKeyPair.getPrivate());
 
         // Verify both decrypted data instances are the same as the original plaintext
         assert Arrays.equals(standardDecryptedData, EXAMPLE_DATA);
@@ -88,25 +85,23 @@ private static byte[] standardEncrypt(final String kmsArn, final PublicKey publi
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate an AWS KMS Client Supplier. This example uses the default client supplier but you can
-        //    also configure the credentials provider, client configuration and other settings as necessary
-        final AwsKmsClientSupplier clientSupplier = AwsKmsClientSupplier.builder().build();
-
-        // 3. Instantiate an AWS KMS Keyring, supplying the keyArn as the generator for generating a data key.
-        //    For this example, empty lists are provided for grant tokens and additional keys to encrypt the data
-        //    key with, but those can be supplied as necessary.
-        final Keyring kmsKeyring = StandardKeyrings.awsKms(clientSupplier, emptyList(), emptyList(), kmsArn);
+        // 2. Instantiate an AWS KMS Keyring, supplying the keyArn as the generator for generating a data key.
+        final Keyring kmsKeyring = StandardKeyrings.awsKms(kmsArn);
 
-        // 4. Instantiate a RawRsaKeyring
+        // 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.
-        final Keyring rsaKeyring = StandardKeyrings.rawRsa("Escrow", "Escrow",
-                publicEscrowKey, null, "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
-
-        // 5. Combine the providers into a single MultiKeyring
+        final Keyring rsaKeyring = StandardKeyrings.rawRsa()
+                .keyNamespace("Escrow")
+                .keyName("Escrow")
+                .publicKey(publicEscrowKey)
+                .wrappingAlgorithm("RSA/ECB/OAEPWithSHA-512AndMGF1Padding")
+                .build();
+
+        // 4. Combine the providers into a single MultiKeyring
         final Keyring keyring = StandardKeyrings.multi(kmsKeyring, rsaKeyring);
 
-        // 6. Encrypt the data with the keyring.
+        // 5. Encrypt the data with the keyring.
         //    To simplify the code, we omit the encryption context. Production code should always
         //    use an encryption context. For an example, see the other SDK samples.
         return crypto.encrypt(EncryptRequest.builder()
@@ -121,14 +116,8 @@ private static byte[] standardDecrypt(final String kmsArn, final byte[] cipherTe
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate an AWS KMS Client Supplier. This example uses the default client supplier but you can
-        //    also configure the credentials provider, client configuration and other settings as necessary
-        final AwsKmsClientSupplier clientSupplier = AwsKmsClientSupplier.builder().build();
-
-        // 3. Instantiate an AWS KMS Keyring, supplying the keyArn as the generator for generating a data key.
-        //    For this example, empty lists are provided for grant tokens and additional keys to encrypt the data
-        //    key with, but those can be supplied as necessary.
-        final Keyring kmsKeyring = StandardKeyrings.awsKms(clientSupplier, emptyList(), emptyList(), kmsArn);
+        // 2. Instantiate an AWS KMS Keyring, supplying the keyArn as the generator for generating a data key.
+        final Keyring kmsKeyring = StandardKeyrings.awsKms(kmsArn);
 
         // 4. Decrypt the data with the keyring.
         //    To simplify the code, we omit the encryption context. Production code should always
@@ -138,16 +127,20 @@ private static byte[] standardDecrypt(final String kmsArn, final byte[] cipherTe
                 .ciphertext(cipherText).build()).getResult();
     }
 
-    private static byte[] escrowDecrypt(final byte[] cipherText, final PublicKey publicEscrowKey, final PrivateKey privateEscrowKey) {
+    private static byte[] escrowDecrypt(final byte[] cipherText, final PrivateKey privateEscrowKey) {
         // You can decrypt the stream using only the private key.
         // This method does not call KMS.
 
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
         // 2. Instantiate a RawRsaKeyring using the escrowed private key
-        final Keyring rsaKeyring = StandardKeyrings.rawRsa("Escrow", "Escrow",
-                publicEscrowKey, privateEscrowKey, "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
+        final Keyring rsaKeyring = StandardKeyrings.rawRsa()
+                .keyNamespace("Escrow")
+                .keyName("Escrow")
+                .privateKey(privateEscrowKey)
+                .wrappingAlgorithm("RSA/ECB/OAEPWithSHA-512AndMGF1Padding")
+                .build();
 
         // 3. Decrypt the data with the keyring
         //    To simplify the code, we omit the encryption context. Production code should always

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

@@ -68,7 +68,11 @@ static void encryptAndDecrypt(final File srcFile, final File encryptedFile, fina
         final SecretKey cryptoKey = retrieveEncryptionKey();
 
         // 3. Instantiate a RawAesKeyring using the random key
-        final Keyring keyring = StandardKeyrings.rawAes("Example", "RandomKey", cryptoKey);
+        final Keyring keyring = StandardKeyrings.rawAes()
+                .keyNamespace("Example")
+                .keyName("RandomKey")
+                .wrappingKey(cryptoKey)
+                .build();
 
         // 4. Create an encryption context
         //

src/main/java/com/amazonaws/encryptionsdk/keyrings/AwsKmsKeyringBuilder.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2020 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.encryptionsdk.keyrings;
+
+import com.amazonaws.encryptionsdk.kms.AwsKmsClientSupplier;
+import com.amazonaws.encryptionsdk.kms.DataKeyEncryptionDao;
+
+import java.util.List;
+
+public class AwsKmsKeyringBuilder {
+    private AwsKmsClientSupplier awsKmsClientSupplier;
+    private List<String> grantTokens;
+    private List<String> keyIds;
+    private String generatorKeyId;
+
+    AwsKmsKeyringBuilder() {
+        // Use StandardKeyrings.awsKms() to instantiate
+    }
+
+    /**
+     * A function that returns an AWS KMS client that can make GenerateDataKey, Encrypt, and Decrypt calls in
+     * a particular AWS region. If this is not supplied, the default AwsKmsClientSupplier will
+     * be used. AwsKmsClientSupplier.builder() can be used to construct this type.
+     *
+     * @param awsKmsClientSupplier The AWS KMS client supplier
+     * @return The AwsKmsKeyringBuilder, for method chaining
+     */
+    public AwsKmsKeyringBuilder awsKmsClientSupplier(AwsKmsClientSupplier awsKmsClientSupplier) {
+        this.awsKmsClientSupplier = awsKmsClientSupplier;
+        return this;
+    }
+
+    /**
+     * A list of string grant tokens to be included in all KMS calls.
+     *
+     * @param grantTokens The list of grant tokens
+     * @return The AwsKmsKeyringBuilder, for method chaining
+     */
+    public AwsKmsKeyringBuilder grantTokens(List<String> grantTokens) {
+        this.grantTokens = grantTokens;
+        return this;
+    }
+
+    /**
+     * A list of strings identifying AWS KMS CMKs used for encrypting and decrypting data keys
+     * in ARN, CMK Alias, or ARN Alias format.
+     *
+     * @param keyIds The list of AWS KMS CMKs
+     * @return The AwsKmsKeyringBuilder, for method chaining
+     */
+    public AwsKmsKeyringBuilder keyIds(List<String> keyIds) {
+        this.keyIds = keyIds;
+        return this;
+    }
+
+    /**
+     * A string that identifies a AWS KMS CMK responsible for generating a data key,
+     * as well as encrypting and decrypting data keys in ARN, CMK Alias, or ARN Alias format.
+     *
+     * @param generatorKeyId The generator AWS KMS CMK
+     * @return The AwsKmsKeyringBuilder, for method chaining
+     */
+    public AwsKmsKeyringBuilder generatorKeyId(String generatorKeyId) {
+        this.generatorKeyId = generatorKeyId;
+        return this;
+    }
+
+    /**
+     * Constructs the {@link Keyring} instance.
+     *
+     * @return The {@link Keyring} instance
+     */
+    public Keyring build() {
+        if(awsKmsClientSupplier == null) {
+            awsKmsClientSupplier = AwsKmsClientSupplier.builder().build();
+        }
+        return new AwsKmsKeyring(DataKeyEncryptionDao.awsKms(awsKmsClientSupplier, grantTokens), keyIds, generatorKeyId);
+    }
+}

src/main/java/com/amazonaws/encryptionsdk/keyrings/RawAesKeyringBuilder.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2020 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.encryptionsdk.keyrings;
+
+import javax.crypto.SecretKey;
+
+public class RawAesKeyringBuilder {
+    private String keyNamespace;
+    private String keyName;
+    private SecretKey wrappingKey;
+
+    RawAesKeyringBuilder() {
+        // Use StandardKeyrings.rawAes() to instantiate
+    }
+
+    /**
+     * A value that, together with the key name, identifies the wrapping key (required).
+     *
+     * @param keyNamespace The key namespace
+     * @return The RawAesKeyringBuilder, for method chaining
+     */
+    public RawAesKeyringBuilder keyNamespace(String keyNamespace) {
+        this.keyNamespace = keyNamespace;
+        return this;
+    }
+
+    /**
+     * A value that, together with the key namespace, identifies the wrapping key (required).
+     *
+     * @param keyName The key name
+     * @return The RawAesKeyringBuilder, for method chaining
+     */
+    public RawAesKeyringBuilder keyName(String keyName) {
+        this.keyName = keyName;
+        return this;
+    }
+
+    /**
+     * The AES key input to AES-GCM to encrypt plaintext data keys (required).
+     *
+     * @param wrappingKey The wrapping key
+     * @return The RawAesKeyringBuilder, for method chaining
+     */
+    public RawAesKeyringBuilder wrappingKey(SecretKey wrappingKey) {
+        this.wrappingKey = wrappingKey;
+        return this;
+    }
+
+    /**
+     * Constructs the {@link Keyring} instance.
+     *
+     * @return The {@link Keyring} instance
+     */
+    public Keyring build() {
+        return new RawAesKeyring(keyNamespace, keyName, wrappingKey);
+    }
+}