Use AWSKMSClientBuilder

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

@@ -0,0 +1,71 @@
+package com.amazonaws.crypto.examples;
+
+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.kms.KmsMasterKeyProviderBuilder;
+
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * <p>
+ * Encrypts and then decrypts a string under a KMS key
+ *
+ * <p>
+ * Arguments:
+ * <ol>
+ * <li>KMS Key Arn
+ * <li>String to encrypt
+ * </ol>
+ */
+public class BuilderExample {
+
+    private static String keyArn;
+    private static String data;
+
+    public static void main(final String[] args) {
+        keyArn = args[0];
+        data = args[1];
+
+        // Instantiate the SDK
+        final AwsCrypto crypto = new AwsCrypto();
+
+        // Set up the KmsMasterKeyProvider using the defaults provided by the KmsMasterKeyProviderBuilder
+        final KmsMasterKeyProvider prov = KmsMasterKeyProviderBuilder.standard()
+                .withKeyId(keyArn)
+                .build();
+
+        // Encrypt the data
+        //
+        // Most encrypted data should have associated encryption context
+        // to protect integrity. Here, we'll just use a placeholder value.
+        //
+        // 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> context = Collections.singletonMap("Example", "String");
+
+        final String ciphertext = crypto.encryptString(prov, data, context).getResult();
+        System.out.println("Ciphertext: " + ciphertext);
+
+        // Decrypt the data
+        final CryptoResult<String, KmsMasterKey> decryptResult = crypto.decryptString(prov, ciphertext);
+        // We need to check the encryption context (and ideally key) to ensure that
+        // this was the ciphertext we expected
+        if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) {
+            throw new IllegalStateException("Wrong key id!");
+        }
+
+        // The SDK may add information to the encryption context, so we check to ensure
+        // that all of our values are present
+        for (final Map.Entry<String, String> e : context.entrySet()) {
+            if (!e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey()))) {
+                throw new IllegalStateException("Wrong Encryption Context!");
+            }
+        }
+
+        // Now that we know we have the correct data, we can output it.
+        System.out.println("Decrypted: " + decryptResult.getResult());
+    }
+}

src/main/java/com/amazonaws/encryptionsdk/kms/KmsMasterKeyProvider.java

@@ -131,10 +131,19 @@ public KmsMasterKeyProvider(final AWSKMS kms, final Region region, final List<St
         kms_ = kms;
         region_ = region;
         regionName_ = region.getName();
-        kms_.setRegion(region);
+        // When kms_ is created by the builder, it is immutable and will throw an exception when setting something
+        try {
+            kms_.setRegion(region);
+        } catch (UnsupportedOperationException e) {
+            // Ignored. Not a problem, region should already be set by the builder.
+        }
         keyIds_ = new ArrayList<>(keyIds);
     }
 
+    public static KmsMasterKeyProviderBuilder builder() {
+        return KmsMasterKeyProviderBuilder.standard();
+    }
+
     /**
      * Returns "aws-kms"
      */
