Merge branch '2133-javadoc-cms-streams' into 'main'

Add java doc for CMSAuthEnvelopedDataParser and CMSAuthEnvelopedDataStreamGenerator

See merge request root/bc-java!116

Author: dghgit

pkix/src/main/java/org/bouncycastle/cms/CMSAuthEnvelopedDataParser.java

@@ -21,6 +21,16 @@
 import org.bouncycastle.asn1.x509.AlgorithmIdentifier;
 import org.bouncycastle.util.Arrays;
 
+/**
+ * Parser for authenticated enveloped CMS data structures.
+ * <p>
+ * Important usage notes:
+ * <ul>
+ *   <li>The constructor <b>fully drains and closes</b> the provided InputStream</li>
+ *   <li>Plaintext content is buffered in memory and available via {@code RecipientInformation}</li>
+ *   <li>Do not reuse the input stream after parsing</li>
+ * </ul>
+ */
 public class CMSAuthEnvelopedDataParser
     extends CMSContentInfoParser
 {
@@ -36,13 +46,29 @@ public class CMSAuthEnvelopedDataParser
     private boolean unauthAttrNotRead;
     private OriginatorInformation originatorInfo;
 
+    /**
+     * Create a parser from a byte array.
+     * <p>
+     * <b>Note:</b> The input is fully consumed during parsing. Plaintext content is buffered in memory.
+     *
+     * @param envelopedData the CMS auth enveloped data bytes
+     */
     public CMSAuthEnvelopedDataParser(
         byte[] envelopedData)
         throws CMSException, IOException
     {
         this(new ByteArrayInputStream(envelopedData));
     }
 
+    /**
+     * Create a parser from an input stream.
+     * <p>
+     * <b>Stream handling note:</b> This constructor fully reads and <b>closes the input stream</b>
+     * before returning. The plaintext content is buffered in memory and accessible via
+     * {@link RecipientInformation#getContentStream}.
+     *
+     * @param envelopedData the CMS auth enveloped data stream
+     */
     public CMSAuthEnvelopedDataParser(
         InputStream envelopedData)
         throws CMSException, IOException

pkix/src/main/java/org/bouncycastle/cms/CMSAuthEnvelopedDataStreamGenerator.java

@@ -15,6 +15,16 @@
 import org.bouncycastle.asn1.x509.AlgorithmIdentifier;
 import org.bouncycastle.operator.OutputAEADEncryptor;
 
+/**
+ * Generate authenticated enveloped CMS data with streaming support.
+ * <p>
+ * When using this generator, note:
+ * <ul>
+ *   <li>The returned OutputStream must be closed to finalize encryption and authentication</li>
+ *   <li>Closing the returned stream <b>does not close</b> the underlying OutputStream passed to {@code open()}</li>
+ *   <li>Callers are responsible for closing the underlying OutputStream separately</li>
+ * </ul>
+ */
 public class CMSAuthEnvelopedDataStreamGenerator
     extends CMSAuthEnvelopedGenerator
 {
@@ -113,10 +123,16 @@ protected OutputStream open(
         }
     }
 
-
     /**
-     * generate an enveloped object that contains an CMS Enveloped Data
-     * object using the given encryptor.
+     * generate an enveloped object that contains an CMS Enveloped Data object using the given encryptor.
+     * <p>
+     * <b>Stream handling note:</b> Closing the returned stream finalizes the CMS structure but
+     * <b>does not close</b> the underlying output stream. The caller remains responsible for
+     * managing the lifecycle of {@code out}.
+     *
+     * @param out the output stream to write the CMS structure to
+     * @param encryptor the cipher to use for encryption
+     * @return an output stream that writes encrypted and authenticated content
      */
     public OutputStream open(
         OutputStream out,