Table of Contents

Class PadesSignerBuilder

Namespace
SimpleSign.PAdES
Assembly
SimpleSign.PAdES.dll

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

public sealed class PadesSignerBuilder
Inheritance
PadesSignerBuilder
Inherited Members
Extension Methods

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 PadesSignerBuilder AsCertification(CertificationLevel level = CertificationLevel.FormFilling)

Parameters

level CertificationLevel

The permitted modification level after certification.

Returns

PadesSignerBuilder

A new builder with the certification level configured.

SignAsync(Stream, CancellationToken)

Executes the signing operation and writes the signed PDF to the output stream.

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

Parameters

outputStream Stream
cancellationToken CancellationToken

Returns

Task

Remarks

Throws SigningException when the requested level profile is configured for best-effort downgrades; use SignWithDetailsAsync(CancellationToken) in that case.

Exceptions

ArgumentNullException

outputStream is null.

SigningException

Certificate is missing, expired, lacks private key, the requested level cannot be produced, or the document is DocMDP-locked.

EncryptedPdfException

The PDF is encrypted.

NotSupportedException

Unsupported hash algorithm or key type.

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[]>

Remarks

Throws SigningException when the requested level profile is configured for best-effort downgrades; use SignWithDetailsAsync(CancellationToken) in that case.

Exceptions

SigningException

Certificate is missing, expired, lacks private key, the requested level cannot be produced, or the document is DocMDP-locked.

EncryptedPdfException

The PDF is encrypted.

NotSupportedException

Unsupported hash algorithm or key type.

SignWithDetailsAsync(CancellationToken)

Executes the signing operation and returns a PadesSigningResult with the signed PDF, the requested and achieved baseline levels, actual feature flags, and any non-fatal warnings. Supports explicit best-effort downgrade profiles (ReturnLowerLevel).

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

Parameters

cancellationToken CancellationToken

Returns

Task<PadesSigningResult>

Exceptions

SigningException

Certificate is missing, expired, lacks private key, the requested level cannot be produced, or the document is DocMDP-locked.

EncryptedPdfException

The PDF is encrypted.

NotSupportedException

Unsupported hash algorithm or key type.

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 PadesSignerBuilder WithAppearance(SignatureAppearance appearance)

Parameters

appearance SignatureAppearance

The visual appearance configuration.

Returns

PadesSignerBuilder

A new builder with the appearance configured.

WithCertificate(X509Certificate2)

Sets the certificate with private key for local signing.

public PadesSignerBuilder WithCertificate(X509Certificate2 certificate)

Parameters

certificate X509Certificate2

The signing certificate. Must not be null.

Returns

PadesSignerBuilder

A new builder with the local credential configured.

WithCertificate(X509Certificate2, IReadOnlyList<X509Certificate2>)

Sets the certificate and its chain for local signing.

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

Parameters

certificate X509Certificate2

The signing certificate. Must not be null.

chain IReadOnlyList<X509Certificate2>

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

Returns

PadesSignerBuilder

A new builder with the local credential configured.

WithCountryExtension(ICountryExtension)

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

public PadesSignerBuilder WithCountryExtension(ICountryExtension extension)

Parameters

extension ICountryExtension

The country extension instance.

Returns

PadesSignerBuilder

A new builder with the extension registered.

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 PadesSignerBuilder WithCountryExtension<T>() where T : ICountryExtension, new()

Returns

PadesSignerBuilder

A new builder with the extension registered.

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 PadesSignerBuilder WithExistingField(string fieldName)

Parameters

fieldName string

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

Returns

PadesSignerBuilder

A new builder with the existing field configured.

WithExternalSigner(X509Certificate2, IExternalSigner)

Configures external signing with an explicit signer contract.

public PadesSignerBuilder WithExternalSigner(X509Certificate2 certificate, IExternalSigner signer)

Parameters

certificate X509Certificate2

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

signer IExternalSigner

The external signer implementation (HSM, cloud KMS, A3 token).

Returns

PadesSignerBuilder

A new builder with the external credential configured.

WithExternalSigner(X509Certificate2, IExternalSigner, IReadOnlyList<X509Certificate2>)

