fixed up javadoc comments

Author: Anirav Kareddy

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

@@ -65,7 +65,6 @@ public static void main(final String[] args) throws NoSuchAlgorithmException {
 
   /**
    * This example demonstrates re-encrypting the encrypted data key in an instruction file with a new AES wrapping key.
-   * The other cryptographic parameters in the instruction file such as the IV and wrapping algorithm remain unchanged.
    *
    * @param bucket The name of the Amazon S3 bucket to perform operations on.
    * @throws NoSuchAlgorithmException if AES algorithm is not available
@@ -166,7 +165,6 @@ public static void simpleAesKeyringReEncryptInstructionFile(final String bucket)
 
   /**
    * This example demonstrates re-encrypting the encrypted data key in an instruction file with a new RSA wrapping key.
-   * The other cryptographic parameters in the instruction file such as the IV and wrapping algorithm remain unchanged.
    *
    * @param bucket The name of the Amazon S3 bucket to perform operations on.
    * @throws NoSuchAlgorithmException if RSA algorithm is not available
@@ -258,7 +256,7 @@ public static void simpleRsaKeyringReEncryptInstructionFile(final String bucket)
       assertTrue(e.getMessage().contains("Unable to RSA-OAEP-SHA1 unwrap"));
     }
 
-    // Create a new client with the rotated AES key
+    // Create a new client with the rotated RSA key
     S3EncryptionClient newClient = S3EncryptionClient.builder()
       .keyring(newKeyring)
       .instructionFileConfig(InstructionFileConfig.builder()

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

@@ -207,14 +207,13 @@ 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
      * @throws S3EncryptionClientException if the new keyring has the same materials description as the current one
      */
     public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstructionFileRequest reEncryptInstructionFileRequest) {
-        //GetObjectRequest MUST be kept the same
+        //Build request to retrieve the encrypted object and its associated instruction file
         final GetObjectRequest request = GetObjectRequest.builder()
           .bucket(reEncryptInstructionFileRequest.bucket())
           .key(reEncryptInstructionFileRequest.key())
@@ -224,15 +223,13 @@ public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstru
         ContentMetadataDecodingStrategy decodingStrategy = new ContentMetadataDecodingStrategy(_instructionFileConfig);
         ContentMetadata contentMetadata = decodingStrategy.decode(request, response.response());
 
-        // Algorithm Suite MUST be kept the same
+        //Extract cryptographic parameters from the current instruction file that MUST be preserved during re-encryption
         final AlgorithmSuite algorithmSuite = contentMetadata.algorithmSuite();
-        // Original Encrypted Data Key MUST be kept the same
         final EncryptedDataKey originalEncryptedDataKey = contentMetadata.encryptedDataKey();
-        // Current Keyring's Materials Description MUST be kept the same
         final Map<String, String> currentKeyringMaterialsDescription = contentMetadata.encryptedDataKeyMatDescOrContext();
-        // Content IV MUST be kept the same
         final byte[] iv = contentMetadata.contentIv();
 
+        //Decrypt the data key using the current keyring
         DecryptionMaterials decryptedMaterials = this._cryptoMaterialsManager.decryptMaterials(
           DecryptMaterialsRequest.builder()
             .algorithmSuite(algorithmSuite)
@@ -241,28 +238,27 @@ public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstru
             .build()
         );
 
-        //Plaintext Data Key MUST be kept the same
         final byte[] plaintextDataKey = decryptedMaterials.plaintextDataKey();
 
+        //Prepare encryption materials with the decrypted data key
         EncryptionMaterials encryptionMaterials = EncryptionMaterials.builder()
           .algorithmSuite(algorithmSuite)
           .plaintextDataKey(plaintextDataKey)
           .s3Request(request)
           .build();
 
-        //New Keyring MUST be kept the same
-        final RawKeyring newKeyring = reEncryptInstructionFileRequest.newKeyring();
-        //Encrypted Materials MUST be kept the same
-        final EncryptionMaterials encryptedMaterials = newKeyring.onEncrypt(encryptionMaterials);
-        //New Keyring's Materials Description MUST be kept the same
-        final Map<String, String> newMaterialsDescription = encryptedMaterials.materialsDescription().getMaterialsDescription();
+        //Re-encrypt the data key with the new keyring while preserving other cryptographic parameters
+        RawKeyring newKeyring = reEncryptInstructionFileRequest.newKeyring();
+        EncryptionMaterials encryptedMaterials = newKeyring.onEncrypt(encryptionMaterials);
 
+        final Map<String, String> newMaterialsDescription = encryptedMaterials.materialsDescription().getMaterialsDescription();
+        //Validate that the new keyring has different materials description than the old keyring
         if (newMaterialsDescription.equals(currentKeyringMaterialsDescription)) {
             throw new S3EncryptionClientException("New keyring must have new materials description!");
         }
 
+        //Create or update instruction file with the re-encrypted metadata while preserving IV
         ContentMetadataEncodingStrategy encodeStrategy = new ContentMetadataEncodingStrategy(_instructionFileConfig);
-
         encodeStrategy.encodeMetadata(encryptedMaterials, iv, PutObjectRequest.builder()
           .bucket(reEncryptInstructionFileRequest.bucket())
           .key(reEncryptInstructionFileRequest.key())