From 0c7b4d37e8c2342901cb81a764d328aa6a2b205a Mon Sep 17 00:00:00 2001 From: Konradsop Date: Fri, 4 Sep 2026 07:35:47 +0200 Subject: [PATCH 1/2] Add XML documentation for CMS SignerInfoGenerator --- crypto/src/cms/SignerInfoGenerator.cs | 78 +++++++++++++++------------ 1 file changed, 44 insertions(+), 34 deletions(-) diff --git a/crypto/src/cms/SignerInfoGenerator.cs b/crypto/src/cms/SignerInfoGenerator.cs index a5da35244..5083752c3 100644 --- a/crypto/src/cms/SignerInfoGenerator.cs +++ b/crypto/src/cms/SignerInfoGenerator.cs @@ -4,6 +4,10 @@ namespace Org.BouncyCastle.Cms { + /// + /// Pre-configured CMS signer used with . Build + /// instances with . + /// public class SignerInfoGenerator { private readonly SignerIdentifier m_sigID; @@ -22,10 +26,14 @@ internal SignerInfoGenerator(SignerIdentifier sigID, ISignatureFactory signature m_certificate = certificate; } + /// Gets the signer's X.509 certificate when built with one, otherwise null. public X509Certificate Certificate => m_certificate; + /// Gets the SignerInfo version that will be generated (1 or 3). public int GeneratedVersion => m_sigID.IsTagged ? 3 : 1; + /// Returns a builder pre-populated with this generator's attribute settings. + /// A new . public SignerInfoGeneratorBuilder NewBuilder() { SignerInfoGeneratorBuilder builder = new SignerInfoGeneratorBuilder(); @@ -35,69 +43,72 @@ public SignerInfoGeneratorBuilder NewBuilder() return builder; } + /// Gets the signature factory used to produce the SignerInfo signature value. public ISignatureFactory SignatureFactory => m_signatureFactory; + /// Gets the signed-attribute generator, or null for a direct signature over the content. public CmsAttributeTableGenerator SignedAttributeTableGenerator => m_signedGen; + /// Gets the signer identifier (issuer/serial or subject key identifier). public SignerIdentifier SignerID => m_sigID; + /// Gets the unsigned-attribute generator, if any. public CmsAttributeTableGenerator UnsignedAttributeTableGenerator => m_unsignedGen; } + /// + /// Builds instances for CMS SignedData creation. Use + /// for a signature over the raw content, or attribute generators for the + /// standard signed-attribute workflow. + /// public class SignerInfoGeneratorBuilder { private bool m_directSignature; private CmsAttributeTableGenerator m_signedGen; private CmsAttributeTableGenerator m_unsignedGen; + /// Creates a builder with default signed-attribute generation. public SignerInfoGeneratorBuilder() { } - /** - * If the passed in flag is true, the signer signature will be based on the data, not - * a collection of signed attributes, and no signed attributes will be included. - * - * @return the builder object - */ + /// + /// When is true, the signature is computed over the content only and + /// no signed or unsigned attributes are included. + /// + /// Whether to omit signed attributes (direct signature). + /// This builder. public SignerInfoGeneratorBuilder SetDirectSignature(bool hasNoSignedAttributes) { m_directSignature = hasNoSignedAttributes; return this; } - /** - * Provide a custom signed attribute generator. - * - * @param signedGen a generator of signed attributes. - * @return the builder object - */ + /// Sets a custom generator for signed attributes. + /// The signed-attribute generator, or null to use the default. + /// This builder. public SignerInfoGeneratorBuilder WithSignedAttributeGenerator(CmsAttributeTableGenerator signedGen) { m_signedGen = signedGen; return this; } - /** - * Provide a generator of unsigned attributes. - * - * @param unsignedGen a generator for signed attributes. - * @return the builder object - */ + /// Sets a generator for unsigned attributes. + /// The unsigned-attribute generator. + /// This builder. public SignerInfoGeneratorBuilder WithUnsignedAttributeGenerator(CmsAttributeTableGenerator unsignedGen) { m_unsignedGen = unsignedGen; return this; } - /** - * Build a generator with the passed in X.509 certificate issuer and serial number as the signerIdentifier. - * - * @param contentSigner operator for generating the final signature in the SignerInfo with. - * @param certificate X.509 certificate related to the contentSigner. - * @return a SignerInfoGenerator - * @throws OperatorCreationException if the generator cannot be built. - */ + /// + /// Builds a generator that identifies the signer by X.509 issuer and serial number from + /// . + /// + /// The signature factory for the SignerInfo signature value. + /// The signer's X.509 certificate. + /// A configured . // TODO[api] 'contentSigner' => 'signatureFactory' public SignerInfoGenerator Build(ISignatureFactory contentSigner, X509Certificate certificate) { @@ -106,14 +117,13 @@ public SignerInfoGenerator Build(ISignatureFactory contentSigner, X509Certificat return CreateGenerator(contentSigner, sigID, certificate); } - /** - * Build a generator with the passed in subjectKeyIdentifier as the signerIdentifier. If used you should - * try to follow the calculation described in RFC 5280 section 4.2.1.2. - * - * @param signerFactory operator factory for generating the final signature in the SignerInfo with. - * @param subjectKeyIdentifier key identifier to identify the public key for verifying the signature. - * @return a SignerInfoGenerator - */ + /// + /// Builds a generator that identifies the signer by subject key identifier. The identifier should follow RFC + /// 5280 section 4.2.1.2 where possible. + /// + /// The signature factory for the SignerInfo signature value. + /// The key identifier for the verifying public key. + /// A configured . // TODO[api] 'signerFactory' => 'signatureFactory' public SignerInfoGenerator Build(ISignatureFactory signerFactory, byte[] subjectKeyIdentifier) { From 7c0d681f68b6127b7d542194abef275ff9f373e9 Mon Sep 17 00:00:00 2001 From: Konradsop Date: Fri, 4 Sep 2026 07:36:48 +0200 Subject: [PATCH 2/2] Align SignerInfoGenerator docs with Batch 14-15 style --- crypto/src/cms/SignerInfoGenerator.cs | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/crypto/src/cms/SignerInfoGenerator.cs b/crypto/src/cms/SignerInfoGenerator.cs index 5083752c3..b50555da1 100644 --- a/crypto/src/cms/SignerInfoGenerator.cs +++ b/crypto/src/cms/SignerInfoGenerator.cs @@ -5,8 +5,9 @@ namespace Org.BouncyCastle.Cms { /// - /// Pre-configured CMS signer used with . Build - /// instances with . + /// Pre-configured CMS SignerInfo for signed-data creation. Build with + /// , then pass to + /// . /// public class SignerInfoGenerator { @@ -56,18 +57,18 @@ public SignerInfoGeneratorBuilder NewBuilder() public CmsAttributeTableGenerator UnsignedAttributeTableGenerator => m_unsignedGen; } - /// - /// Builds instances for CMS SignedData creation. Use - /// for a signature over the raw content, or attribute generators for the - /// standard signed-attribute workflow. - /// + /// Builds instances for CMS SignedData creation. + /// + /// Use for a signature over the raw content. Otherwise, a null + /// signed-attribute generator selects . + /// public class SignerInfoGeneratorBuilder { private bool m_directSignature; private CmsAttributeTableGenerator m_signedGen; private CmsAttributeTableGenerator m_unsignedGen; - /// Creates a builder with default signed-attribute generation. + /// Initialises a builder with default signed-attribute generation. public SignerInfoGeneratorBuilder() { }