Merge branch 'dev'

Author: aws-sdk-dotnet-automation

.github/workflows/semgrep-analysis.yml

@@ -38,4 +38,4 @@ jobs:
         uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 #v3.30.5
         with:
           sarif_file: semgrep.sarif
-        if: always()
+        if: always()

CHANGELOG.md

@@ -1,3 +1,8 @@
+## Release 2025-12-17 #2
+
+### Amazon.Extensions.S3.Encryption (4.0.0)
+* feat:add ability to encrypt/decrypt with AES GCM with Key commitment
+
 ## Release 2025-11-12
 
 ### Amazon.Extensions.S3.Encryption (3.1.0)

README.md

@@ -14,7 +14,7 @@ The AmazonS3EncryptionClientV2 supports the following encryption methods for enc
   * RSA-OAEP-SHA1
   * AES-GCM
 
-Object content is encrypted using AES-GCM with generated DEKs which are stored in the S3 object metadata or in a separate instruction file (as configured).
+Object content is encrypted using committing AES-GCM (default) with generated DEKs which are stored in the S3 object metadata or in a separate instruction file (as configured).
 
 # Code examples and API Documentation
 

SUPPORT_POLICY.rst

@@ -0,0 +1,37 @@
+Overview
+========
+This page describes the support policy for the Amazon S3 Encryption Client for .NET. We regularly provide the Amazon S3 Encryption Client for .NET with updates that may contain support for new or updated APIs, new features, enhancements, bug fixes, security patches, or documentation updates. Updates may also address changes with dependencies, language runtimes, and operating systems.
+
+We recommend users to stay up-to-date with Amazon S3 Encryption Client for .NET releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported SDK version is not recommended and is done at the user's discretion.
+
+
+Major Version Lifecycle
+========================
+The Amazon S3 Encryption Client for .NET follows the same major version lifecycle as the AWS SDK. For details on this lifecycle, see  `AWS SDKs and Tools Maintenance Policy`_.
+
+Version Support Matrix
+======================
+This table describes the current support status of each major version of the Amazon S3 Encryption Client for .NET. It also shows the next status each major version will transition to, and the date at which that transition will happen.
+
+.. list-table::
+    :widths: 30 50 50 50
+    :header-rows: 1
+
+    * - Major version
+      - Current status
+      - Next status
+      - Next status date
+    * - 4.x
+      - General Availability
+      - 
+      -
+    * - 3.x
+      - General Availability
+      - Maintenance
+      -
+    * - 2.x
+      - General Availability
+      - Maintenance
+      - March 1, 2026
+
+.. _AWS SDKs and Tools Maintenance Policy: https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle

docs/index.md

@@ -7,29 +7,32 @@ _layout: landing
 ## Overview
 
 These are the API docs for the Amazon S3 Encryption client for .NET. There exist two (2) clients in this product:
-* AmazonS3EncryptionClient
 * AmazonS3EncryptionClientV2
+* AmazonS3EncryptionClientV4
 
-The AmazonS3EncryptionClient has an identical API to the obsolete client that is in the AWS SDK for .NET. The main difference is
-that this client can also decrypt AmazonS3EncryptionClientV2 encrypted objects.
+The AmazonS3EncryptionClientV2 has an identical API to the AmazonS3EncryptionClientV4 that is in the AWS SDK for .NET. The main difference is
+that AmazonS3EncryptionClientV2 can only decrypt message with content encryption AesGcmWithCommitment, while AmazonS3EncryptionClientV4 can encrypt or decrypt
+message with content encryption AesGcmWithCommitment. It is recommended to use AesGcmWithCommitment instead of AesGcm without key commitment because key commitment 
+prevents attackers from crafting ciphertexts that decrypt to different plaintexts under different keys, protecting against key substitution attacks when on instruction file mode.
 
-## How to use the AmazonS3EncryptionClientV2 client
+## How to use the AmazonS3EncryptionClientV4 client
 
-The AmazonS3EncryptionClientV2 supports the following encryption methods for encrypting DEKs (Data encryption keys):
+The AmazonS3EncryptionClientV4 supports the following encryption methods for encrypting DEKs (Data encryption keys):
 
 * AWS supplied KEK (key encryption key):
   * AWS KMS + Context
 * User supplied KEK:
   * RSA-OAEP-SHA1
   * AES-GCM
 
-Object content is encrypted using AES-GCM with generated DEKs which are stored in the S3 object metadata or in a separate instruction file (as configured).
+Object content is encrypted using committing AES-GCM (default) with generated DEKs which are stored in the S3 object metadata or in a separate instruction file (as configured).
+
 
 ### Data Key Encryption
 
 #### AWS KMS + Context
 
-To use "AWS KMS + Context", you must supply an EncryptionMaterialsV2 instance with the following information:
+To use "AWS KMS + Context", you must supply an EncryptionMaterialsV4 instance with the following information:
 
 * A KMS key id
   * This id will be used in decryption as well. If the id specified is not the key used to encrypt the object, decryption will fail.
