Merge branch 'main' into imabhichow/update-releaserc

Author: imabhichow

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "specification"]
 	path = specification
-	url = [email protected]:awslabs/aws-encryption-sdk-specification.git
-	branch = kessplas/s3-ec-v3
+	url = [email protected]:awslabs/private-aws-encryption-sdk-specification-staging.git
+	branch = fire-egg-staging

specification

@@ -0,0 +1,79 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package software.amazon.encryption.s3;
+
+/**
+ * Defines the S3 Encryption Client's key commitment behavior during encryption and decryption operations.
+ * Key commitment ensures each encrypted object can be decrypted to only a single plaintext by cryptographically binding the data key to the encrypted object.
+ * <p>
+ * For more information, refer to the <a href=https://docs.aws.amazon.com/amazon-s3-encryption-client/latest/developerguide/concepts.html)>Developer Guide.</a>
+ */
+public enum CommitmentPolicy {
+
+    //= specification/s3-encryption/key-commitment.md#commitment-policy
+    //# When the commitment policy is FORBID_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST allow decryption using algorithm suites which do not support key commitment.
+    /**
+     * This policy forbids the client from encrypting objects with an algorithm suite which supports key commitment.
+     * This policy allows decryption of objects using algorithm suites which do not support key commitment. Objects encrypted with key commitment may be decrypted as well.
+     * <p>
+     * This client will write objects that any v3 client can read and any v4 client can read.
+     * This client can read objects written by any v3 or v4 client.
+     * This is the default (and only) policy for v3 clients.
+     */
+    FORBID_ENCRYPT_ALLOW_DECRYPT(false, false),
+
+    //= specification/s3-encryption/key-commitment.md#commitment-policy
+    //# When the commitment policy is REQUIRE_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST only encrypt using an algorithm suite which supports key commitment.
+    //= specification/s3-encryption/key-commitment.md#commitment-policy
+    //# When the commitment policy is REQUIRE_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST allow decryption using algorithm suites which do not support key commitment.
+    /**
+     * This policy requires the client to encrypt objects using an algorithm suite which supports key commitment.
+     * This policy allows decryption of objects using algorithm suites which do not support key commitment. Objects encrypted with key commitment may be decrypted as well.
+     * <p>
+     * This client will write objects that any v4 client can read.
+     * Only V4 clients and the latest V3 client can read objects written by a client using this policy.
+     * This client can read objects written by any V3 or V4 client.
+     */
+    REQUIRE_ENCRYPT_ALLOW_DECRYPT(true, false),
+
+    //= specification/s3-encryption/key-commitment.md#commitment-policy
+    //# When the commitment policy is REQUIRE_ENCRYPT_REQUIRE_DECRYPT, the S3EC MUST only encrypt using an algorithm suite which supports key commitment.
+    //= specification/s3-encryption/key-commitment.md#commitment-policy
+    //# When the commitment policy is REQUIRE_ENCRYPT_REQUIRE_DECRYPT, the S3EC MUST NOT allow decryption using algorithm suites which do not support key commitment.
+    /**
+     * This policy requires the client to encrypt objects using an algorithm suite which supports key commitment.
+     * This policy requires that objects have been encrypted using an algorithm suite which supports key commitment. 
+     * <p>
+     * This client will write objects that any v4 client can read.
+     * Only V4 clients and the latest V3 clients can read objects written by a client using this policy.
+     * This client can only read objects written by v4 clients with key commitment enabled.
+     * This is the most secure policy and should be used when all objects are encrypted with key commitment.
+     */
+    REQUIRE_ENCRYPT_REQUIRE_DECRYPT(true, true);
+
+    private final boolean _requiresEncrypt;
+    private final boolean _requiresDecrypt;
+
+    CommitmentPolicy(boolean requiresEncrypt, boolean requiresDecrypt) {
+        _requiresEncrypt = requiresEncrypt;
+        _requiresDecrypt = requiresDecrypt;
+    }
+
+    /**
+     * Indicates whether this commitment policy requires key commitment for encryption operations.
+     *
+     * @return {@code true} if encryption must use algorithm suites that support key commitment
+     */
+    public boolean requiresEncrypt() {
+        return _requiresEncrypt;
+    }
+
+    /**
+     * Indicates whether this commitment policy requires key commitment for decryption operations.
+     *
+     * @return {@code true} if decryption can only succeed for messages with valid key commitment
+     */
+    public boolean requiresDecrypt() {
+        return _requiresDecrypt;
+    }
+}

src/main/java/software/amazon/encryption/s3/CommitmentPolicy.java

@@ -2,6 +2,24 @@
 // SPDX-License-Identifier: Apache-2.0
 package software.amazon.encryption.s3;
 
