feat!: Updates to the AWS Encryption SDK.

This change includes fixes for issues that were reported by Thai Duong from Google's Security team, and
for issues that were identified by AWS Cryptography.

BREAKING CHANGE: AWS KMS KeyIDs must be specified explicitly or Discovery mode explicitly chosen.
Key committing suites are now default. CommitmentPolicy requires commitment by default.

See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/migration.html

Author: lavaleri

README.md

@@ -91,9 +91,7 @@ public class StringExample {
         data = args[1];
 
         // Instantiate the SDK
-        final AwsCrypto crypto = AwsCrypto.builder()
-                .withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
-                .build();
+        final AwsCrypto crypto = AwsCrypto.standard();
 
         // Set up the master key provider
         final KmsMasterKeyProvider prov = KmsMasterKeyProvider.builder().buildStrict(keyArn);

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-encryption-sdk-java</artifactId>
-    <version>1.7.0</version>
+    <version>2.0.0</version>
     <packaging>jar</packaging>
 
     <name>aws-encryption-sdk-java</name>

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

@@ -36,15 +36,21 @@ public static void main(final String[] args) {
     }
 
     static void encryptAndDecrypt(final String keyArn) {
-        // 1. Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // 1. Instantiate the SDK
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
-        // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict()
+        // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict().
         // In strict mode, the AWS KMS master key provider encrypts and decrypts only by using the key
         // indicated by keyArn.
         // To encrypt and decrypt with this master key provider, use an AWS KMS key ARN to identify the CMKs.
-        // The decrypt operation doesn't work with any other key identifier in strict mode.
+        // In strict mode, the decrypt operation requires a key ARN.
         final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder().buildStrict(keyArn);
 
         // 3. Create an encryption context

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

@@ -45,9 +45,15 @@ public static void main(final String[] args) {
     }
 
     static void encryptAndDecrypt(final String keyName, final String partition, final String accountId) {
-        // 1. Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // 1. Instantiate the SDK
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // 2. Instantiate an AWS KMS master key provider for encryption.
         //

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

@@ -66,10 +66,16 @@ public static void main(final String[] args) throws Exception {
     }
 
     private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
-        // Encrypt with the AWS KMS CMK and the escrowed public key
-        // 1. Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // Encrypt with the KMS CMK and the escrowed public key
+        // 1. Instantiate the SDK
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict()
         //
@@ -102,8 +108,15 @@ private static void standardDecrypt(final String kmsArn, final String fileName)
         // Decrypt with the AWS KMS CMK and the escrow public key. You can use a combined provider,
         // as shown here, or just the AWS KMS master key provider.
 
-        // 1. Instantiate the SDK
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // 1. Instantiate the SDK.
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict()
         //
@@ -136,7 +149,7 @@ private static void escrowDecrypt(final String fileName) throws Exception {
         // This method does not call AWS KMS.
 
         // 1. Instantiate the SDK
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        final AwsCrypto crypto = AwsCrypto.standard();
 
         // 2. Instantiate a JCE master key provider
         // This method call uses the escrowed private key, not null 

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

@@ -47,9 +47,15 @@ public static void main(String[] args) throws IOException {
         // Create a JCE master key provider using the random key and an AES-GCM encryption algorithm
         JceMasterKey masterKey = JceMasterKey.getInstance(cryptoKey, "Example", "RandomKey", "AES/GCM/NoPadding");
 
-        // Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // Instantiate the SDK.
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // Create an encryption context to identify this ciphertext
         Map<String, String> context = Collections.singletonMap("Example", "FileStreaming");

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

@@ -41,9 +41,15 @@ public static void main(final String[] args) {
     }
 
     static void encryptAndDecrypt(final String keyArn1, final String keyArn2) {
-        // 1. Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // Instantiate the SDK.
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // 2. Instantiate an AWS KMS master key provider to encrypt with
         // In strict mode (`buildStrict`), the AWS KMS master key provider encrypts and decrypts only by using the

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

@@ -49,9 +49,15 @@ public static void main(final String[] args) {
     }
 
     static void encryptAndDecrypt(final String keyName, final String partition, final String accountId, final String region) {
-        // 1. Instantiate the SDK with a specific commitment policy.
-        // ForbidEncryptAllowDecrypt is the only available policy in 1.7.0.
-        final AwsCrypto crypto = AwsCrypto.builder().withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt).build();
+        // Instantiate the SDK.
+        // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
+        // which enforces that this client only encrypts using committing algorithm suites and enforces
+        // that this client will only decrypt encrypted messages that were created with a committing algorithm suite.
+        // This is the default commitment policy if you build the client with `AwsCrypto.builder().build()`
+        // or `AwsCrypto.standard()`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
+                .build();
 
         // 2. Instantiate the AWS KMS client for the desired region
         final AWSKMS kmsClient = AWSKMSClientBuilder.standard().withRegion(region).build();

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

@@ -0,0 +1,96 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.amazonaws.crypto.examples;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Map;
+
+import com.amazonaws.encryptionsdk.AwsCrypto;
+import com.amazonaws.encryptionsdk.CommitmentPolicy;
+import com.amazonaws.encryptionsdk.CryptoResult;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
+
+/**
+ * <p>
+ * Configures a client with a specific commitment policy, then
+ * encrypts and decrypts data using an AWS KMS customer master key.
+ *
+ * This configuration should only be used as part of a migration from version 1.x to 2.x, or for advanced users
+ * with specialized requirements. We recommend that AWS Encryption SDK users use the default commitment policy
+ * whenever possible.
+ *
+ * <p>
+ * Arguments:
+ * <ol>
+ * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
+ *    key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
+ * </ol>
+ */
+public class SetCommitmentPolicyExample {
+
+    private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
+
+    public static void main(final String[] args) {
+        final String keyArn = args[0];
+
+        encryptAndDecrypt(keyArn);
+    }
+
+    static void encryptAndDecrypt(final String keyArn) {
+        // 1. Instantiate the SDK with a specific commitment policy
+        //
+        // `withCommitmentPolicy(CommitmentPolicy)` configures the client with
+        // a commitment policy that dictates whether the client is required to encrypt
+        // using committing algorithms and whether the client must require that the messages
+        // it decrypts were encrypted using committing algorithms.
+        // In this example, we set the commitment policy to `ForbidEncryptAllowDecrypt`.
+        // This policy enforces that the client writes using non-committing algorithms,
+        // and allows decrypting of messages created with committing algorithms.
+        //
+        // If this value is not set, the client is configured to use our recommended default:
+        // `RequireEncryptRequireDecrypt`.
+        // This policy enforces that the client uses committing algorithms
+        // to encrypt and enforces that the client only decrypts messages created with committing algorithms.
+        // We recommend using the default whenever possible.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
+                .build();
+
+        // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict()
+        // In strict mode, the AWS KMS master key provider encrypts and decrypts only by using the key
+        // indicated by keyArn.
+        // To encrypt and decrypt with this master key provider, use an AWS KMS key ARN to identify the CMKs.
+        // In strict mode, the decrypt operation requires a key ARN.
+        final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder().buildStrict(keyArn);
+
+        // 3. Create an encryption context
+        // 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
+        final Map<String, String> encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
+
+        // 4. Encrypt the data
+        final CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(keyProvider, EXAMPLE_DATA, encryptionContext);
+        final byte[] ciphertext = encryptResult.getResult();
+
+        // 5. Decrypt the data
+        final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext);
+
+        // 6. 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!");
+        }
+
+        // 7. Verify that the decrypted plaintext matches the original plaintext
+        assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
+    }
+}

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

@@ -0,0 +1,93 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.amazonaws.crypto.examples;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Map;
+
+import com.amazonaws.encryptionsdk.AwsCrypto;
+import com.amazonaws.encryptionsdk.CryptoAlgorithm;
+import com.amazonaws.encryptionsdk.CryptoResult;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
+
+/**
+ * <p>
+ * Configures a client with a specific encryption algorithm, then
+ * encrypts and decrypts data using that encryption algorithm and
+ * an AWS KMS customer master key.
+ *
+ * <p>
+ * Arguments:
+ * <ol>
+ * <li>Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
+ *    key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
+ * </ol>
+ */
+public class SetEncryptionAlgorithmExample {
+
+    private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
+
+    public static void main(final String[] args) {
+        final String keyArn = args[0];
+
+        encryptAndDecrypt(keyArn);
+    }
+
+    static void encryptAndDecrypt(final String keyArn) {
+        // 1. Instantiate the SDK with the algorithm for encryption
+        //
+        // `withEncryptionAlgorithm(cryptoAlgorithm)` configures the client to encrypt
+        // using a specified encryption algorithm.
+        // This example sets the encryption algorithm to
+        // `CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`,
+        // which is an algorithm that does not contain message signing.
+        //
+        // If this value is not set, the client encrypts with the recommended default:
+        // `CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384`.
+        // We recommend using the default whenever possible.
+        // For a description of our supported algorithms, see https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html
+        //
+        // You can update the encryption algorithm after constructing the client
+        // by using `crypto.setEncryptionAlgorithm(CryptoAlgorithm)`.
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
+                .build();
+
+        // 2. Instantiate an AWS KMS master key provider in strict mode using buildStrict().
+        // In strict mode, the AWS KMS master key provider encrypts and decrypts only by using the key
+        // indicated by keyArn.
+        // To encrypt and decrypt with this master key provider, use an AWS KMS key ARN to identify the CMKs.
+        // In strict mode, the decrypt operation requires a key ARN.
+        final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder().buildStrict(keyArn);
+
+        // 3. Create an encryption context
+        // 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
+        final Map<String, String> encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
+
+        // 4. Encrypt the data
+        final CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(keyProvider, EXAMPLE_DATA, encryptionContext);
+        final byte[] ciphertext = encryptResult.getResult();
+
+        // 5. Decrypt the data
+        final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext);
+
+        // 6. 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!");
+        }
+
+        // 7. Verify that the decrypted plaintext matches the original plaintext
+        assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
+    }
+}