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)

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. Implies WithLtv() — LTV is automatically enabled.

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

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

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[]>>, 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 SimpleSign.Core.Constants.Oids for common values.

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

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.

public SignerBuilder WithLtv()

Returns

SignerBuilder

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

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