Configures external signing with an explicit signer contract and a pre-fetched chain.

public PadesSignerBuilder WithExternalSigner(X509Certificate2 certificate, IExternalSigner signer, IReadOnlyList<X509Certificate2> chain)

Parameters

certificate X509Certificate2

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

signer IExternalSigner

The external signer implementation (HSM, cloud KMS, A3 token).

chain IReadOnlyList<X509Certificate2>

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

Returns

PadesSignerBuilder

A new builder with the external credential configured.

WithFieldName(string)

Sets the signature field name.

public PadesSignerBuilder WithFieldName(string fieldName)

Parameters

fieldName string

The PDF signature field name.

Returns

PadesSignerBuilder

A new builder with the field name configured.

WithFieldOptions(SignatureFieldOptions)

Replaces the complete PDF signature-field configuration.

public PadesSignerBuilder WithFieldOptions(SignatureFieldOptions options)

Parameters

options SignatureFieldOptions

The complete field configuration to snapshot.

Returns

PadesSignerBuilder

A new builder with the supplied field configuration.

Remarks

Use this method when an optional field value previously configured on a builder must be cleared. Unlike the convenience methods, this operation replaces rather than merges field state.

WithHashAlgorithm(HashAlgorithmName)

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

public PadesSignerBuilder WithHashAlgorithm(HashAlgorithmName algorithm)

Parameters

algorithm HashAlgorithmName

The hash algorithm.

Returns

PadesSignerBuilder

A new builder with the hash algorithm configured.

WithHttpClientProvider(IHttpClientProvider)

Sets a builder-wide IHttpClientProvider used as the fallback for all network operations that do not carry their own scoped provider (timestamp, long-term validation material, archive timestamp).

public PadesSignerBuilder WithHttpClientProvider(IHttpClientProvider provider)

Parameters

provider IHttpClientProvider

The HTTP client provider.

Returns

PadesSignerBuilder

A new builder with the provider configured.

WithLevel(AdesBaselineProfile)

Replaces the complete baseline profile. The requested ETSI level and all of its dependencies travel together in one immutable value; no other method changes the level.

public PadesSignerBuilder WithLevel(AdesBaselineProfile profile)

Parameters

profile AdesBaselineProfile

The complete baseline profile (B-B, B-T, B-LT, or B-LTA).

Returns

PadesSignerBuilder

A new builder with the profile configured.

WithLogger(ILogger)

Sets the logger for diagnostic output.

public PadesSignerBuilder WithLogger(ILogger logger)

Parameters

logger ILogger

The logger.

Returns

PadesSignerBuilder

A new builder with the logger 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 PadesSignerBuilder WithMetadata(SignatureMetadata metadata)

Parameters

metadata SignatureMetadata

The signer metadata.

Returns

PadesSignerBuilder

A new builder with the metadata configured.

WithOperationId(string)

Sets an operation ID for correlation in log messages.

public PadesSignerBuilder WithOperationId(string operationId)

Parameters

operationId string

The operation ID.

Returns

PadesSignerBuilder

A new builder with the operation ID configured.

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 PadesSignerBuilder WithPdfAPreservation()

Returns

PadesSignerBuilder

A new builder with PDF/A preservation enabled.

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 PadesSignerBuilder WithSignatureAlgorithm(string signatureAlgorithmOid)

Parameters

signatureAlgorithmOid string

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

Returns

PadesSignerBuilder

A new builder with the signature algorithm configured.

WithSigningTime(DateTimeOffset)

Configures the claimed signing time embedded in the signature. This is not trusted proof of time; B-T or higher still requires a signature timestamp via WithLevel(AdesBaselineProfile).

public PadesSignerBuilder WithSigningTime(DateTimeOffset signingTime)

Parameters

signingTime DateTimeOffset

The claimed signing time. Default: UTC now.

Returns

PadesSignerBuilder

A new builder with the signing time configured.

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 PadesSignerBuilder WithSubFilter(PdfSignatureSubFilter subFilter)

Parameters

subFilter PdfSignatureSubFilter

The signature SubFilter value.

Returns

PadesSignerBuilder

A new builder with the SubFilter configured.

Edit this page