From 8f2f4d933a5c58641621191f2c9e5e5daf3f328a Mon Sep 17 00:00:00 2001 From: Konradsop Date: Thu, 30 Jul 2026 16:41:42 +0200 Subject: [PATCH] Add XML documentation for CMS EnvelopedData parser --- crypto/src/cms/CMSEnvelopedDataParser.cs | 103 +++++++++-------------- 1 file changed, 38 insertions(+), 65 deletions(-) diff --git a/crypto/src/cms/CMSEnvelopedDataParser.cs b/crypto/src/cms/CMSEnvelopedDataParser.cs index 4e2d6345b..fc0990da2 100644 --- a/crypto/src/cms/CMSEnvelopedDataParser.cs +++ b/crypto/src/cms/CMSEnvelopedDataParser.cs @@ -6,53 +6,30 @@ namespace Org.BouncyCastle.Cms { - /** - * Parsing class for an CMS Enveloped Data object from an input stream. - *

- * Note: that because we are in a streaming mode only one recipient can be tried and it is important - * that the methods on the parser are called in the appropriate order. - *

- *

- * Example of use - assuming the first recipient matches the private key we have. - * 

-     *      CmsEnvelopedDataParser     ep = new CmsEnvelopedDataParser(inputStream);
-     *
-     *      RecipientInformationStore  recipients = ep.GetRecipientInfos();
-     *
-     *      Collection  c = recipients.GetRecipients();
-     *      Iterator    it = c.iterator();
-     *
-     *      if (it.hasNext())
-     *      {
-     *          RecipientInformation   recipient = (RecipientInformation)it.next();
-     *
-     *          CMSTypedStream recData = recipient.GetContentStream(privateKey);
-     *
-     *          processDataStream(recData.GetContentStream());
-     *      }
-     *
- * Note: this class does not introduce buffering - if you are processing large files you should create - * the parser with: - * 
-     *          CmsEnvelopedDataParser     ep = new CmsEnvelopedDataParser(new BufferedInputStream(inputStream, bufSize));
-     *
- * where bufSize is a suitably large buffer size. - *

- *

- * Stream handling note: - *

- *

- */ + /// + /// Streaming parser for CMS EnvelopedData messages, the counterpart to . + /// In streaming mode only one recipient can be tried and parser methods must be called in order. + /// + /// + /// The constructor reads only enough of the supplied stream to expose CMS structure metadata (originator + /// info, recipient infos, content-encryption algorithm). Encrypted content is drained lazily via + /// or + /// . + /// The supplied stream is not closed automatically. Dispose this parser to close the underlying stream, + /// or close it yourself. + /// This class does not introduce buffering. For large inputs, pass a buffered stream with a suitably + /// large buffer size. + /// Example: + /// + /// CmsEnvelopedDataParser ep = new CmsEnvelopedDataParser(inputStream); + /// RecipientInformationStore recipients = ep.GetRecipientInfos(); + /// foreach (RecipientInformation recipient in recipients) + /// { + /// using CmsTypedStream recData = recipient.GetContentStream(privateKey); + /// ProcessDataStream(recData.ContentStream); + /// } + /// + /// public class CmsEnvelopedDataParser : CmsContentInfoParser { @@ -64,11 +41,17 @@ public class CmsEnvelopedDataParser private bool _attrNotRead; private OriginatorInformation m_originatorInformation; + /// Creates a parser from an encoded EnvelopedData message. + /// The DER-encoded CMS ContentInfo bytes. public CmsEnvelopedDataParser(byte[] envelopedData) : this(new MemoryStream(envelopedData, false)) { } + /// Creates a parser from an encoded EnvelopedData message. + /// The stream containing the DER-encoded CMS ContentInfo. + /// is null. + /// The stream cannot be parsed as CMS ContentInfo. public CmsEnvelopedDataParser(Stream envelopedData) : base(envelopedData) { @@ -104,34 +87,24 @@ public CmsEnvelopedDataParser(Stream envelopedData) recipientInfos, secureReadable); } + /// Gets the content-encryption algorithm identifier. public AlgorithmIdentifier EncryptionAlgorithmID => _encAlg; - /** - * return the object identifier for the content encryption algorithm. - */ + /// Return the object identifier for the content-encryption algorithm. public string EncryptionAlgOid => _encAlg.Algorithm.GetID(); - /** - * return the ASN.1 encoded encryption algorithm parameters, or null if there aren't any. - */ + /// + /// Return the ASN.1 encoded content-encryption algorithm parameters, or null if there aren't any. + /// public Asn1Object EncryptionAlgParams => _encAlg.Parameters?.ToAsn1Object(); - /** - * Return the originator information associated with this message if present. - * - * @return OriginatorInformation, null if not present. - */ + /// Gets originator certificates and CRLs carried in the message, or null if absent. public OriginatorInformation OriginatorInformation => m_originatorInformation; - /** - * return a store of the intended recipients for this message - */ + /// Returns a store of the intended recipients for this message. public RecipientInformationStore GetRecipientInfos() => this.recipientInfoStore; - /** - * return a table of the unprotected attributes indexed by the OID of the attribute. - * @throws IOException - */ + /// Returns a table of unprotected attributes indexed by attribute OID, or null if absent. public Asn1.Cms.AttributeTable GetUnprotectedAttributes() { if (_unprotectedAttributes == null && _attrNotRead)