@@ -40,39 +43,57 @@ To use "AWS KMS + Context", you must supply an EncryptionMaterialsV2 instance wi
 ```csharp
 var encryptionContext = new Dictionary<string, string>();
 var encryptionMaterial =
-    new EncryptionMaterialsV2("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext);
-var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
-var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
+    new EncryptionMaterialsV4("1234abcd-12ab-34cd-56ef-1234567890ab", KmsType.KmsContext, encryptionContext);
+var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4, CommitmentPolicy.RequireEncryptRequireDecrypt, ContentEncryptionAlgorithm.AesGcmWithCommitment);
+var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);
 ```
 
 #### RSA-OAEP-SHA1
 
-To use "RSA-OAEP-SHA1", you must supply an EncryptionMaterialsV2 instance with the following information:
+To use "RSA-OAEP-SHA1", you must supply an EncryptionMaterialsV4 instance with the following information:
 
 * A RSA instance containing the encryption materials.
 * Which algorithm to use (AsymmetricAlgorithmType.RsaOaepSha1)
 
 ```csharp
 var asymmetricAlgorithm = RSA.Create();
-var encryptionMaterial = new EncryptionMaterialsV2(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1);
-var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
-var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
+var encryptionMaterial = new EncryptionMaterialsV4(asymmetricAlgorithm, AsymmetricAlgorithmType.RsaOaepSha1);
+var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4, CommitmentPolicy.RequireEncryptRequireDecrypt, ContentEncryptionAlgorithm.AesGcmWithCommitment);
+var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);
 ```
 
 #### AES-GCM
 
-To use "AES-GCM", you must supply an EncryptionMaterialsV2 instance with the following information:
+To use "AES-GCM", you must supply an EncryptionMaterialsV4 instance with the following information:
 
 * An Aes instance containing the encryption materials.
 * Which algorithm to use (SymmetricAlgorithmType.AesGcm)
 
 ```csharp
 var symmetricAlgorithm = Aes.Create();
-var encryptionMaterial = new EncryptionMaterialsV2(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm);
-var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
-var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);
+var encryptionMaterial = new EncryptionMaterialsV4(symmetricAlgorithm, SymmetricAlgorithmType.AesGcm);
+var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4, CommitmentPolicy.RequireEncryptRequireDecrypt, ContentEncryptionAlgorithm.AesGcmWithCommitment);
+var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);
 ```
 
+### CommitmentPolicy and ContentEncryptionAlgorithm
+
+Starting with Amazon S3 Encryption Client for .NET V4, you can encrypt objects with AES-GCM with key commitment (default for V4), which protects your data against key substitution attacks. To help you migrate from AES-GCM to AES-GCM with key commitment, this version includes three commitment policies.
+
+For more information, see [S3 Encryption Client Migration (V2 to V4)](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/s3-encryption-migration-v2-v4.html). 
+
+* ForbidEncryptAllowDecrypt: 
+  * With ForbidEncryptAllowDecrypt CommitmentPolicy, the client continues to encrypt objects without key commitment and can decrypt both non-key-committing objects and key-committing objects encrypted with AES GCM with commitment.
+  * Because this policy encrypts with AES-GCM without key commitment, it does not enforce commitment and may allow keys in Instruction Files to be tampered with which does not protect against key substitution attacks.
+
+* RequireEncryptAllowDecrypt
+  * With RequireEncryptAllowDecrypt CommitmentPolicy, the client starts encrypting objects with key commitment (AES-GCM with key commitment) and can still decrypt objects encrypted without key commitment.
+  * This policy protects newly encrypted objects against key substitution attacks while maintaining backward compatibility for decryption.
+
+* RequireEncryptRequireDecrypt (default for V4)
+  * With RequireEncryptRequireDecrypt CommitmentPolicy, the client will no longer decrypt objects encrypted without key commitment (AES-GCM without key commitment) and cannot decrypt objects encrypted without key commitment.
+  * This policy fully enforces key commitment and protects against key substitution attacks.
+  
 ### Storage Mode
 
 You can specify a storage mode for the encrypted data key and associated metadata needed for decryption of an object:
@@ -82,32 +103,32 @@ You can specify a storage mode for the encrypted data key and associated metadat
 * InstructionFile
   * Stores the data in a separate S3 object
 
-This can be set on the AmazonS3CryptoConfigurationV2 instance:
+This can be set on the AmazonS3CryptoConfigurationV4 instance:
 
 ```csharp
-var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2)
+var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4)
 {
     StorageMode.InstructionFile
 }
 ```
 
 ### Security Profile
 
-A security profile setting needs to be passed to the constructor of the AmazonS3CryptoConfigurationV2 instance, either:
+A security profile setting needs to be passed to the constructor of the AmazonS3CryptoConfigurationV4 instance, either:
 
-* V2
-* V2AndLegacy
+* V4
+* V4AndLegacy
 
