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.

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

Author: lavaleri

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.7.0 -- 2020-09-24
+
+* feat: Updates to the AWS Encryption SDK.
+
 ## 1.6.2 -- 2020-05-26
 
 ### Patches

README.md

@@ -56,7 +56,7 @@ You can get the latest release from Maven:
 <dependency>
   <groupId>com.amazonaws</groupId>
   <artifactId>aws-encryption-sdk-java</artifactId>
-  <version>1.6.2</version>
+  <version>1.7.0</version>
 </dependency>
 ```
 
@@ -77,6 +77,7 @@ 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;
@@ -90,10 +91,12 @@ public class StringExample {
         data = args[1];
 
         // Instantiate the SDK
-        final AwsCrypto crypto = new AwsCrypto();
+        final AwsCrypto crypto = AwsCrypto.builder()
+                .withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
+                .build();
 
         // Set up the master key provider
-        final KmsMasterKeyProvider prov = new KmsMasterKeyProvider(keyArn);
+        final KmsMasterKeyProvider prov = KmsMasterKeyProvider.builder().buildStrict(keyArn);
 
         // Encrypt the data
         //

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>com.amazonaws</groupId>
     <artifactId>aws-encryption-sdk-java</artifactId>
-    <version>1.6.2</version>
+    <version>1.7.0</version>
     <packaging>jar</packaging>
 
     <name>aws-encryption-sdk-java</name>
@@ -142,6 +142,54 @@
     </build>
 
     <profiles>
+        <profile>
+            <id>publishingCodeArtifact</id>
+
+            <distributionManagement>
+                <!--
+                Registers an alternate repository for testing the publishing process using CodeArtifact
+                before moving to the production sonatype repository.
+
+                This can be used with a mvn invocation like:
+
+                mvn deploy -PpublishingCodeArtifact \
+                           -DaltDeploymentRepository=codeartifact::default::$CODEARTIFACT_REPO_URL \
+                           ...
+                -->
+                <repository>
+                    <id>codeartifact</id>
+                    <name>codeartifact</name>
+                    <!-- url specified using -DaltDeploymentRepository to avoid hardcoding it here -->
+                </repository>
+            </distributionManagement>
+
+            <!-- TODO: figure out how to share this config between the two publishing profiles -->
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-gpg-plugin</artifactId>
+                        <version>1.6</version>
+                        <executions>
+                            <execution>
+                                <id>sign-artifacts</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>sign</goal>
+                                </goals>
+                                <configuration>
+                                    <gpgArguments>
+                                        <arg>--pinentry-mode</arg>
+                                        <arg>loopback</arg>
+                                    </gpgArguments>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+
         <profile>
             <id>publishing</id>
 

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

@@ -1,15 +1,5 @@
-/*
- * Copyright 2019 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.
- */
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 package com.amazonaws.crypto.examples;
 
@@ -22,6 +12,7 @@
 import com.amazonaws.encryptionsdk.CryptoResult;
 import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
 import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
+import com.amazonaws.encryptionsdk.CommitmentPolicy;
 
 /**
  * <p>
@@ -45,35 +36,32 @@ public static void main(final String[] args) {
     }
 
     static void encryptAndDecrypt(final String keyArn) {
-        // 1. Instantiate the SDK
-        final AwsCrypto crypto = new AwsCrypto();
+        // 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();
 
-        // 2. Instantiate a KMS master key provider
-        final KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder().withKeysForEncryption(keyArn).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.
+        // The decrypt operation doesn't work with any other key identifier in strict mode.
+        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(masterKeyProvider, EXAMPLE_DATA, encryptionContext);
+        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(masterKeyProvider, ciphertext);
-
-        // 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)) {
-            throw new IllegalStateException("Wrong key ID!");
-        }
+        final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext);
 
-        // 7. Also, verify that the encryption context in the result contains the
+        // 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.
@@ -82,7 +70,7 @@ static void encryptAndDecrypt(final String keyArn) {
             throw new IllegalStateException("Wrong Encryption Context!");
         }
 
-        // 8. Verify that the decrypted plaintext matches the original plaintext
+        // 7. Verify that the decrypted plaintext matches the original plaintext
         assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
     }
 }

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

@@ -0,0 +1,103 @@
+// 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.CryptoResult;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
+import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
+import com.amazonaws.encryptionsdk.CommitmentPolicy;
+import com.amazonaws.encryptionsdk.kms.DiscoveryFilter;
+
+/**
+ * <p>
+ * Encrypts and then decrypts data using an AWS KMS customer master key in discovery mode.
+ * Discovery mode is useful when you use an alias to identify a CMK when encrypting and the
+ * underlying key ARN might vary in each AWS Region.
+ * <p>
+ * Arguments:
+ * <ol>
+ * <li>Key Name: An identifier for the AWS KMS customer master key (CMK) to use. For example,
+ *     a key ARN or a key alias.
+ *     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
+ * <li>Partition: The partition of the AWS KMS customer master key, which is usually "aws."
+ *     A partition is a group of regions. The partition is the second element in the key ARN, e.g. "arn" in "aws:aws: ..."
+ * <li>Account ID: The identifier for the account of the AWS KMS customer master key.
+ * </ol>
+ */
+public class DiscoveryDecryptionExample {
+
+    private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
+
+    public static void main(final String[] args) {
+        final String keyName = args[0];
+        final String partition = args[1];
+        final String accountId = args[2];
+
+        encryptAndDecrypt(keyName, partition, accountId);
+    }
+
+    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();
+
+        // 2. Instantiate an AWS KMS master key provider for encryption.
+        //
+        // In strict mode (`buildStrict`), the AWS KMS master key provider encrypts and decrypts only by using the key
+        // indicated by keyName.
+        final KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder().buildStrict(keyName);
+
+        // 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(encryptingKeyProvider, EXAMPLE_DATA, encryptionContext);
+        final byte[] ciphertext = encryptResult.getResult();
+
+        // 5. Instantiate a discovery filter for decrypting. This filter restricts what AWS KMS CMKs the
+        // AWS KMS master key provider can use to those in a particular AWS partition and account.
+        // You can create a similar filter with one partition and multiple AWS accounts.
+        // This example only configures the filter with one account, but more may be specified
+        // as long as they exist within the same partition.
+        // This filter is not required for Discovery mode, but is a best practice.
+        final DiscoveryFilter discoveryFilter = new DiscoveryFilter(partition, accountId);
+
+        // 6. Instantiate an AWS KMS master key provider for decryption in discovery mode (`buildDiscovery`) with a
+        // Discovery Filter.
+        //
+        // In discovery mode, the AWS KMS master key provider attempts to decrypt only by using AWS KMS ARNs
+        // indicated in the encrypted message.
+        // By configuring the master key provider with a Discovery Filter, this master key provider
+        // attempts to decrypt AWS KMS CMKs only in the configured partition and accounts.
+        final KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder().buildDiscovery(discoveryFilter);
+
+        // 7. Decrypt the data
+        final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(decryptingKeyProvider, ciphertext);
+
+        // 8. 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!");
+        }
+
+        // 9. Verify that the decrypted plaintext matches the original plaintext
+        assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
+    }
+}