Class SignerBuilder

Namespace

SimpleSign.PAdES

Assembly

SimpleSign.PAdES.dll

Immutable builder that accumulates signing configuration. Each method returns a new instance — no shared mutable state.

public sealed class SignerBuilder

Inheritance

object

SignerBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

SignerBuilderBrasilExtensions.WithAdvancedSignature(SignerBuilder, AdvancedSignatureInfo)

Properties

CountryExtensions

The registered country extensions. Consumed by PdfSignatureValidator during validation.

public IReadOnlyList<ICountryExtension> CountryExtensions { get; }

Property Value

IReadOnlyList<ICountryExtension>

Methods

AsCertification(CertificationLevel)

Creates a certification (DocMDP) signature that restricts subsequent document modifications. Only the first signature in a document can be a certification signature.

public SignerBuilder AsCertification(CertificationLevel level = CertificationLevel.FormFilling)

Parameters

level CertificationLevel

The permitted modification level after certification.

Returns

SignerBuilder

SignAsync(Stream, CancellationToken)

Executes the signing operation and returns the signed PDF as a byte array.

public Task SignAsync(Stream outputStream, CancellationToken cancellationToken = default)

Parameters

outputStream Stream

cancellationToken CancellationToken

Returns

Task

Exceptions

SigningException

Certificate is missing, expired, lacks private key, or document is DocMDP-locked.

EncryptedPdfException

The PDF is encrypted.

NotSupportedException

Unsupported hash algorithm or key type.

HttpRequestException

Timestamp or LTV network operations failed.

SignAsync(CancellationToken)

Executes the signing operation and returns the signed PDF as a byte array.

public Task<byte[]> SignAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<byte[]>

Exceptions

SigningException

Certificate is missing, expired, lacks private key, or document is DocMDP-locked.

EncryptedPdfException

The PDF is encrypted.

NotSupportedException

Unsupported hash algorithm or key type.

HttpRequestException

Timestamp or LTV network operations failed.

SignWithDetailsAsync(CancellationToken)

Executes the signing operation and returns a PdfSigningResult with the signed PDF and any non-fatal warnings (e.g., LTV data unavailable, certificate lacks NonRepudiation). Prefer this method over SignAsync(CancellationToken) when you need to programmatically verify that LTV data was actually embedded.

public Task<PdfSigningResult> SignWithDetailsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<PdfSigningResult>

WithAppearance(SignatureAppearance)

Adds a visual appearance (stamp) to the signature on a specific page. The stamp displays the signer name, date/time, and other configured metadata.

public SignerBuilder WithAppearance(SignatureAppearance appearance)

Parameters

appearance SignatureAppearance

Returns

SignerBuilder

WithArchivalTimestamp(string?)

Enables PAdES-B-LTA by adding a document-level timestamp (DocTimeStamp) after LTV embedding. This is the highest level of PAdES compliance, guaranteeing archival validation. Requires LTV to be enabled (call WithLtv() first).

public SignerBuilder WithArchivalTimestamp(string? tsaUrl = null)

Parameters

tsaUrl string

TSA URL for the archival timestamp. If null, uses the same TSA as WithTimestamp.

Returns

SignerBuilder

Exceptions

InvalidOperationException

Thrown if LTV has not been enabled.

WithCertificate(X509Certificate2)

Sets the certificate with private key for signing.

public SignerBuilder WithCertificate(X509Certificate2 certificate)

Parameters

certificate X509Certificate2

Returns

SignerBuilder

WithCertificate(X509Certificate2, IReadOnlyList<X509Certificate2>)

Sets the certificate and full chain (for LTV and offline validation).

public SignerBuilder WithCertificate(X509Certificate2 certificate, IReadOnlyList<X509Certificate2> chain)

Parameters

certificate X509Certificate2

chain IReadOnlyList<X509Certificate2>

Returns

SignerBuilder

WithCountryExtension(ICountryExtension)

Registers a pre-configured country extension instance for DI scenarios where the extension needs constructor-injected dependencies (HttpClient, ILogger).

public SignerBuilder WithCountryExtension(ICountryExtension extension)

Parameters

extension ICountryExtension

Returns

SignerBuilder

WithCountryExtension<T>()

Registers a country/region-specific extension package (e.g., ICP-Brasil, eIDAS). Extensions provide trust anchors for validation and chain validation providers that enrich SignatureValidationResult with country-specific metadata (policy level, signer national ID, etc.).

