Added javadoc comments for readability

Author: Anirav Kareddy

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

@@ -79,7 +79,6 @@
 import java.security.Provider;
 import java.security.SecureRandom;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -109,6 +108,7 @@ public class S3EncryptionClient extends DelegatingS3Client {
     public static final ExecutionAttribute<Map<String, String>> ENCRYPTION_CONTEXT = new ExecutionAttribute<>("EncryptionContext");
     public static final ExecutionAttribute<MultipartConfiguration> CONFIGURATION = new ExecutionAttribute<>("MultipartConfiguration");
 
+    //Used for specifying custom instruction file suffix on a per-request basis
     public static final ExecutionAttribute<String> CUSTOM_INSTRUCTION_FILE_SUFFIX = new ExecutionAttribute<>("CustomInstructionFileSuffix");
 
     private final S3Client _wrappedClient;
@@ -157,6 +157,13 @@ public static Consumer<AwsRequestOverrideConfiguration.Builder> withAdditionalCo
                 builder.putExecutionAttribute(S3EncryptionClient.ENCRYPTION_CONTEXT, encryptionContext);
     }
 
+    /**
+     * Attaches a custom instruction file suffix to a request. Must be used as a parameter to
+     * {@link S3Request#overrideConfiguration()} in the request.
+     * This allows specifying a custom suffix for the instruction file on a per-request basis.
+     * @param customInstructionFileSuffix the custom suffix to use for the instruction file.
+     * @return Consumer for use in overrideConfiguration()
+     */
     public static Consumer<AwsRequestOverrideConfiguration.Builder> withCustomInstructionFileSuffix(String customInstructionFileSuffix) {
         return builder ->
                 builder.putExecutionAttribute(S3EncryptionClient.CUSTOM_INSTRUCTION_FILE_SUFFIX, customInstructionFileSuffix);
@@ -190,6 +197,29 @@ public static Consumer<AwsRequestOverrideConfiguration.Builder> withAdditionalCo
                         .putExecutionAttribute(S3EncryptionClient.CONFIGURATION, multipartConfiguration);
     }
 