@@ -215,6 +224,8 @@ public void addGrantToken(final String grantToken) {
      * Configures this provider to use a custom endpoint. Sets the underlying {@link Region} object
      * to {@code null}, and instructs the internal KMS client to use the specified {@code endPoint}
      * and {@code regionName}.
+     *
+     * Note: This method will not work if this object was created by {@link KmsMasterKeyProviderBuilder}.
      */
     public void setCustomEndpoint(final String regionName, final String endPoint) {
         if (kms_ instanceof AWSKMSClient) {
@@ -231,6 +242,8 @@ public void setCustomEndpoint(final String regionName, final String endPoint) {
      * Set the AWS region of the AWS KMS service for access to the master key. This method simply
      * calls the same method of the underlying {@link AWSKMSClient}
      *
+     * Note: This method will not work if this object was created by {@link KmsMasterKeyProviderBuilder}.
+     *
      * @param region
      *            string containing the region.
      */
@@ -244,7 +257,7 @@ public Region getRegion() {
         return region_;
     }
 
-    private static Region getStartingRegion(final String keyArn) {
+    static Region getStartingRegion(final String keyArn) {
         final String region = parseRegionfromKeyArn(keyArn);
         if (region != null) {
             return Region.getRegion(Regions.fromName(region));

src/main/java/com/amazonaws/encryptionsdk/kms/KmsMasterKeyProviderBuilder.java

@@ -0,0 +1,125 @@
+package com.amazonaws.encryptionsdk.kms;
+
+import com.amazonaws.ClientConfigurationFactory;
+import com.amazonaws.client.AwsSyncClientParams;
+import com.amazonaws.client.builder.AwsClientBuilder;
+import com.amazonaws.regions.AwsRegionProvider;
+import com.amazonaws.regions.DefaultAwsRegionProviderChain;
+import com.amazonaws.regions.Region;
+import com.amazonaws.regions.RegionUtils;
+import com.amazonaws.regions.Regions;
+import com.amazonaws.services.kms.AWSKMSClient;
+import com.amazonaws.services.kms.AWSKMSClientBuilder;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Used to build a {@link KmsMasterKeyProvider} which will use the defaults found in the relevant provider chains.
+ *
+ * If a region is not defined and no region can be found in the region provider chain, then
+ * {@link Regions#DEFAULT_REGION} is used.
+ * <pre>
+ *     KmsMasterKeyProvider keyProvider = KmsMasterKeyProviderBuilder.defaultProvider();
+ * </pre>
+ *
+ * Example, specifying a region:
+ * <pre>
+ *     KmsMasterKeyProvider keyProvider = KmsMasterKeyProviderBuilder.standard()
+ *       .withDefaultRegion("us-east-1")
+ *       .build();
+ * </pre>
+ */
+public class KmsMasterKeyProviderBuilder extends AwsClientBuilder<KmsMasterKeyProviderBuilder, KmsMasterKeyProvider> {
+
+    private List<String> keyIds;
+
+    /**
+     * @return a new {@link KmsMasterKeyProviderBuilder} with the defaults set.
+     */
+    public static KmsMasterKeyProviderBuilder standard() {
+        return new KmsMasterKeyProviderBuilder();
+    }
+
+    /**
+     * @return a KmsMasterKeyProvider using the {@link AWSKMSClientBuilder} defaults, and an empty key ID list.
+     */
+    public static KmsMasterKeyProvider defaultProvider() {
+        return standard().build();
+    }
+
+    private KmsMasterKeyProviderBuilder() {
+        super(new ClientConfigurationFactory());
+    }
+
+    /**
+     * Sets the default region to be used by the client. Overrides any previously set region.
+     */
+    public KmsMasterKeyProviderBuilder withDefaultRegion(Region region) {
+        return withRegion(region.getName());
+    }
+
+    /**
+     * Sets the region using a keyId. This will override any previously set regions.
+     */
+    public KmsMasterKeyProviderBuilder withKeyId(String keyId) {
+        withKeyIds(Collections.singletonList(keyId));
+
+        withDefaultRegion(KmsMasterKeyProvider.getStartingRegion(keyId));
+
+        return this;
+    }
+
+    /**
+     * Adds {@code keyIds}, but does not use them to set the region.
+     */
+    public KmsMasterKeyProviderBuilder withKeyIds(List<String> keyIds) {
+        if (this.keyIds == null) {
+            this.keyIds = new ArrayList<>();
+        }
+
+        this.keyIds.addAll(keyIds);
+
+        return this;
+    }
+
+    /**
+     * Builds a {@link KmsMasterKeyProvider} using the information it was built with, or with defaults where necessary.
+     */
+    @Override
+    public KmsMasterKeyProvider build() {
+        return build(getSyncClientParams());
+    }
+
+    private KmsMasterKeyProvider build(AwsSyncClientParams clientParams) {
+        keyIds = (keyIds == null) ? Collections.emptyList() : keyIds;
+
+        AWSKMSClient client = new AWSKMSClient(clientParams.getCredentialsProvider(),
+                clientParams.getClientConfiguration(),
+                clientParams.getRequestMetricCollector());
+
+        Region region = determineRegion();
+
+        return new KmsMasterKeyProvider(client,
+                region,
+                keyIds);
+    }
+
+    private Region determineRegion() {
+        Region region = RegionUtils.getRegion(this.getRegion());
+
+        final AwsRegionProvider regionProvider = new DefaultAwsRegionProviderChain();
+
+        if (region != null) {
+            return region;
+        } else {
+            final String regionName = regionProvider.getRegion();
+            if (regionName != null) {
+                return Region.getRegion(Regions.fromName(regionName));
+            } else {
+                return Region.getRegion(Regions.DEFAULT_REGION);
+            }
+        }
+    }
+}