-Unless you are migrating existing applications, use V2. If you need leagcy mode:
+Unless you are migrating existing applications from legacy content encryption message format (message encrypted with AmazonS3EncryptionClient which uses AES CBC), use V4. If you need legacy mode:
 
 ```csharp
-var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy);
+var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4AndLegacy);
 ```
 
 ### Multipart Uploads
 
-The AmazonS3EncryptionClientV2 extends the base AmazonS3Client. You can use multipart upload using the same APIs: <https://docs.aws.amazon.com/AmazonS3/latest/dev/LLuploadFileDotNet.html>
+The AmazonS3EncryptionClientV4 extends the base AmazonS3Client. You can use multipart upload using the same APIs: <https://docs.aws.amazon.com/AmazonS3/latest/dev/LLuploadFileDotNet.html>
 
 ### Transfer Utility Integration
 
-The AmazonS3EncryptionClientV2 extends the base AmazonS3Client. You can use the TransferUtility just as you would using the base AmazonS3Client: <https://docs.aws.amazon.com/AmazonS3/latest/dev/HLuploadFileDotNet.html>
+The AmazonS3EncryptionClientV4 extends the base AmazonS3Client. You can use the TransferUtility just as you would using the base AmazonS3Client: <https://docs.aws.amazon.com/AmazonS3/latest/dev/HLuploadFileDotNet.html>

src/Amazon.Extensions.S3.Encryption.csproj

@@ -2,7 +2,7 @@
 
     <PropertyGroup>
         <TargetFrameworks>net472;netstandard2.0;netcoreapp3.1;net8.0</TargetFrameworks>
-        <Version>3.1.0</Version>
+        <Version>4.0.0</Version>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <PackageId>Amazon.Extensions.S3.Encryption</PackageId>
         <Title>Amazon S3 Encryption Client for .NET</Title>
@@ -53,4 +53,13 @@
         <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
     </ItemGroup>
 
+    <ItemGroup>
+        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+            <_Parameter1>Amazon.Extensions.S3.Encryption.UnitTests,PublicKey=0024000004800000940000000602000000240000525341310004000001000100db5f59f098d27276c7833875a6263a3cc74ab17ba9a9df0b52aedbe7252745db7274d5271fd79c1f08f668ecfa8eaab5626fa76adc811d3c8fc55859b0d09d3bc0a84eecd0ba891f2b8a2fc55141cdcc37c2053d53491e650a479967c3622762977900eddbf1252ed08a2413f00a28f3a0752a81203f03ccb7f684db373518b4</_Parameter1>
+        </AssemblyAttribute>
+        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+            <_Parameter1>Amazon.Extensions.S3.Encryption.IntegrationTests.NetFramework,PublicKey=0024000004800000940000000602000000240000525341310004000001000100db5f59f098d27276c7833875a6263a3cc74ab17ba9a9df0b52aedbe7252745db7274d5271fd79c1f08f668ecfa8eaab5626fa76adc811d3c8fc55859b0d09d3bc0a84eecd0ba891f2b8a2fc55141cdcc37c2053d53491e650a479967c3622762977900eddbf1252ed08a2413f00a28f3a0752a81203f03ccb7f684db373518b4</_Parameter1>
+        </AssemblyAttribute>
+    </ItemGroup>
+
 </Project>

src/AmazonS3CryptoConfiguration.cs

@@ -28,18 +28,35 @@ namespace Amazon.Extensions.S3.Encryption
     /// </summary>
     public abstract class AmazonS3CryptoConfigurationBase: AmazonS3Config
     {
+        //= ../specification/s3-encryption/client.md#instruction-file-configuration
+        //# The S3EC MAY support the option to provide Instruction File Configuration during its initialization.
+        
+        //= ../specification/s3-encryption/client.md#instruction-file-configuration
+        //# If the S3EC in a given language supports Instruction Files, then it MUST accept Instruction File Configuration during its initialization.
+        
         /// <summary>
         /// Gets and sets the StorageMode property. This determines if the crypto metadata is stored as metadata on the object or as a separate object in S3.
         /// The default is ObjectMetadata.
         /// </summary>
         public CryptoStorageMode StorageMode { get; set; }
+        
+        //= ../specification/s3-encryption/data-format/metadata-strategy.md#instruction-file
+        //= type=implication
+        //# Instruction File writes MUST be optionally configured during client creation or on each PutObject request.
 
         /// <summary>
         /// Default Constructor.
         /// </summary>
         public AmazonS3CryptoConfigurationBase()
         {
-            // By default, store encryption info in metadata
+            //= ../specification/s3-encryption/data-format/metadata-strategy.md#object-metadata
+            //# By default, the S3EC MUST store content metadata in the S3 Object Metadata.
+            
+            //= ../specification/s3-encryption/data-format/metadata-strategy.md#instruction-file
+            //# Instruction File writes MUST NOT be enabled by default.
+            
+            //= ../specification/s3-encryption/client.md#instruction-file-configuration
+            //# In this case, the Instruction File Configuration SHOULD be optional, such that its default configuration is used when none is provided.
             StorageMode = CryptoStorageMode.ObjectMetadata;
         }
         /// <summary>