+    /**
+     * Re-encrypts an instruction file with a new keyring while preserving the original encrypted object in S3.
+     * This enables:
+     * 1. Key rotation by updating instruction file metadata without re-encrypting object content
+     * 2. Sharing encrypted objects with partners by creating new instruction files with their public keys
+     * <p>
+     * Key rotation scenarios:
+     * - Legacy to V3: Can rotate same key type from V1/V2 to V3's improved algorithms
+     * - Within V3: Cannot rotate to same key (must use different keyring)
+     * <p>
+     * Instruction file behavior:
+     * - AES keyrings: Uses default ".instruction" suffix
+     * - RSA keyrings: Requires custom suffix for multiple access patterns
+     * <p>
+     * Requirements:
+     * - New keyring must have different materials description
+     * - Custom instruction file suffix required for RSA keyrings
+     * - Default instruction file suffix required for AES keyrings
+     *
+     * @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 request = GetObjectRequest.builder()
           .bucket(reEncryptInstructionFileRequest.bucket())
@@ -224,7 +254,7 @@ public ReEncryptInstructionFileResponse reEncryptInstructionFile(ReEncryptInstru
         EncryptionMaterials encryptedMaterials = newKeyring.onEncrypt(encryptionMaterials);
 
         if (encryptedMaterials.materialsDescription().equals(currentKeyringMaterialsDescription)) {
-            throw new S3EncryptionClientException("New keyring must generate new materials description!");
+            throw new S3EncryptionClientException("New keyring must have new materials description!");
         }
 
         ContentMetadataEncodingStrategy encodeStrategy = new ContentMetadataEncodingStrategy(_instructionFileConfig);

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

@@ -7,8 +7,12 @@
 import software.amazon.encryption.s3.materials.RawKeyring;
 import software.amazon.encryption.s3.materials.RsaKeyring;
 
-/** Request object for re-encrypting instruction files.
- * Supports both AES and RSA keyring with different instruction file suffixes.
+/**
+ * Request object for re-encrypting instruction files in S3.
+ * This request supports re-encryption operations using either AES or RSA keyrings.
+ * For AES keyrings, only the default instruction file suffix is supported.
+ * For RSA keyrings, a custom instruction file suffix must be provided to support
+ * multiple accesses to the same encrypted object.
  */
 public class ReEncryptInstructionFileRequest {
   private final String bucket;
@@ -23,53 +27,106 @@ private ReEncryptInstructionFileRequest(Builder builder) {
     instructionFileSuffix = builder.instructionFileSuffix;
   }
 
+  /**
+   * @return the S3 bucket name that contains the encrypted object and instruction file to re-encrypt
+   */
   public String bucket() {
     return bucket;
   }
 
+  /**
+   * @return the S3 object key of the encrypted object whose instruction file will be re-encrypted
+   */
   public String key() {
     return key;
   }
 
+  /**
+   * @return the new keyring (AES or RSA) that will be used to re-encrypt the instruction file
+   */
   public RawKeyring newKeyring() {
     return newKeyring;
   }
 
+  /**
+   * @return the suffix to use for the instruction file. The default instruction file suffix is ".instruction" for
+   * AES keyrings and the instruction file suffix must be different from the default one for RSA keyrings
+   */
   public String instructionFileSuffix() {
     return instructionFileSuffix;
   }
 
+  /**
+   * Creates a builder that can be used to configure and create a {@link ReEncryptInstructionFileRequest}
+   *
+   * @return a new builder
+   */
   public static Builder builder() {
     return new Builder();
   }
 
+  /**
+   * Builder for ReEncryptInstructionFileRequest.
+   */
   public static class Builder {
     private static final String DEFAULT_INSTRUCTION_FILE_SUFFIX = ".instruction";
     private String bucket;
     private String key;
     private RawKeyring newKeyring;
     private String instructionFileSuffix = DEFAULT_INSTRUCTION_FILE_SUFFIX;
 
+    /**
+     * Sets the S3 bucket name for the re-encryption of instruction file.
+     *
+     * @param bucket the S3 bucket name
+     * @return a reference to this object so that method calls can be chained together.
+     */
     public Builder bucket(String bucket) {
       this.bucket = bucket;
       return this;
     }
 
+    /**
+     * Sets the S3 object key for the re-encryption of instruction file.
+     *
+     * @param key the S3 object key
+     * @return a reference to this object so that method calls can be chained together.
+     */
     public Builder key(String key) {
       this.key = key;
       return this;
     }
 
+    /**
+     * Sets the new keyring for re-encryption of instruction file.
+     *
+     * @param newKeyring the new keyring for re-encryption
+     * @return a reference to this object so that method calls can be chained together.
+     */
     public Builder newKeyring(RawKeyring newKeyring) {
       this.newKeyring = newKeyring;
       return this;
     }
 
+    /**
+     * Sets a custom instruction file suffix for the re-encrypted instruction file.
+     * For AES keyrings, only the default instruction file suffix is allowed.
+     * For RSA keyrings, a custom suffix different from the default must be provided.
+     *
+     * @param instructionFileSuffix the instruction file suffix
+     * @return a reference to this object so that method calls can be chained together.
+     */
     public Builder instructionFileSuffix(String instructionFileSuffix) {
       this.instructionFileSuffix = "." + instructionFileSuffix;
       return this;
     }
 
+    /**
+     * Validates and builds the ReEncryptInstructionFileRequest according
+     * to the configuration options passed to the Builder object.
+     *
+     * @return an instance of the ReEncryptInstructionFileRequest
+     */
     public ReEncryptInstructionFileRequest build() {
       if (bucket == null || bucket.isEmpty()) {
         throw new S3EncryptionClientException("Bucket must be provided!");

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

@@ -2,28 +2,45 @@
 // SPDX-License-Identifier: Apache-2.0
 package software.amazon.encryption.s3.internal;
 
-/** Response object for re-encrypting instruction files.
- * Contains the bucket, key, and instruction file suffix of the re-encrypted instruction file in S3.
+/**
+ * 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
  */
 public class ReEncryptInstructionFileResponse {
   private final String bucket;
   private final String key;
   private final String instructionFileSuffix;
 
+  /**
+   * 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
+   */
   public ReEncryptInstructionFileResponse(String bucket, String key, String instructionFileSuffix) {
     this.bucket = bucket;
     this.key = key;
     this.instructionFileSuffix = instructionFileSuffix;
   }
 
+  /**
+   * @return the S3 bucket containing the re-encrypted instruction file
+   */
   public String Bucket() {
     return bucket;
   }
 
+  /**
+   * @return the S3 object key of the encrypted object in S3
+   */
   public String Key() {
     return key;
   }
 
+  /**
+   * @return the instruction file suffix used for the instruction file
+   */
   public String InstructionFileSuffix() {
     return instructionFileSuffix;
   }

src/main/java/software/amazon/encryption/s3/materials/RawKeyring.java

@@ -16,6 +16,13 @@ protected RawKeyring(Builder<?, ?> builder) {
     _materialsDescription = builder._materialsDescription;
   }
 
+  /**
+   * Modifies encryption materials with the keyring's materials description if present.
+   * Issues a warning if encryption context is found, as it provides no security benefit for raw keyrings.
+   *
+   * @param materials the encryption materials to modify
+   * @return modified encryption materials with the keyring's materials description or original encryption materials if no materials description is set
+   */
   public EncryptionMaterials modifyMaterialsForRawKeyring(EncryptionMaterials materials) {
     warnIfEncryptionContextIsPresent(materials);
     if (_materialsDescription != null && !_materialsDescription.isEmpty()) {
@@ -46,6 +53,13 @@ public void warnIfEncryptionContextIsPresent(EncryptionMaterials materials) {
         "stored in the material description. Provide a MaterialDescription in the Keyring's builder instead."));
   }
 
+  /**
+   * Abstract builder for RawKeyring implementations.
+   * Provides common functionality for setting materials description on raw keyrings.
+   * 
+   * @param <KeyringT> the type of keyring being built
+   * @param <BuilderT> the type of builder
+   */
   public static abstract class Builder<KeyringT extends RawKeyring, BuilderT extends Builder<KeyringT, BuilderT>>
       extends S3Keyring.Builder<KeyringT, BuilderT> {
 
@@ -55,6 +69,13 @@ protected Builder() {
       super();
     }
 
+    /**
+     * Sets the materials description for this keyring.
+     * Materials description provides additional metadata for raw keyrings.
+     * 
+     * @param materialsDescription the materials description to associate with this keyring.
+     * @return a reference to this object so that method calls can be chained together.
+     */
     public BuilderT materialsDescription(MaterialsDescription materialsDescription) {
       _materialsDescription = materialsDescription;
       return builder();