From 38b7d5232353ffe6b30f9171a006feaa4ee511a5 Mon Sep 17 00:00:00 2001 From: Konradsop Date: Mon, 8 Jun 2026 22:23:50 +0200 Subject: [PATCH] docs: add XML documentation for CMS SignedData generator Document CmsSignedDataGenerator: class summary, constructors, all AddSigner overload families, AddSignerInfoGenerator, Generate overloads, GenerateCounterSigners and UseDefiniteLength. Converts legacy block comments to XML with accurate CmsException contracts on generation paths. Wrap a pre-existing commented line to the 120-character limit. No behavioural changes. --- crypto/src/cms/CMSSignedDataGenerator.cs | 270 +++++++++++++---------- 1 file changed, 151 insertions(+), 119 deletions(-) diff --git a/crypto/src/cms/CMSSignedDataGenerator.cs b/crypto/src/cms/CMSSignedDataGenerator.cs index 0fee4bfc2..4f196c4f3 100644 --- a/crypto/src/cms/CMSSignedDataGenerator.cs +++ b/crypto/src/cms/CMSSignedDataGenerator.cs @@ -18,24 +18,12 @@ namespace Org.BouncyCastle.Cms { - /** - * general class for generating a pkcs7-signature message. - *

- * A simple example of usage. - * - * 

-     *      IX509Store certs...
-     *      IX509Store crls...
-     *      CmsSignedDataGenerator gen = new CmsSignedDataGenerator();
-     *
-     *      gen.AddSigner(privKey, cert, CmsSignedGenerator.DigestSha1);
-     *      gen.AddCertificates(certs);
-     *      gen.AddCrls(crls);
-     *
-     *      CmsSignedData data = gen.Generate(content);
-     *
- *

- */ + /// + /// Generator for CMS SignedData (PKCS#7 signed-data) messages. Configure signers with + /// (and overloads), add + /// certificates and CRLs via the base methods, then call + /// to obtain a instance. + /// public class CmsSignedDataGenerator : CmsSignedGenerator { @@ -86,7 +74,8 @@ internal SignerInf( // else // { // // NOTE: We'd need a complete AlgorithmIdentifier ('digAlgID') instead of only 'digAlgOid' - // throw new ArgumentException("Ed448 cannot be used with this constructor and signed attributes"); + // throw new ArgumentException( + // "Ed448 cannot be used with this constructor and signed attributes"); // } // var sigAlgID = new AlgorithmIdentifier(sigAlgOid); @@ -315,37 +304,38 @@ internal SignerInfo ToSignerInfo(DerObjectIdentifier contentType, CmsProcessable } } + /// Creates a generator using the default randomness source. public CmsSignedDataGenerator() { } - /// Constructor allowing specific source of randomness - /// Instance of SecureRandom to use. + /// + /// Creates a generator with an explicit randomness source for signature generation. + /// + /// The secure random to use when signing. public CmsSignedDataGenerator(SecureRandom random) : base(random) { } - /** - * add a signer - no attributes other than the default ones will be - * provided here. - * - * @param key signing key to use - * @param cert certificate containing corresponding public key - * @param digestOID digest algorithm OID - */ + /// + /// Adds a signer identified by certificate, inferring the signature algorithm OID from the key type. + /// Only default signed attributes are included. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The digest algorithm OID. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string digestOID) => AddSigner(privateKey, cert, CmsSignedHelper.GetEncOid(privateKey, digestOID)?.GetID(), digestOID); - /** - * add a signer, specifying the digest encryption algorithm to use - no attributes other than the default ones - * will be provided here. - * - * @param key signing key to use - * @param cert certificate containing corresponding public key - * @param encryptionOID digest encryption algorithm OID - * @param digestOID digest algorithm OID - */ + /// + /// Adds a signer identified by certificate with explicit digest and signature algorithm OIDs. + /// Only default signed attributes are included. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string encryptionOID, string digestOID) { @@ -353,17 +343,24 @@ public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, s new DerObjectIdentifier(digestOID), new DefaultSignedAttributeTableGenerator(), null, null); } - /** - * add a signer - no attributes other than the default ones will be - * provided here. - */ + /// + /// Adds a signer identified by subject key identifier, inferring the signature algorithm OID from the key. + /// Only default signed attributes are included. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The digest algorithm OID. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string digestOID) => AddSigner(privateKey, subjectKeyID, CmsSignedHelper.GetEncOid(privateKey, digestOID)?.GetID(), digestOID); - /** - * add a signer, specifying the digest encryption algorithm to use - no attributes other than the default ones will be - * provided here. - */ + /// + /// Adds a signer identified by subject key identifier with explicit digest and signature algorithm OIDs. + /// Only default signed attributes are included. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string encryptionOID, string digestOID) { @@ -371,15 +368,14 @@ public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, st new DerObjectIdentifier(digestOID), new DefaultSignedAttributeTableGenerator(), null, null); } - /** - * add a signer with extra signed/unsigned attributes. - * - * @param key signing key to use - * @param cert certificate containing corresponding public key - * @param digestOID digest algorithm OID - * @param signedAttr table of attributes to be included in signature - * @param unsignedAttr table of attributes to be included as unsigned - */ + /// + /// Adds a certificate-identified signer with caller-supplied signed and unsigned attribute tables. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The digest algorithm OID. + /// Signed attributes to include (merged with defaults). + /// Unsigned attributes to include. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string digestOID, Asn1.Cms.AttributeTable signedAttr, Asn1.Cms.AttributeTable unsignedAttr) { @@ -387,16 +383,15 @@ public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, s signedAttr, unsignedAttr); } - /** - * add a signer, specifying the digest encryption algorithm, with extra signed/unsigned attributes. - * - * @param key signing key to use - * @param cert certificate containing corresponding public key - * @param encryptionOID digest encryption algorithm OID - * @param digestOID digest algorithm OID - * @param signedAttr table of attributes to be included in signature - * @param unsignedAttr table of attributes to be included as unsigned - */ + /// + /// Adds a certificate-identified signer with explicit algorithm OIDs and attribute tables. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. + /// Signed attributes to include (merged with defaults). + /// Unsigned attributes to include. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string encryptionOID, string digestOID, Asn1.Cms.AttributeTable signedAttr, Asn1.Cms.AttributeTable unsignedAttr) { @@ -405,15 +400,14 @@ public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, s new SimpleAttributeTableGenerator(unsignedAttr), signedAttr); } - /** - * add a signer with extra signed/unsigned attributes. - * - * @param key signing key to use - * @param subjectKeyID subjectKeyID of corresponding public key - * @param digestOID digest algorithm OID - * @param signedAttr table of attributes to be included in signature - * @param unsignedAttr table of attributes to be included as unsigned - */ + /// + /// Adds a subject-key-id-identified signer with caller-supplied signed and unsigned attribute tables. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The digest algorithm OID. + /// Signed attributes to include (merged with defaults). + /// Unsigned attributes to include. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string digestOID, Asn1.Cms.AttributeTable signedAttr, Asn1.Cms.AttributeTable unsignedAttr) { @@ -421,16 +415,15 @@ public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, st signedAttr, unsignedAttr); } - /** - * add a signer, specifying the digest encryption algorithm, with extra signed/unsigned attributes. - * - * @param key signing key to use - * @param subjectKeyID subjectKeyID of corresponding public key - * @param encryptionOID digest encryption algorithm OID - * @param digestOID digest algorithm OID - * @param signedAttr table of attributes to be included in signature - * @param unsignedAttr table of attributes to be included as unsigned - */ + /// + /// Adds a subject-key-id-identified signer with explicit algorithm OIDs and attribute tables. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. + /// Signed attributes to include (merged with defaults). + /// Unsigned attributes to include. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string encryptionOID, string digestOID, Asn1.Cms.AttributeTable signedAttr, Asn1.Cms.AttributeTable unsignedAttr) { @@ -439,9 +432,14 @@ public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, st new SimpleAttributeTableGenerator(unsignedAttr), signedAttr); } - /** - * add a signer with extra signed/unsigned attributes based on generators. - */ + /// + /// Adds a certificate-identified signer with attribute-table generators for signed and unsigned attributes. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The digest algorithm OID. + /// Generator for signed attributes. + /// Generator for unsigned attributes. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string digestOID, CmsAttributeTableGenerator signedAttrGen, CmsAttributeTableGenerator unsignedAttrGen) { @@ -449,9 +447,15 @@ public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, s signedAttrGen, unsignedAttrGen); } - /** - * add a signer, specifying the digest encryption algorithm, with extra signed/unsigned attributes based on generators. - */ + /// + /// Adds a certificate-identified signer with explicit algorithm OIDs and attribute-table generators. + /// + /// The signing private key. + /// The signer's X.509 certificate. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. + /// Generator for signed attributes. + /// Generator for unsigned attributes. public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, string encryptionOID, string digestOID, CmsAttributeTableGenerator signedAttrGen, CmsAttributeTableGenerator unsignedAttrGen) { @@ -459,9 +463,14 @@ public void AddSigner(AsymmetricKeyParameter privateKey, X509Certificate cert, s new DerObjectIdentifier(digestOID), signedAttrGen, unsignedAttrGen, null); } - /** - * add a signer with extra signed/unsigned attributes based on generators. - */ + /// + /// Adds a subject-key-id-identified signer with attribute-table generators. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The digest algorithm OID. + /// Generator for signed attributes. + /// Generator for unsigned attributes. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string digestOID, CmsAttributeTableGenerator signedAttrGen, CmsAttributeTableGenerator unsignedAttrGen) { @@ -469,9 +478,15 @@ public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, st signedAttrGen, unsignedAttrGen); } - /** - * add a signer, including digest encryption algorithm, with extra signed/unsigned attributes based on generators. - */ + /// + /// Adds a subject-key-id-identified signer with explicit algorithm OIDs and attribute-table generators. + /// + /// The signing private key. + /// The subject key identifier octets. + /// The signature (encryption) algorithm OID. + /// The digest algorithm OID. + /// Generator for signed attributes. + /// Generator for unsigned attributes. public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, string encryptionOID, string digestOID, CmsAttributeTableGenerator signedAttrGen, CmsAttributeTableGenerator unsignedAttrGen) { @@ -479,6 +494,10 @@ public void AddSigner(AsymmetricKeyParameter privateKey, byte[] subjectKeyID, st new DerObjectIdentifier(digestOID), signedAttrGen, unsignedAttrGen, null); } + /// + /// Adds a signer using a pre-configured . + /// + /// The signer configuration to add. public void AddSignerInfoGenerator(SignerInfoGenerator signerInfoGenerator) { signerInfs.Add( @@ -495,26 +514,38 @@ private void DoAddSigner(AsymmetricKeyParameter privateKey, SignerIdentifier sig signedAttrGen, unsignedAttrGen, baseSignedTable)); } - /** - * generate a signed object that for a CMS Signed Data object - */ + /// + /// Generates a CMS SignedData object for without encapsulating the content. + /// + /// The content to sign. + /// The signed-data structure. + /// + /// An error occurred while building signer information or encapsulating content. + /// public CmsSignedData Generate(CmsProcessable content) => Generate(content, encapsulate: false); - /** - * generate a signed object that for a CMS Signed Data - * object - if encapsulate is true a copy - * of the message will be included in the signature with the - * default content type "data". - */ + /// + /// Generates a CMS SignedData object, optionally encapsulating a copy of the content with type data. + /// + /// The content to sign. + /// true to embed the content in the SignedData. + /// The signed-data structure. + /// + /// An error occurred while building signer information or encapsulating content. + /// public CmsSignedData Generate(CmsProcessable content, bool encapsulate) => Generate(signedContentType: Data, content, encapsulate); - /** - * generate a signed object that for a CMS Signed Data - * object - if encapsulate is true a copy - * of the message will be included in the signature. The content type - * is set according to the OID represented by the string signedContentType. - */ + /// + /// Generates a CMS SignedData object with an explicit encapsulated content type OID. + /// + /// Dotted-decimal OID of the encapsulated content type. + /// The content to sign. + /// true to embed the content in the SignedData. + /// The signed-data structure. + /// + /// An error occurred while building signer information or encapsulating content. + /// // TODO[api] Rename parameters public CmsSignedData Generate( string signedContentType, @@ -614,14 +645,12 @@ public CmsSignedData Generate( return new CmsSignedData(content, contentInfo); } - /** - * generate a set of one or more SignerInformation objects representing counter signatures on - * the passed in SignerInformation object. - * - * @param signer the signer to be countersigned - * @param sigProvider the provider to be used for counter signing. - * @return a store containing the signers. - */ + /// + /// Generates counter-signature SignerInformation objects over an existing signer's signature value. + /// + /// The signer to countersign. + /// A store containing the counter-signature signer informations. + /// An error occurred while creating counter signatures. public SignerInformationStore GenerateCounterSigners(SignerInformation signer) { m_digests.Clear(); @@ -663,6 +692,9 @@ public SignerInformationStore GenerateCounterSigners(SignerInformation signer) return new SignerInformationStore(signerInformations); } + /// + /// When true, generated SignedData structures use definite-length (DL) encoding where supported. + /// public bool UseDefiniteLength { get { return _useDefiniteLength; }