From 4ae771ccd8e838275e68fcf55090a098e6d58d8a Mon Sep 17 00:00:00 2001 From: Konradsop Date: Fri, 4 Sep 2026 07:52:16 +0200 Subject: [PATCH] Add XML documentation for CMS attribute and originator generators --- crypto/src/cms/CMSCompressedDataGenerator.cs | 15 +++++++- ...ultAuthenticatedAttributeTableGenerator.cs | 8 +++- .../DefaultSignedAttributeTableGenerator.cs | 10 ++++- crypto/src/cms/OriginatorInfoGenerator.cs | 20 ++++++++++ .../src/cms/SimpleAttributeTableGenerator.cs | 38 ++++++++++--------- 5 files changed, 70 insertions(+), 21 deletions(-) diff --git a/crypto/src/cms/CMSCompressedDataGenerator.cs b/crypto/src/cms/CMSCompressedDataGenerator.cs index 9043a1f580..b52e3bc9ac 100644 --- a/crypto/src/cms/CMSCompressedDataGenerator.cs +++ b/crypto/src/cms/CMSCompressedDataGenerator.cs @@ -7,14 +7,19 @@ namespace Org.BouncyCastle.Cms { - /// General class for generating a compressed CMS message. + /// + /// Generator for CMS CompressedData messages. Compresses content with ZLIB and returns a + /// instance (read-side: Batch 15d, #703). + /// public class CmsCompressedDataGenerator { + /// The object identifier for ZLIB compression (id-zlibCompress). public static readonly string ZLib = CmsObjectIdentifiers.ZlibCompress.Id; private static readonly AlgorithmIdentifier ZLibCompressionAlgorithm = new AlgorithmIdentifier(CmsObjectIdentifiers.ZlibCompress); + /// Creates a compressed-data generator. public CmsCompressedDataGenerator() { } @@ -24,6 +29,14 @@ public CmsCompressedDataGenerator() public CmsCompressedData Generate(CmsProcessable content, string compressionOid) => Generate(CmsUtilities.GetTypedData(content), compressionOid); + /// Generates a CMS CompressedData message for . + /// The content to compress. + /// The compression algorithm OID (currently only ). + /// A compressed-data structure. + /// + /// Thrown if is not supported. + /// + /// Thrown if the content cannot be compressed. public CmsCompressedData Generate(CmsTypedData content, string compressionOid) { if (ZLib != compressionOid) diff --git a/crypto/src/cms/DefaultAuthenticatedAttributeTableGenerator.cs b/crypto/src/cms/DefaultAuthenticatedAttributeTableGenerator.cs index fb367b7c47..f8d5dca369 100644 --- a/crypto/src/cms/DefaultAuthenticatedAttributeTableGenerator.cs +++ b/crypto/src/cms/DefaultAuthenticatedAttributeTableGenerator.cs @@ -7,7 +7,11 @@ namespace Org.BouncyCastle.Cms { - /// Default authenticated attributes generator. + /// + /// Default authenticated-attribute generator for CMS AuthenticatedData. Supplies contentType, messageDigest, and + /// cmsAlgorithmProtect unless overridden. Used by and related + /// generators. + /// public class DefaultAuthenticatedAttributeTableGenerator : CmsAttributeTableGenerator { @@ -33,6 +37,8 @@ public DefaultAuthenticatedAttributeTableGenerator(AttributeTable attributeTable } /// Returns a populated . + /// Generation parameters supplied by the CMS generator. + /// An attribute table including standard authenticated attributes. public virtual AttributeTable GetAttributes(IDictionary parameters) { var table = CreateStandardAttributeTable(parameters); diff --git a/crypto/src/cms/DefaultSignedAttributeTableGenerator.cs b/crypto/src/cms/DefaultSignedAttributeTableGenerator.cs index 6b1e0bbd1f..0e8302ae1a 100644 --- a/crypto/src/cms/DefaultSignedAttributeTableGenerator.cs +++ b/crypto/src/cms/DefaultSignedAttributeTableGenerator.cs @@ -8,7 +8,11 @@ namespace Org.BouncyCastle.Cms { - /// Default signed attributes generator. + /// + /// Default signed-attribute generator for CMS SignedData. Supplies contentType, signingTime, messageDigest, and + /// cmsAlgorithmProtect unless overridden. Used by and + /// AddSigner overloads. + /// public class DefaultSignedAttributeTableGenerator : CmsAttributeTableGenerator { @@ -33,7 +37,9 @@ public DefaultSignedAttributeTableGenerator(AttributeTable attributeTable) } } - /// Returns a populated . + /// Returns a populated . + /// Generation parameters supplied by the CMS generator. + /// An attribute table including standard signed attributes. public virtual AttributeTable GetAttributes(IDictionary parameters) { var table = CreateStandardAttributeTable(parameters); diff --git a/crypto/src/cms/OriginatorInfoGenerator.cs b/crypto/src/cms/OriginatorInfoGenerator.cs index a93da06722..80e64fefce 100644 --- a/crypto/src/cms/OriginatorInfoGenerator.cs +++ b/crypto/src/cms/OriginatorInfoGenerator.cs @@ -7,27 +7,45 @@ namespace Org.BouncyCastle.Cms { + /// + /// Builds CMS OriginatorInfo values carrying certificates and revocation information for authenticated + /// messages. The read-side wrapper is . + /// public class OriginatorInfoGenerator { private readonly List origCerts; private readonly List origCrls; + /// Creates a generator containing a single originator certificate. + /// The originator's X.509 certificate. public OriginatorInfoGenerator(X509Certificate origCert) { this.origCerts = new List{ origCert.CertificateStructure }; this.origCrls = null; } + /// Creates a generator from a store of originator certificates. + /// Public-key certificates to include, or null to omit. public OriginatorInfoGenerator(IStore x509Certs) : this(x509Certs, null, null, null) { } + /// Creates a generator from certificate and CRL stores. + /// Public-key certificates to include, or null to omit. + /// CRLs to include, or null to omit. public OriginatorInfoGenerator(IStore x509Certs, IStore x509Crls) : this(x509Certs, x509Crls, null, null) { } + /// + /// Creates a generator from certificate, CRL, attribute-certificate, and other-revocation stores. + /// + /// Public-key certificates to include, or null to omit. + /// CRLs to include, or null to omit. + /// Attribute certificates to include, or null to omit. + /// Other revocation information to include, or null to omit. public OriginatorInfoGenerator(IStore x509Certs, IStore x509Crls, IStore x509AttrCerts, IStore otherRevocationInfos) { @@ -63,6 +81,8 @@ public OriginatorInfoGenerator(IStore x509Certs, IStoreBuilds an OriginatorInfo structure from the configured stores. + /// A CMS OriginatorInfo value. public virtual OriginatorInfo Generate() => new OriginatorInfo(origCerts?.ToDerSet(), origCrls?.ToDerSet()); } } diff --git a/crypto/src/cms/SimpleAttributeTableGenerator.cs b/crypto/src/cms/SimpleAttributeTableGenerator.cs index 7b20ac3e29..363ce2185f 100644 --- a/crypto/src/cms/SimpleAttributeTableGenerator.cs +++ b/crypto/src/cms/SimpleAttributeTableGenerator.cs @@ -5,23 +5,27 @@ namespace Org.BouncyCastle.Cms { - /** - * Basic generator that just returns a preconstructed attribute table - */ - public class SimpleAttributeTableGenerator - : CmsAttributeTableGenerator - { - private readonly AttributeTable attributes; + /// + /// Returns a fixed regardless of generation parameters. Used for unsigned attributes + /// and other cases where attributes are fully preconfigured. + /// + public class SimpleAttributeTableGenerator + : CmsAttributeTableGenerator + { + private readonly AttributeTable attributes; - public SimpleAttributeTableGenerator( - AttributeTable attributes) - { - this.attributes = attributes; - } + /// Creates a generator that always returns . + /// The attribute table to return from . + public SimpleAttributeTableGenerator( + AttributeTable attributes) + { + this.attributes = attributes; + } - public virtual AttributeTable GetAttributes(IDictionary parameters) - { - return attributes; - } - } + /// + public virtual AttributeTable GetAttributes(IDictionary parameters) + { + return attributes; + } + } }