+import static software.amazon.encryption.s3.S3EncryptionClientUtilities.DEFAULT_BUFFER_SIZE_BYTES;
+import static software.amazon.encryption.s3.S3EncryptionClientUtilities.MAX_ALLOWED_BUFFER_SIZE_BYTES;
+import static software.amazon.encryption.s3.S3EncryptionClientUtilities.MIN_ALLOWED_BUFFER_SIZE_BYTES;
+import static software.amazon.encryption.s3.internal.ApiNameVersion.API_NAME_INTERCEPTOR;
+
+import java.net.URI;
+import java.security.KeyPair;
+import java.security.Provider;
+import java.security.SecureRandom;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Consumer;
+import java.util.function.Function;
+
+import javax.crypto.SecretKey;
+
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
 import software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration;
@@ -37,6 +55,7 @@
 import software.amazon.awssdk.services.s3.model.UploadPartRequest;
 import software.amazon.awssdk.services.s3.model.UploadPartResponse;
 import software.amazon.awssdk.services.s3.multipart.MultipartConfiguration;
+import software.amazon.encryption.s3.algorithms.AlgorithmSuite;
 import software.amazon.encryption.s3.internal.GetEncryptedObjectPipeline;
 import software.amazon.encryption.s3.internal.InstructionFileConfig;
 import software.amazon.encryption.s3.internal.NoRetriesAsyncRequestBody;
@@ -49,26 +68,12 @@
 import software.amazon.encryption.s3.materials.PartialRsaKeyPair;
 import software.amazon.encryption.s3.materials.RsaKeyring;
 
