feat: allow S3EncryptionClient and S3AsyncEncryption Client to be configured (#328)

* feat: add top level client configuration option
* add top-level creds option for async
* add test using alternate role
* add Cfn changes, another test
* other async options
* readme updates
* java formatting

Author: kessplas

.github/workflows/build.yml

@@ -46,6 +46,8 @@ jobs:
 
       - name: Test
         run: |
+          export AWS_S3EC_TEST_ALT_KMS_KEY_ARN=arn:aws:kms:${{ vars.CI_AWS_REGION }}:${{ secrets.CI_AWS_ACCOUNT_ID }}:key/${{ vars.CI_ALT_KMS_KEY_ID }}
+          export AWS_S3EC_TEST_ALT_ROLE_ARN=arn:aws:iam::${{ secrets.CI_AWS_ACCOUNT_ID }}:role/service-role/${{ vars.CI_ALT_ROLE }}
           export AWS_S3EC_TEST_BUCKET=${{ vars.CI_S3_BUCKET }}
           export AWS_S3EC_TEST_KMS_KEY_ID=arn:aws:kms:${{ vars.CI_AWS_REGION }}:${{ secrets.CI_AWS_ACCOUNT_ID }}:key/${{ vars.CI_KMS_KEY_ID }}
           export AWS_S3EC_TEST_KMS_KEY_ALIAS=arn:aws:kms:${{ vars.CI_AWS_REGION }}:${{ secrets.CI_AWS_ACCOUNT_ID }}:alias/${{ vars.CI_KMS_KEY_ALIAS }}

README.md

@@ -33,6 +33,8 @@ The other values are added as variables (by clicking the "New repository variabl
 * `CI_S3_BUCKET` - the S3 bucket to use, e.g. s3ec-github-test-bucket.
 * `CI_KMS_KEY_ID` - the short KMS key ID to use, e.g. c3eafb5f-e87d-4584-9400-cf419ce5d782.
 * `CI_KMS_KEY_ALIAS` - the KMS key alias to use, e.g. S3EC-Github-KMS-Key. Note that the alias must reference the key ID above.
+* `CI_ALT_ROLE` - an alternate role to use that is different from the role defined above. It must have permission to use the KMS key below and the S3 bucket above.
+* `CI_ALT_KMS_KEY_ID`- the KMS key of an alternate KMS key to use. The alternate role must have access to use the key and the role for `CI_AWS_ROLE` must not have access to the key.
 
 ## Migration
 
@@ -44,6 +46,12 @@ However, this version does not support V2's Unencrypted Object Passthrough.
 This library can only read encrypted objects from S3,
 unencrypted objects MUST be read with the base S3 Client.
 
+## Client Configuration
+
+The S3 Encryption Client uses "wrapped" clients to make its requests to S3 and/or KMS.
+You can configure each client independently, or apply a "top-level" configuration which is applied to all wrapped clients.
+Refer to the Client Configuration Example in the [Examples directory](https://github.com/aws/amazon-s3-encryption-client-java/tree/main/src/examples/java/software/amazon/encryption/s3/examples) for examples of each configuration method.
+
 ### Examples
 #### V2 KMS Materials Provider to V3
 ```java

cfn/S3EC-GitHub-CF-Template.yml

@@ -14,6 +14,20 @@ Resources:
             Action: 'kms:*'
             Resource: '*'
 
+  S3ECGitHubKMSKeyIDAlternate:
+    Type: 'AWS::KMS::Key'
+    Properties:
+      Description: Alternate KMS Key for GitHub Action Workflow
+      Enabled: true
+      KeyPolicy:
+        Version: 2012-10-17
+        Statement:
+          - Effect: Allow
+            Principal:
+              AWS: !Sub 'arn:aws:iam::${AWS::AccountId}:root'
+            Action: 'kms:*'
+            Resource: '*'
+
   S3ECGitHubKMSKeyAlias:
     Type: 'AWS::KMS::Alias'
     Properties:
@@ -73,6 +87,89 @@ Resources:
         }
       ManagedPolicyName: S3EC-GitHub-KMS-Key-Policy
 
+  S3ECGitHubKMSKeyPolicyAlternate:
+    Type: 'AWS::IAM::ManagedPolicy'
+    Properties:
+      PolicyDocument: !Sub |
+        {
+          "Version": "2012-10-17",
+          "Statement": [
+            {
+              "Effect": "Allow",
+              "Resource": [
+                "arn:aws:kms:*:${AWS::AccountId}:key/${S3ECGitHubKMSKeyIDAlternate}"
+              ],
+              "Action": [
+                "kms:Decrypt",
+                "kms:GenerateDataKey",
+                "kms:GenerateDataKeyPair"
+              ]
+            }
+          ]
+        }
+      ManagedPolicyName: S3EC-GitHub-KMS-Key-Policy-Alternate
+
+  S3ECGithubTestRoleAlternate:
+    Type: 'AWS::IAM::Role'
+    Properties:
+      Path: /service-role/
+      RoleName: S3EC-GitHub-test-role-alternate
+      AssumeRolePolicyDocument: !Sub |
+        {
+          "Version": "2012-10-17",   
+          "Statement": [
+            {
+              "Effect": "Allow",
+              "Principal": { "Federated": "arn:aws:iam::${AWS::AccountId}:oidc-provider/token.actions.githubusercontent.com" },
+              "Action": "sts:AssumeRoleWithWebIdentity",
+              "Condition": {
+                  "StringEquals": {
+                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+                  },
+                  "StringLike": {
+                    "token.actions.githubusercontent.com:sub": "repo:aws/amazon-s3-encryption-client-java:*"
+                  }
+               }
+            },
+            {
+              "Effect": "Allow",
+              "Principal": { "AWS": "arn:aws:iam::${AWS::AccountId}:role/ToolsDevelopment" },
+              "Action": "sts:AssumeRole"
+            },
+            {
+              "Effect": "Allow",
+              "Principal": { "AWS": "arn:aws:iam::${AWS::AccountId}:role/service-role/S3EC-GitHub-test-role" },
+              "Action": "sts:AssumeRole"
+            }
+          ]
+        }
+      Description: >-
+        Grant GitHub S3 put and get and KMS (alt key) encrypt, decrypt, and generate access
+        for testing
+      ManagedPolicyArns:
+        - !Ref S3ECGitHubKMSKeyPolicyAlternate
+        - !Ref S3ECGitHubS3BucketPolicy
+
+  S3ECGitHubAssumeAlternatePolicy:
+    Type: 'AWS::IAM::ManagedPolicy'
+    Properties:
+      PolicyDocument: !Sub |
+        {
+          "Version": "2012-10-17",
+          "Statement": [
+            {
+              "Effect": "Allow",
+              "Resource": [
+                "arn:aws:iam::${AWS::AccountId}:role/service-role/${S3ECGithubTestRoleAlternate}"
+              ],
+              "Action": [
+                "sts:AssumeRole"
+              ]
+            }
+          ]
+        }
+      ManagedPolicyName: S3EC-GitHub-Assume-Alternate-Policy
+
   S3ECGithubTestRole:
     Type: 'AWS::IAM::Role'
     Properties:
@@ -108,3 +205,6 @@ Resources:
       ManagedPolicyArns:
         - !Ref S3ECGitHubKMSKeyPolicy
         - !Ref S3ECGitHubS3BucketPolicy
+        - !Ref S3ECGitHubAssumeAlternatePolicy
+
+

pom.xml

@@ -155,6 +155,14 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>sts</artifactId>
+      <version>2.20.38</version>
+      <optional>true</optional>
+      <scope>test</scope>
+    </dependency>
+
   </dependencies>
 
   <build>

src/examples/java/software/amazon/encryption/s3/examples/AsyncClientExample.java

@@ -1,9 +1,5 @@
 package software.amazon.encryption.s3.examples;
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static software.amazon.encryption.s3.utils.S3EncryptionClientTestResources.KMS_KEY_ID;
-import static software.amazon.encryption.s3.utils.S3EncryptionClientTestResources.appendTestSuffix;
-
 import software.amazon.awssdk.core.ResponseBytes;
 import software.amazon.awssdk.core.async.AsyncRequestBody;
 import software.amazon.awssdk.core.async.AsyncResponseTransformer;
@@ -14,6 +10,10 @@
 
 import java.util.concurrent.CompletableFuture;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static software.amazon.encryption.s3.utils.S3EncryptionClientTestResources.KMS_KEY_ID;
+import static software.amazon.encryption.s3.utils.S3EncryptionClientTestResources.appendTestSuffix;
+
 public class AsyncClientExample {
     public static final String OBJECT_KEY = appendTestSuffix("async-client-example");
 
@@ -33,7 +33,7 @@ public static void AsyncClient(String bucket) {
         final String input = "PutAsyncGetAsync";
 
         // Instantiate the S3 Async Encryption Client to encrypt and decrypt
-        // by specifying an AES Key with the aesKey builder parameter.
+        // by specifying a KMS key with the kmsKeyId parameter.
         //
         // This means that the S3 Async Encryption Client can perform both encrypt and decrypt operations
         // as part of the S3 putObject and getObject operations.