public SignerBuilder WithCountryExtension<T>() where T : ICountryExtension, new()

Returns

SignerBuilder

Type Parameters

T

A concrete ICountryExtension with a parameterless constructor.

WithExistingField(string)

Signs an existing empty signature field instead of creating a new one. The field must already exist in the PDF with an empty /V value.

public SignerBuilder WithExistingField(string fieldName)

Parameters

fieldName string

The name of the existing signature field (the /T value).

Returns

SignerBuilder

WithExternalSigner(X509Certificate2, Func<byte[], Task<byte[]>>)

Configures an external signing delegate with automatic algorithm detection from the certificate. Supports RSA, ECDSA, and EdDSA certificate public key OIDs.

public SignerBuilder WithExternalSigner(X509Certificate2 certificate, Func<byte[], Task<byte[]>> externalSigner)

Parameters

certificate X509Certificate2

externalSigner Func<byte[], Task<byte[]>>

Returns

SignerBuilder

WithExternalSigner(X509Certificate2, Func<byte[], Task<byte[]>>, IReadOnlyList<X509Certificate2>)

Configures an external signing delegate with automatic algorithm detection and supplies the pre-fetched intermediate certificate chain.

public SignerBuilder WithExternalSigner(X509Certificate2 certificate, Func<byte[], Task<byte[]>> externalSigner, IReadOnlyList<X509Certificate2> chain)

Parameters

certificate X509Certificate2

The signer's public certificate (private key NOT required).

externalSigner Func<byte[], Task<byte[]>>

External signing delegate (DER input → raw signature).

chain IReadOnlyList<X509Certificate2>

Intermediate CA certificates, ordered from the issuer up to (but not including) the root. May be empty.

Returns

SignerBuilder

WithExternalSigner(X509Certificate2, Func<byte[], Task<byte[]>>, string)

Configures an external signing delegate for A3 tokens, HSMs, or cloud KMS. The delegate receives the DER-encoded signed attributes and must return the raw signature bytes.

public SignerBuilder WithExternalSigner(X509Certificate2 certificate, Func<byte[], Task<byte[]>> externalSigner, string signatureAlgorithmOid)

Parameters

certificate X509Certificate2

The signer's public certificate (private key NOT required).

externalSigner Func<byte[], Task<byte[]>>

