Incorporate Keyrings into AwsCrypto and deprecate MasterKeyProviders.

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

@@ -19,9 +19,14 @@
 import java.util.Map;
 
 import com.amazonaws.encryptionsdk.AwsCrypto;
-import com.amazonaws.encryptionsdk.CryptoResult;
-import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
-import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
+import com.amazonaws.encryptionsdk.AwsCryptoResult;
+import com.amazonaws.encryptionsdk.DecryptRequest;
+import com.amazonaws.encryptionsdk.EncryptRequest;
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
+import com.amazonaws.encryptionsdk.keyrings.StandardKeyrings;
+import com.amazonaws.encryptionsdk.kms.KmsClientSupplier;
+
+import static java.util.Collections.emptyList;
 
 /**
  * <p>
@@ -48,41 +53,56 @@ static void encryptAndDecrypt(final String keyArn) {
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate a KMS master key provider
-        final KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder().withKeysForEncryption(keyArn).build();
+        // 2. Instantiate a 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 KmsClientSupplier clientSupplier = KmsClientSupplier.builder().build();
+
+        // 3. Instantiate a 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.kms(clientSupplier, emptyList(), emptyList(), keyArn);
 
-        // 3. Create an encryption context
+        // 4. Create an encryption context
         //
-        // Most encrypted data should have an associated encryption context
-        // to protect integrity. This sample uses placeholder values.
+        //    Most encrypted data should have an associated encryption context
+        //    to protect integrity. This sample uses placeholder values.
         //
-        // For more information see:
-        // blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
+        //    For more information see:
+        //    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");
 
-        // 4. Encrypt the data
-        final CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(masterKeyProvider, EXAMPLE_DATA, encryptionContext);
+        // 5. 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();
 
-        // 5. Decrypt the data
-        final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(masterKeyProvider, ciphertext);
+        // 6. 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());
 
-        // 6. Before verifying the plaintext, verify that the customer master key that
-        // was used in the encryption operation was the one supplied to the master key provider.
-        if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) {
+        // 7. 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!");
         }
 
-        // 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.
+        // 8. 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.
         if (!encryptionContext.entrySet().stream()
                 .allMatch(e -> e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey())))) {
             throw new IllegalStateException("Wrong Encryption Context!");
         }
 
-        // 8. Verify that the decrypted plaintext matches the original plaintext
+        // 9. 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

@@ -1,168 +1,165 @@
 /*
  * Copyright 2017 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.crypto.examples;
 
-import java.io.FileInputStream;
-import java.io.FileOutputStream;
+import com.amazonaws.encryptionsdk.AwsCrypto;
+import com.amazonaws.encryptionsdk.DecryptRequest;
+import com.amazonaws.encryptionsdk.EncryptRequest;
+import com.amazonaws.encryptionsdk.keyrings.Keyring;
+import com.amazonaws.encryptionsdk.keyrings.StandardKeyrings;
+import com.amazonaws.encryptionsdk.kms.KmsClientSupplier;
+
+import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
 import java.security.KeyPair;
 import java.security.KeyPairGenerator;
 import java.security.PrivateKey;
 import java.security.PublicKey;
+import java.util.Arrays;
 
-import com.amazonaws.encryptionsdk.AwsCrypto;
-import com.amazonaws.encryptionsdk.CryptoOutputStream;
-import com.amazonaws.encryptionsdk.MasterKeyProvider;
-import com.amazonaws.encryptionsdk.jce.JceMasterKey;
-import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
-import com.amazonaws.encryptionsdk.multi.MultipleProviderFactory;
-import com.amazonaws.util.IOUtils;
+import static java.util.Collections.emptyList;
 
 /**
  * <p>
- * Encrypts a file using both KMS and an asymmetric key pair.
+ * Encrypts data using both KMS and an asymmetric key pair.
  *
  * <p>
  * Arguments:
  * <ol>
- * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master 
+ * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master
  *    key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
- *
-  * <li>Name of file containing plaintext data to encrypt
  * </ol>
  *
- * You might use AWS Key Management Service (KMS) for most encryption and decryption operations, but 
- * still want the option of decrypting your data offline independently of KMS. This sample 
+ * You might use AWS Key Management Service (KMS) for most encryption and decryption operations, but
+ * still want the option of decrypting your data offline independently of KMS. This sample
  * demonstrates one way to do this.
- * 
+ *
  * The sample encrypts data under both a KMS customer master key (CMK) and an "escrowed" RSA key pair
- * so that either key alone can decrypt it. You might commonly use the KMS CMK for decryption. However, 
+ * so that either key alone can decrypt it. You might commonly use the KMS CMK for decryption. However,
  * at any time, you can use the private RSA key to decrypt the ciphertext independent of KMS.
  *
- * This sample uses the JCEMasterKey class to generate a RSA public-private key pair
- * and saves the key pair in memory. In practice, you would store the private key in a secure offline 
+ * This sample uses a RawRsaKeyring to generate a RSA public-private key pair
+ * and saves the key pair in memory. In practice, you would store the private key in a secure offline
  * location, such as an offline HSM, and distribute the public key to your development team.
  *
  */
 public class EscrowedEncryptExample {
-    private static PublicKey publicEscrowKey;
-    private static PrivateKey privateEscrowKey;
+    private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
 
-    public static void main(final String[] args) throws Exception {
+    public static void main(final String[] args) throws GeneralSecurityException {
+        final String kmsArn = args[0];
+
+        escrowEncryptAndDecrypt(kmsArn);
+    }
+
+    static void escrowEncryptAndDecrypt(String kmsArn) throws GeneralSecurityException {
         // This sample generates a new random key for each operation.
-        // In practice, you would distribute the public key and save the private key in secure
-        // storage.
-        generateEscrowKeyPair();
+        // In practice, you would distribute the public key and save the private key in secure storage.
+        final KeyPair escrowKeyPair = generateEscrowKeyPair();
 
-        final String kmsArn = args[0];
-        final String fileName = args[1];
+        // Encrypt the data under both a KMS Key and an escrowed RSA Key
+        byte[] encryptedData = standardEncrypt(kmsArn, escrowKeyPair.getPublic());
+
+        // Decrypt the data using the KMS Key
+        byte[] standardDecryptedData = standardDecrypt(kmsArn, encryptedData);
 
-        standardEncrypt(kmsArn, fileName);
-        standardDecrypt(kmsArn, fileName);
+        // Decrypt the data using the escrowed RSA Key
+        byte[] escrowedDecryptedData = escrowDecrypt(encryptedData, escrowKeyPair.getPublic(), escrowKeyPair.getPrivate());
 
-        escrowDecrypt(fileName);
+        // Verify both decrypted data instances are the same as the original plaintext
+        assert Arrays.equals(standardDecryptedData, EXAMPLE_DATA);
+        assert Arrays.equals(escrowedDecryptedData, EXAMPLE_DATA);
     }
 
-    private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
+    private static byte[] standardEncrypt(final String kmsArn, final PublicKey publicEscrowKey) {
         // Encrypt with the KMS CMK and the escrowed public key
+
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate a KMS master key provider
-        final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
-
-        // 3. Instantiate a JCE master key provider
-        // Because the user does not have access to the private escrow key,
-        // they pass in "null" for the private key parameter.
-        final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow",
-                "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
-
-        // 4. Combine the providers into a single master key provider
-        final MasterKeyProvider<?> provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub);
-
-        // 5. Encrypt the file
-        // 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.
-        final FileInputStream in = new FileInputStream(fileName);
-        final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
-        final CryptoOutputStream<?> encryptingStream = crypto.createEncryptingStream(provider, out);
-
-        IOUtils.copy(in, encryptingStream);
-        in.close();
-        encryptingStream.close();
+        // 2. Instantiate a 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 KmsClientSupplier clientSupplier = KmsClientSupplier.builder().build();
+
+        // 3. Instantiate a 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.kms(clientSupplier, emptyList(), emptyList(), kmsArn);
+
+        // 4. Instantiate an 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 keyring = StandardKeyrings.multi(kmsKeyring, rsaKeyring);
+
+        // 6. 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()
+                .keyring(keyring)
+                .plaintext(EXAMPLE_DATA).build())
+                .getResult();
     }
 