-import javax.crypto.SecretKey;
-import java.net.URI;
-import java.security.KeyPair;
-import java.security.Provider;
-import java.security.SecureRandom;
-import java.util.List;
-import java.util.Map;
-import java.util.Optional;
-import java.util.concurrent.CompletableFuture;
-import java.util.function.Consumer;
-import java.util.function.Function;
-
-import static software.amazon.encryption.s3.S3EncryptionClientUtilities.DEFAULT_BUFFER_SIZE_BYTES;
-import static software.amazon.encryption.s3.S3EncryptionClientUtilities.MAX_ALLOWED_BUFFER_SIZE_BYTES;
-import static software.amazon.encryption.s3.S3EncryptionClientUtilities.MIN_ALLOWED_BUFFER_SIZE_BYTES;
-import static software.amazon.encryption.s3.internal.ApiNameVersion.API_NAME_INTERCEPTOR;
-
 /**
  * This client is a drop-in replacement for the S3 Async client. It will automatically encrypt objects
  * on putObject and decrypt objects on getObject using the provided encryption key(s).
+ * 
+ * This major version uses AES_GCM_HKDF_SHA512_COMMIT_KEY by default and only recent minor versions
+ * of the previous major version can decrypt these objects.
  */
 public class S3AsyncEncryptionClient extends DelegatingS3AsyncClient {
 
@@ -80,6 +85,7 @@ public class S3AsyncEncryptionClient extends DelegatingS3AsyncClient {
     private final boolean _enableMultipartPutObject;
     private final long _bufferSize;
     private final InstructionFileConfig _instructionFileConfig;
+    private final CommitmentPolicy _commitmentPolicy;
 
     private S3AsyncEncryptionClient(Builder builder) {
         super(builder._wrappedClient);
@@ -91,16 +97,29 @@ private S3AsyncEncryptionClient(Builder builder) {
         _enableMultipartPutObject = builder._enableMultipartPutObject;
         _bufferSize = builder._bufferSize;
         _instructionFileConfig = builder._instructionFileConfig;
+        _commitmentPolicy = builder._commitmentPolicy;
     }
 
     /**
      * Creates a builder that can be used to configure and create a {@link S3AsyncEncryptionClient}.
      */
+    @Deprecated
     public static Builder builder() {
-        return new Builder();
+        // Defaults to ForbidEncryptAllowDecrypt and ALG_AES_256_GCM_IV12_TAG16_NO_KDF
+        return new Builder(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF);
     }
 
 
+
+    /**
+     * Creates a V4 Transition builder that can be used to configure and create a {@link S3AsyncEncryptionClient}.
+     */
+    public static Builder builderV4() {
+        // NewBuilder introduced which REQUIRES commitmentPolicy and encryptionAlgorithm
+        // to be set and is V4 compatible
+        return new Builder();
+    }
+
     /**
      * Attaches encryption context to a request. Must be used as a parameter to
      * {@link S3Request#overrideConfiguration()} in the request.
@@ -211,6 +230,7 @@ public <T> CompletableFuture<T> getObject(GetObjectRequest getObjectRequest,
                 .enableDelayedAuthentication(_enableDelayedAuthenticationMode)
                 .bufferSize(_bufferSize)
                 .instructionFileConfig(_instructionFileConfig)
+                .commitmentPolicy(_commitmentPolicy)
                 .build();
 
         return pipeline.getObject(getObjectRequest, asyncResponseTransformer);
@@ -309,6 +329,8 @@ public static class Builder implements S3AsyncClientBuilder {
         private SecureRandom _secureRandom = new SecureRandom();
         private long _bufferSize = -1L;
         private InstructionFileConfig _instructionFileConfig = null;
+        private AlgorithmSuite _encryptionAlgorithm = null;
+        private CommitmentPolicy _commitmentPolicy = null;
 
         // generic AwsClient configuration to be shared by default clients
         private AwsCredentialsProvider _awsCredentialsProvider = null;
@@ -335,6 +357,11 @@ public static class Builder implements S3AsyncClientBuilder {
         private Builder() {
         }
 
+        private Builder(CommitmentPolicy commitmentPolicy, AlgorithmSuite algorithmSuite) {
+            _commitmentPolicy = commitmentPolicy;
+            _encryptionAlgorithm = algorithmSuite;
+        }
+
         /**
          * Specifies the wrapped client to use for the actual S3 request.
          * This client will be used for all async operations.
@@ -568,6 +595,42 @@ public Builder instructionFileConfig(InstructionFileConfig instructionFileConfig
             return this;
         }
 
+        //= specification/s3-encryption/client.md#encryption-algorithm
+        //# The S3EC MUST support configuration of the encryption algorithm (or algorithm suite) during its initialization.
+        /**
+         * Sets the {@link AlgorithmSuite} to encrypt with.
+         * <p>
+         * Defaults to AlgorithmSuite.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY which provides key commitment.
+         * Objects encrypted with this default algorithm can only be decrypted by version 3.6.0 or later.
+         *
+         * @param encryptionAlgorithm The {@link AlgorithmSuite}
+         * @return The Builder, for method chaining
+         */
+        public Builder encryptionAlgorithm(AlgorithmSuite encryptionAlgorithm) {
+            _encryptionAlgorithm = encryptionAlgorithm;
+            return this;
+        }
+
+        //= specification/s3-encryption/client.md#key-commitment
+        //# The S3EC MUST support configuration of the [Key Commitment policy](./key-commitment.md) during its initialization.
+        /**
+         * Sets the commitment policy for this S3 encryption client.
+         * The commitment policy determines whether the client requires, forbids, or allows
+         * key commitment during encryption and decryption operations.
+         * <p>
+         * Defaults to REQUIRE_ENCRYPT_REQUIRE_DECRYPT which provides the highest security.
+         * This policy will reject messages encrypted without key commitment, so it should be only used when all the objects expected to succeed decryption have been encrypted using key commitment.
+         *
+         * @param commitmentPolicy the commitment policy to use
+         * @return this builder instance for method chaining
+         * @see CommitmentPolicy
+         */
+
+        public Builder commitmentPolicy(CommitmentPolicy commitmentPolicy) {
+            _commitmentPolicy = commitmentPolicy;
+            return this;
+        }
+
         /**
          * The credentials provider to use for all inner clients, including KMS, if a KMS key ID is provided.
          * Note that if a wrapped client is configured, the wrapped client will take precedence over this option.
@@ -896,6 +959,30 @@ public S3AsyncEncryptionClient build() {
                         .build();
             }
 
+            //= specification/s3-encryption/client.md#encryption-algorithm
+            //# The S3EC MUST validate that the configured encryption algorithm is not legacy.
+            //= specification/s3-encryption/client.md#key-commitment
+            //# The S3EC MUST validate the configured Encryption Algorithm against the provided key commitment policy.
+            //= specification/s3-encryption/key-commitment.md#commitment-policy
+            //# When the commitment policy is FORBID_ENCRYPT_ALLOW_DECRYPT, the S3EC MUST NOT encrypt using an algorithm suite which supports key commitment.
+            if (_encryptionAlgorithm == null || _commitmentPolicy == null) {
+                throw new S3EncryptionClientException(
+                        "Both encryption algorithm and commitment policy must be configured."
+                );
+            }
+            if (!(_encryptionAlgorithm.id() == AlgorithmSuite.ALG_AES_256_GCM_IV12_TAG16_NO_KDF.id()
+                    && _commitmentPolicy.equals(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT))) {
+                //= specification/s3-encryption/client.md#encryption-algorithm
+                //# If the configured encryption algorithm is legacy, then the S3EC MUST throw an exception.
+                //= specification/s3-encryption/client.md#key-commitment
+                //# If the configured Encryption Algorithm is incompatible with the key commitment policy, then it MUST throw an exception.
+                throw new S3EncryptionClientException(
+                        "This client can ONLY be built with these Settings: Commitment Policy: FORBID_ENCRYPT_ALLOW_DECRYPT; Encryption Algorithm: ALG_AES_256_GCM_IV12_TAG16_NO_KDF. "
+                                + "Note that the Encryption Algorithm does NOT effect Decryption; See: https://docs.aws.amazon.com/amazon-s3-encryption-client/latest/developerguide/encryption-algorithms.html#decryption-modes. "
+                                +  "Please update your configuration. Provided algorithm: " + _encryptionAlgorithm.name() + " and commitment policy: " + _commitmentPolicy.name()
+                );
+            }
+
             return new S3AsyncEncryptionClient(this);
         }