feat: Enforce Rotation Functionality for ReEncrypt-feature (#474)

Implemented a stronger level of validation for reEncryptInstructionFile where, when enabled, the client will attempt to decrypt the re-encrypted instruction file with the old key material and throw an exception when decryption succeeds. This is a stronger level of validation that the wrapping key has been rotated than the standard assertion that the materials descriptions are different.

---------

Co-authored-by: Anirav Kareddy <[email protected]>

Author: akareddy04

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

@@ -123,6 +123,7 @@ public static void simpleAesKeyringReEncryptInstructionFile(final String bucket)
       .bucket(bucket)
       .key(objectKey)
       .newKeyring(newKeyring)
+      .enforceRotation(true)
       .build();
 
     // Perform the re-encryption of the instruction file
@@ -239,6 +240,7 @@ public static void simpleRsaKeyringReEncryptInstructionFile(final String bucket)
       .bucket(bucket)
       .key(objectKey)
       .newKeyring(newKeyring)
+      .enforceRotation(true)
       .build();
 
     // Perform the re-encryption of the instruction file

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

@@ -207,6 +207,7 @@ public static Consumer<AwsRequestOverrideConfiguration.Builder> withAdditionalCo
      * Key rotation scenarios:
      * - Legacy to V3: Can rotate same wrapping key from legacy wrapping algorithms to fully supported wrapping algorithms
      * - Within V3: When rotating the wrapping key, the new keyring must be different from the current keyring
+     * - Enforce Rotation: When enabled, ensures old keyring cannot decrypt data encrypted by new keyring
      *
      * @param reEncryptInstructionFileRequest the request containing bucket, object key, new keyring, and optional instruction file suffix
      * @return ReEncryptInstructionFileResponse containing the bucket, object key, and instruction file suffix used
@@ -257,6 +258,11 @@ public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstru
             throw new S3EncryptionClientException("New keyring must have new materials description!");
         }
 
+        // If enforceRotation is set to true, ensure that the old keyring cannot decrypt the newly encrypted data key
+        if (reEncryptInstructionFileRequest.enforceRotation()) {
+            enforceRotation(encryptedMaterials, request);
+        }
+      
         //Create or update instruction file with the re-encrypted metadata while preserving IV
         ContentMetadataEncodingStrategy encodeStrategy = new ContentMetadataEncodingStrategy(_instructionFileConfig);
         encodeStrategy.encodeMetadata(encryptedMaterials, iv, PutObjectRequest.builder()
@@ -265,8 +271,23 @@ public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstru
           .build(), reEncryptInstructionFileRequest.instructionFileSuffix());
 
         return new ReEncryptInstructionFileResponse(reEncryptInstructionFileRequest.bucket(),
-            reEncryptInstructionFileRequest.key(), reEncryptInstructionFileRequest.instructionFileSuffix());
+            reEncryptInstructionFileRequest.key(), reEncryptInstructionFileRequest.instructionFileSuffix(), reEncryptInstructionFileRequest.enforceRotation());
+
+    }
 
+    private void enforceRotation(EncryptionMaterials newEncryptionMaterials, GetObjectRequest request) {
+        try {
+            DecryptionMaterials decryptedMaterials = this._cryptoMaterialsManager.decryptMaterials(
+              DecryptMaterialsRequest.builder()
+                .algorithmSuite(newEncryptionMaterials.algorithmSuite())
+                .encryptedDataKeys(newEncryptionMaterials.encryptedDataKeys())
+                .s3Request(request)
+                .build()
+            );
+        } catch (S3EncryptionClientException e) {
+            return;
+        }
+        throw new S3EncryptionClientException("Re-encryption failed due to enforced rotation! Old keyring is still able to decrypt the newly encrypted data key");
     }
 
     /**

src/main/java/software/amazon/encryption/s3/internal/ReEncryptInstructionFileRequest.java

@@ -19,12 +19,14 @@ public class ReEncryptInstructionFileRequest {
   private final String key;
   private final RawKeyring newKeyring;
   private final String instructionFileSuffix;
+  private final boolean enforceRotation;
 
   private ReEncryptInstructionFileRequest(Builder builder) {
     bucket = builder.bucket;
     key = builder.key;
     newKeyring = builder.newKeyring;
     instructionFileSuffix = builder.instructionFileSuffix;
+    enforceRotation = builder.enforceRotation;
   }
 
   /**
@@ -55,6 +57,11 @@ public String instructionFileSuffix() {
     return instructionFileSuffix;
   }
 
+  /**
+   * @return whether to enforce rotation for the re-encrypted instruction file
+   */
+  public boolean enforceRotation() { return enforceRotation; }
+
   /**
    * Creates a builder that can be used to configure and create a {@link ReEncryptInstructionFileRequest}
    *
@@ -72,6 +79,7 @@ public static class Builder {
     private String key;
     private RawKeyring newKeyring;
     private String instructionFileSuffix = DEFAULT_INSTRUCTION_FILE_SUFFIX;
+    private boolean enforceRotation = false;
 
     /**
      * Sets the S3 bucket name for the re-encryption of instruction file.
@@ -120,6 +128,20 @@ public Builder instructionFileSuffix(String instructionFileSuffix) {
       return this;
     }
 
+    /**
+     * Sets whether to enforce rotation for the re-encrypted instruction file.
+     * When enabled, the client will attempt to decrypt the re-encrypted instruction file with the old key material and
+     * throw an exception when decryption succeeds. This is a stronger level of validation that the wrapping key has been
+     * rotated than the standard assertion that the materials descriptions are different.
+     *
+     * @param enforceRotation whether to enforce rotation
+     * @return a reference to this object so that method calls can be chained together.
+     */
+    public Builder enforceRotation(boolean enforceRotation) {
+      this.enforceRotation = enforceRotation;
+      return this;
+    }
+
     /**
      * Validates and builds the ReEncryptInstructionFileRequest according
      * to the configuration options passed to the Builder object.

src/main/java/software/amazon/encryption/s3/internal/ReEncryptInstructionFileResponse.java

@@ -4,24 +4,27 @@
 
 /**
  * Response object returned after re-encrypting an instruction file in S3.
- * Contains the S3 bucket name, object key, and instruction file suffix used for the re-encrypted instruction file
+ * Contains the S3 bucket name, object key, instruction file suffix, and rotation enforcement status for the re-encrypted instruction file
  */
 public class ReEncryptInstructionFileResponse {
   private final String bucket;
   private final String key;
   private final String instructionFileSuffix;
+  private final boolean enforceRotation;
 
   /**
    * Creates a new ReEncryptInstructionFileResponse object with the specified parameters.
    *
    * @param bucket the S3 bucket containing the re-encrypted instruction file
    * @param key the S3 object key of the encrypted object in S3
    * @param instructionFileSuffix the suffix used for the instruction file
+   * @param enforceRotation whether rotation was enforced for the re-encrypted instruction file
    */
-  public ReEncryptInstructionFileResponse(String bucket, String key, String instructionFileSuffix) {
+  public ReEncryptInstructionFileResponse(String bucket, String key, String instructionFileSuffix, boolean enforceRotation) {
     this.bucket = bucket;
     this.key = key;
     this.instructionFileSuffix = instructionFileSuffix.substring(1);
+    this.enforceRotation = enforceRotation;
   }
 
   /**
@@ -38,6 +41,13 @@ public String key() {
     return key;
   }
 
+  /**
+   * @return whether rotation was enforced for the re-encrypted instruction file
+   */
+  public boolean enforceRotation() {
+    return enforceRotation;
+  }
+
   /**
    * @return the instruction file suffix used for the instruction file
    */