diff --git a/crypto/src/cms/CMSAuthenticatedDataParser.cs b/crypto/src/cms/CMSAuthenticatedDataParser.cs index addbcbd62..1222e7de6 100644 --- a/crypto/src/cms/CMSAuthenticatedDataParser.cs +++ b/crypto/src/cms/CMSAuthenticatedDataParser.cs @@ -7,58 +7,34 @@ namespace Org.BouncyCastle.Cms { - /** - * Parsing class for an CMS Authenticated 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. - * 

-     *      CMSAuthenticatedDataParser     ad = new CMSAuthenticatedDataParser(inputStream);
-     *
-     *      RecipientInformationStore  recipients = ad.getRecipientInfos();
-     *
-     *      Collection  c = recipients.getRecipients();
-     *      Iterator    it = c.iterator();
-     *
-     *      if (it.hasNext())
-     *      {
-     *          RecipientInformation   recipient = (RecipientInformation)it.next();
-     *
-     *          CMSTypedStream recData = recipient.getContentStream(privateKey, "BC");
-     *
-     *          processDataStream(recData.getContentStream());
-     *
-     *          if (!Arrays.equals(ad.getMac(), recipient.getMac())
-     *          {
-     *              System.err.println("Data corrupted!!!!");
-     *          }
-     *      }
-     *
- * Note: this class does not introduce buffering - if you are processing large files you should create - * the parser with: - * 
-     *          CMSAuthenticatedDataParser     ep = new CMSAuthenticatedDataParser(new BufferedInputStream(inputStream, bufSize));
-     *
- * where bufSize is a suitably large buffer size. - *

- *

- * Stream handling note: - *

- *

- */ + /// + /// Streaming parser for CMS AuthenticatedData 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, MAC algorithm). Encapsulated content is drained lazily via + /// . + /// The MAC is available from once the content stream has been read to end-of-file. + /// 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: + /// + /// CmsAuthenticatedDataParser ad = new CmsAuthenticatedDataParser(inputStream); + /// RecipientInformationStore recipients = ad.GetRecipientInfos(); + /// foreach (RecipientInformation recipient in recipients) + /// { + /// using CmsTypedStream recData = recipient.GetContentStream(privateKey); + /// ProcessDataStream(recData.ContentStream); + /// if (!Arrays.FixedTimeEquals(ad.GetMac(), recipient.GetMac())) + /// { + /// // MAC mismatch + /// } + /// } + /// + /// public class CmsAuthenticatedDataParser : CmsContentInfoParser { @@ -74,12 +50,18 @@ public class CmsAuthenticatedDataParser private bool unauthAttrNotRead; private OriginatorInformation m_originatorInformation; + /// Creates a parser from an encoded AuthenticatedData message. + /// The DER-encoded CMS ContentInfo bytes. // TODO[api] Rename parameter to 'authenticatedData' public CmsAuthenticatedDataParser(byte[] envelopedData) : this(new MemoryStream(envelopedData, false)) { } + /// Creates a parser from an encoded AuthenticatedData message. + /// The stream containing the DER-encoded CMS ContentInfo. + /// is null. + /// The stream cannot be parsed as CMS ContentInfo. // TODO[api] Rename parameter to 'authenticatedData' public CmsAuthenticatedDataParser(Stream envelopedData) : base(envelopedData) @@ -117,36 +99,25 @@ public CmsAuthenticatedDataParser(Stream envelopedData) recipientInfos, secureReadable); } - /** - * 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 the MAC algorithm details for the MAC associated with the data in this object. - * - * @return AlgorithmIdentifier representing the MAC algorithm. - */ + /// Gets the MAC algorithm identifier. public AlgorithmIdentifier MacAlgorithmID => macAlg; - /** - * return the object identifier for the mac algorithm. - */ + /// Return the object identifier for the MAC algorithm. public string MacAlgOid => macAlg.Algorithm.GetID(); - /** - * return the ASN.1 encoded encryption algorithm parameters, or null if - * there aren't any. - */ + /// Return the ASN.1 encoded MAC algorithm parameters, or null if there aren't any. public Asn1Object MacAlgParams => macAlg.Parameters?.ToAsn1Object(); - /** - * return a store of the intended recipients for this message - */ + /// Returns a store of the intended recipients for this message. public RecipientInformationStore GetRecipientInfos() => _recipientInfoStore; + /// + /// Returns a copy of the message authentication code. Call after the encapsulated content stream has been + /// read to end-of-file. + /// public byte[] GetMac() { if (mac == null) @@ -157,11 +128,7 @@ public byte[] GetMac() return Arrays.Clone(mac); } - /** - * return a table of the unauthenticated attributes indexed by - * the OID of the attribute. - * @exception java.io.IOException - */ + /// Returns a table of authenticated attributes indexed by attribute OID, or null if absent. public Asn1.Cms.AttributeTable GetAuthAttrs() { if (authAttrs == null && authAttrNotRead) @@ -179,11 +146,9 @@ public Asn1.Cms.AttributeTable GetAuthAttrs() return authAttrs; } - /** - * return a table of the unauthenticated attributes indexed by - * the OID of the attribute. - * @exception java.io.IOException - */ + /// + /// Returns a table of unauthenticated attributes indexed by attribute OID, or null if absent. + /// public Asn1.Cms.AttributeTable GetUnauthAttrs() { if (unauthAttrs == null && unauthAttrNotRead)