-    private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
-        // Decrypt with the KMS CMK and the escrow public key. You can use a combined provider, 
-        // as shown here, or just the KMS master key provider.
+    private static byte[] standardDecrypt(final String kmsArn, final byte[] cipherText) {
+        // Decrypt with the KMS CMK
 
         // 1. Instantiate the SDK
         final AwsCrypto crypto = new AwsCrypto();
 
-        // 2. Instantiate a KMS master key provider
-        final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn);
-
-        // 3. Instantiate a JCE master key provider
-        // Because the user does not have access to the private 
-        // escrow key, they pass in "null" for the private key parameter.
-        final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow",
-                "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
-
-        // 4. Combine the providers into a single master key provider
-        final MasterKeyProvider<?> provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub);
-
-        // 5. Decrypt the file
-        // 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.
-        final FileInputStream in = new FileInputStream(fileName + ".encrypted");
-        final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
-        final CryptoOutputStream<?> decryptingStream = crypto.createDecryptingStream(provider, out);
-        IOUtils.copy(in, decryptingStream);
-        in.close();
-        decryptingStream.close();
+        // 2. Instantiate a 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 KmsClientSupplier clientSupplier = KmsClientSupplier.builder().build();
+
+        // 3. Instantiate a 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.kms(clientSupplier, emptyList(), emptyList(), kmsArn);
+
+        // 4. Decrypt 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.decrypt(DecryptRequest.builder()
+                .keyring(kmsKeyring)
+                .ciphertext(cipherText).build()).getResult();
     }
 
-    private static void escrowDecrypt(final String fileName) throws Exception {
+    private static byte[] escrowDecrypt(final byte[] cipherText, final PublicKey publicEscrowKey, 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 JCE master key provider
-        // This method call uses the escrowed private key, not null 
-        final JceMasterKey escrowPriv = JceMasterKey.getInstance(publicEscrowKey, privateEscrowKey, "Escrow", "Escrow",
-                "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
-
-        // 3. Decrypt the file
-        // 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.
-        final FileInputStream in = new FileInputStream(fileName + ".encrypted");
-        final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
-        final CryptoOutputStream<?> decryptingStream = crypto.createDecryptingStream(escrowPriv, out);
-        IOUtils.copy(in, decryptingStream);
-        in.close();
-        decryptingStream.close();
+        // 2. Instantiate a RawRsaKeyring using the escrowed private key
+        final Keyring rsaKeyring = StandardKeyrings.rawRsa("Escrow", "Escrow",
+                publicEscrowKey, privateEscrowKey, "RSA/ECB/OAEPWithSHA-512AndMGF1Padding");
 
+        // 3. Decrypt 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.decrypt(DecryptRequest.builder()
+                .keyring(rsaKeyring)
+                .ciphertext(cipherText).build()).getResult();
     }
 
-    private static void generateEscrowKeyPair() throws GeneralSecurityException {
+    private static KeyPair generateEscrowKeyPair() throws GeneralSecurityException {
         final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA");
         kg.initialize(4096); // Escrow keys should be very strong
-        final KeyPair keyPair = kg.generateKeyPair();
-        publicEscrowKey = keyPair.getPublic();
-        privateEscrowKey = keyPair.getPrivate();
-
+        return kg.generateKeyPair();
     }
 }