Delegate that signs data externally. Input: DER-encoded signed attributes. Output: raw signature (RSA PKCS#1 or ECDSA DER SEQUENCE { r, s }).

signatureAlgorithmOid string

The signature algorithm OID (e.g., "1.2.840.113549.1.1.11" for RSA-SHA256). Use Oids for common values.

Returns

SignerBuilder

WithExternalSigner(X509Certificate2, Func<byte[], Task<byte[]>>, string, IReadOnlyList<X509Certificate2>)

Configures an external signing delegate with an explicit signature algorithm OID and supplies the pre-fetched intermediate certificate chain. Use this when the signing service also returns the chain (e.g., an HSM API or cloud KMS endpoint) to avoid redundant AIA HTTP requests during LTV embedding.

public SignerBuilder WithExternalSigner(X509Certificate2 certificate, Func<byte[], Task<byte[]>> externalSigner, string signatureAlgorithmOid, IReadOnlyList<X509Certificate2> chain)

Parameters

certificate X509Certificate2

The signer's public certificate (private key NOT required).

externalSigner Func<byte[], Task<byte[]>>

Delegate that signs data externally. Input: DER-encoded signed attributes. Output: raw signature (RSA PKCS#1 or ECDSA DER SEQUENCE { r, s }).

signatureAlgorithmOid string

The signature algorithm OID (e.g., "1.2.840.113549.1.1.11" for RSA-SHA256). Use Oids for common values.

chain IReadOnlyList<X509Certificate2>

Intermediate CA certificates, ordered from the issuer of certificate up to (but not including) the root. May be empty.

Returns

SignerBuilder

WithFieldName(string)

Sets the signature field name.

public SignerBuilder WithFieldName(string fieldName)

Parameters

fieldName string

Returns

SignerBuilder

WithHashAlgorithm(HashAlgorithmName)

Sets the hash algorithm. Default: SHA-256 (recommended by ICP-Brasil).

public SignerBuilder WithHashAlgorithm(HashAlgorithmName algorithm)

Parameters

algorithm HashAlgorithmName

Returns

SignerBuilder

WithHttpClient(HttpClient)

Sets the default HttpClient for all outbound HTTP operations (OCSP, CRL, AIA, and TSA when no TSA-specific client is configured via WithTimestamp(string, HttpClient)).

public SignerBuilder WithHttpClient(HttpClient httpClient)

Parameters

httpClient HttpClient

Returns

SignerBuilder

WithHttpClientProvider(IHttpClientProvider)

Sets a custom IHttpClientProvider for all HTTP operations. Use this in ASP.NET Core to integrate with IHttpClientFactory.

public SignerBuilder WithHttpClientProvider(IHttpClientProvider provider)

Parameters

provider IHttpClientProvider

Returns

SignerBuilder

WithLegacyCms()

Produces a plain PKCS#7/CMS signature (adbe.pkcs7.detached) without PAdES-specific attributes (no id-aa-signingCertificateV2 / ESS CertV2). Use this to interoperate with legacy systems or to replicate signatures produced by tools that predate PAdES (Level: CMS — no PAdES attributes).

public SignerBuilder WithLegacyCms()

Returns

SignerBuilder

Remarks

When this mode is active, the resulting signature is NOT considered PAdES-compliant. Validators that enforce PAdES (e.g., ITI) may report the signature as non-conformant.

WithLtv()

Enables LTV (Long-Term Validation) by embedding DSS with CRLs, OCSP responses, and VRI in the signed PDF. Requires an HttpClient for downloading revocation data. Requires a timestamp (call WithTimestamp(string) first) — PAdES B-LT needs B-T.

public SignerBuilder WithLtv()

Returns

SignerBuilder

Exceptions

InvalidOperationException

Thrown if no TSA URL has been configured.

WithMetadata(SignatureMetadata)

Configures generic signer metadata for the signature. Use this for country-agnostic signing with structured metadata. For Brazil-specific signing, use WithAdvancedSignature from SimpleSign.Brasil.

public SignerBuilder WithMetadata(SignatureMetadata metadata)

Parameters

metadata SignatureMetadata

Returns

SignerBuilder

WithMetadata(string?, string?, string?, string?)

Sets visible metadata on the signature.

public SignerBuilder WithMetadata(string? signerName = null, string? reason = null, string? location = null, string? contactInfo = null)

Parameters

signerName string

reason string

location string

contactInfo string

Returns

SignerBuilder

WithOperationId(string)

Sets an operation ID for correlation in log messages.

public SignerBuilder WithOperationId(string operationId)

Parameters

operationId string

Returns

SignerBuilder

WithPdfAPreservation()

Enables PDF/A conformance checking before signing. If the input document is a PDF/A file and the signature options are incompatible with that level, a SigningException is thrown during signing.

public SignerBuilder WithPdfAPreservation()

Returns

SignerBuilder

WithSignatureAlgorithm(string)

Forces a specific signature algorithm, overriding the algorithm inferred from the certificate's public key type. The primary use case is producing RSASSA-PSS signatures with a certificate whose public key OID is rsaEncryption (1.2.840.113549.1.1.1) rather than id-RSASSA-PSS (1.2.840.113549.1.1.10). Compatibility with the certificate's key type is validated at signing time.

public SignerBuilder WithSignatureAlgorithm(string signatureAlgorithmOid)

Parameters

signatureAlgorithmOid string

OID of the signature algorithm (e.g., Oids.RsaPss).

Returns

SignerBuilder

WithSubFilter(PdfSignatureSubFilter)

Sets the signature SubFilter value independently of PAdES attribute configuration. Default is EtsiCadesDetached. Use AdbePkcs7Detached for PDF/A-1 compatibility or when the target validator requires the legacy subfilter.

public SignerBuilder WithSubFilter(PdfSignatureSubFilter subFilter)

Parameters

subFilter PdfSignatureSubFilter

Returns

SignerBuilder

Remarks

Unlike WithLegacyCms(), this method does NOT disable CAdES/PAdES attributes. The resulting signature includes full PAdES-B-B attributes (signing-certificate-v2, etc.) while using the specified SubFilter value in the PDF signature dictionary.

WithTimestamp(string)

Configures the timestamp (TSA) using the default HttpClient.

public SignerBuilder WithTimestamp(string tsaUrl)

Parameters

tsaUrl string

Returns

SignerBuilder

WithTimestamp(string, HttpClient)

Configures the timestamp with a custom HttpClient (for testing/proxy).

public SignerBuilder WithTimestamp(string tsaUrl, HttpClient httpClient)

Parameters

tsaUrl string

httpClient HttpClient

Returns

SignerBuilder