Class DeferredSignerBuilder

Namespace

SimpleSign.PAdES

Assembly

SimpleSign.PAdES.dll

Fluent builder for deferred (two-phase) PAdES signing. Immutable — each method returns a new instance with updated configuration.

public sealed class DeferredSignerBuilder

Inheritance

object

DeferredSignerBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Use this builder to configure and execute deferred signing workflows where the private key resides on a different machine (e.g., user's browser).

Example:

var signed = await new DeferredSignerBuilder(pdfBytes, cert)
    .WithSignerName("John Doe")
    .WithSignatureField(page: 1, x: 50, y: 700)
    .WithTimestamp("http://tsa.example.com")
    .SignAsync(externalSignature);

Constructors

DeferredSignerBuilder(byte[], X509Certificate2)

Initializes a new deferred signer builder with PDF bytes and signing certificate.

public DeferredSignerBuilder(byte[] pdfBytes, X509Certificate2 certificate)

Parameters

pdfBytes byte[]

PDF document bytes to sign.

certificate X509Certificate2

Signer's public certificate (private key NOT required).

Exceptions

ArgumentNullException

If pdfBytes or certificate is null.

Methods

CompleteAsync(byte[], byte[], CancellationToken)

Phase 2: Embeds the external signature and optional timestamp into the document.

public Task<byte[]> CompleteAsync(byte[] sessionData, byte[] rawSignature, CancellationToken cancellationToken = default)

Parameters

sessionData byte[]

rawSignature byte[]

cancellationToken CancellationToken

Returns

Task<byte[]>

PrepareAsync(CancellationToken)

Phase 1: Prepares the document and returns the hash to be signed. The hash must be signed by the external signer (e.g., hardware token, browser).

public Task<DeferredSigningPrepareResult> PrepareAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<DeferredSigningPrepareResult>

SignAsync(byte[], CancellationToken)

One-shot signing: Prepares the hash and immediately completes the signature. Use this when the signing happens synchronously on the same machine.

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

Parameters

signature byte[]

cancellationToken CancellationToken

Returns

Task<byte[]>

WithExtraCertificates(IReadOnlyList<X509Certificate2>)

Adds extra certificates (CA chain) to the signature for validation.

public DeferredSignerBuilder WithExtraCertificates(IReadOnlyList<X509Certificate2> certificates)

Parameters

certificates IReadOnlyList<X509Certificate2>

Returns

DeferredSignerBuilder

WithFieldName(string)

Sets the signature field name. Default: "Signature1".

public DeferredSignerBuilder WithFieldName(string name)

Parameters

name string

Returns

DeferredSignerBuilder

WithHashAlgorithm(HashAlgorithmName)

Sets the hash algorithm for the signature. Default: SHA-256.

public DeferredSignerBuilder WithHashAlgorithm(HashAlgorithmName algorithm)

Parameters

algorithm HashAlgorithmName

Returns

DeferredSignerBuilder

WithLocation(string)

Sets the signature location (e.g., "São Paulo, Brazil").

public DeferredSignerBuilder WithLocation(string location)

Parameters

location string

Returns

DeferredSignerBuilder

WithLogger(ILogger)

Sets a custom logger for diagnostic output.

public DeferredSignerBuilder WithLogger(ILogger logger)

Parameters

logger ILogger

Returns

DeferredSignerBuilder

WithReason(string)

Sets the signature reason (e.g., "Approval", "Agreement").

public DeferredSignerBuilder WithReason(string reason)

Parameters

reason string

Returns

DeferredSignerBuilder

WithSignatureAlgorithmOid(string)

Specifies a custom signature algorithm OID. Default: auto-detected from certificate.

public DeferredSignerBuilder WithSignatureAlgorithmOid(string oid)

Parameters

oid string

Returns

DeferredSignerBuilder

WithSignatureField(int, float, float)

Configures the signature field position on the PDF.

public DeferredSignerBuilder WithSignatureField(int page, float x, float y)

Parameters

page int

Page number (1-based).

x float

X coordinate in points.

y float

Y coordinate in points.

Returns

DeferredSignerBuilder

WithSignerName(string)

Sets the signer's display name in the signature field.

public DeferredSignerBuilder WithSignerName(string name)

Parameters

name string

Returns

DeferredSignerBuilder

WithTimestamp(string)

Enables timestamp from a Time Stamp Authority (creates PAdES-T).

public DeferredSignerBuilder WithTimestamp(string tsaUrl)

Parameters

tsaUrl string

Returns

DeferredSignerBuilder

WithTimestamp(string, HttpClient)

Enables timestamp with a custom HTTP client. Useful for proxies or custom certificate validation.

public DeferredSignerBuilder WithTimestamp(string tsaUrl, HttpClient httpClient)

Parameters

tsaUrl string

httpClient HttpClient

Returns

DeferredSignerBuilder