diff --git a/crypto/src/cms/SignerInfoGenerator.cs b/crypto/src/cms/SignerInfoGenerator.cs index a5da35244..b50555da1 100644 --- a/crypto/src/cms/SignerInfoGenerator.cs +++ b/crypto/src/cms/SignerInfoGenerator.cs @@ -4,6 +4,11 @@ namespace Org.BouncyCastle.Cms { + /// + /// Pre-configured CMS SignerInfo for signed-data creation. Build with + /// , then pass to + /// . + /// public class SignerInfoGenerator { private readonly SignerIdentifier m_sigID; @@ -22,10 +27,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 +44,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. Otherwise, a null + /// signed-attribute generator selects . + /// public class SignerInfoGeneratorBuilder { private bool m_directSignature; private CmsAttributeTableGenerator m_signedGen; private CmsAttributeTableGenerator m_unsignedGen; + /// Initialises 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 +118,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) {