CSC (AES / QES)

The csc signing transport routes signatures through a third-party Trust Service Provider (TSP) using the Cloud Signature Consortium API v1.0.4.0. Each recipient authenticates directly with the TSP (Strong Customer Authentication) and the TSP returns a per-recipient signature bound to the document hash. Documenso assembles the resulting PAdES signature inside the PDF.

This transport enables Advanced Electronic Signatures (AES) and Qualified Electronic Signatures (QES) under eIDAS. See Signature Levels for the legal framework.

Prerequisites

${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback

Environment Variables

Configuration Example

NEXT_PRIVATE_SIGNING_TRANSPORT=csc
NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL=https://api.example-tsp.com/csc/v1
NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID=documenso-prod
NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET=...
NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL=QES
NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY=http://timestamp.example.com

Register ${NEXT_PUBLIC_WEBAPP_URL}/api/csc/oauth/callback (e.g. https://sign.example.com/api/csc/oauth/callback) as the OAuth callback URL with the TSP.

Default Signature Level

NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL selects the legal tier applied to envelopes that do not specify one explicitly. It is a default, not a capability gate: callers may still create AES or QES envelopes explicitly regardless of this setting.

Any value other than AES or QES causes the instance to refuse to start. This prevents silent qualified-to-advanced downgrades from a typo.

Timestamp Authority Resolution

AES/QES envelopes use TSA-attested timestamps in two distinct phases. Resolution differs per phase.

Sign time — PAdES B-T per recipient

Each recipient's CMS embeds a signature timestamp (CMS unsigned attribute) so proven time is bound to the recipient's signature itself. Resolution order:

1. If the TSP advertises signatures/timestamp in its info response (CSC §11.10), the TSP endpoint is used. The call is authorised with this recipient's service-scope bearer token — the same one authorising the signatures/signHash call alongside it.
2. Otherwise, the first URL from NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is used (RFC 3161 over HTTP).

Selection is made at boot from the discovered transport, not at runtime; there is no try-then-fall-through. If the chosen source fails, the recipient's sign attempt fails.

Seal time — PAdES B-LTA archival

The seal-document job emits a single archival /DocTimeStamp over the fully-signed envelope (plus DSS for the existing signatures and the timestamp's own chain). This phase is env-only: the first URL from NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is always used.

The archival anchor is the operator's long-term trust anchor and SHOULD point at a dedicated qualified archival TSA (e.g. DigiCert) independent of the per-recipient TSP. We deliberately do not fall back to the TSP at seal time: archive longevity should not be coupled to a TSP that may rotate or revoke, and the seal-document job has no recipient context to carry a service-scope bearer.

Boot-time guard

The instance refuses to start in CSC mode unless NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is set (CSC_PROVIDER_NO_TSA at transport construction). The env var is required unconditionally — even when the TSP advertises its own signatures/timestamp, seal-time B-LTA archival uses the env TSA. Catching this at boot prevents the failure mode where an envelope signs successfully at B-T and then hangs in WAITING_FOR_SIGNATURE_COMPLETION when the seal job throws.

Switching Transports

NEXT_PRIVATE_SIGNING_TRANSPORT is a one-way operational migration. Existing envelopes route per the signatureLevel column they were created with — the runtime branching looks at the envelope, not the env var. After a switch:

• Envelopes already at SES continue to use the new transport for sealing, but the new transport's signer must produce SES-compatible signatures (only local and gcloud-hsm qualify).
• Envelopes already at AES / QES will fail at sign or seal time if the new transport is not csc.

Plan migrations during a quiet window with no in-flight envelopes.

Behavioural Notes

CSC mode changes a number of envelope-authoring behaviours that operators should communicate to users.

Mutation lock at distribution

For AES/QES envelopes, all authoring routes refuse mutations once the envelope leaves DRAFT. This locks the PDF before any recipient begins Strong Customer Authentication, closing the PDF-swap window that would otherwise allow an owner to replace the PDF between view and sign and break the legal "what you see is what you sign" guarantee.

In practice: edit envelope, recipients, fields, and items freely while DRAFT; once sent, no changes are accepted (including from the API).

Sequential signing only

Parallel signing produces conflicting incremental updates over the same base PDF, breaking the per-recipient /ByteRange invariant. The signing order is forced to SEQUENTIAL on AES/QES envelopes — at the schema layer, at send time, and in the UI (the parallel-signing toggle is hidden).

Assistant role and Dictate Next Signer disabled

Both features modify the recipient set after the envelope is sent, which is incompatible with the AES/QES mutation lock. They are hidden in the UI and rejected at the server schema layer.

Sidecar PDFs at download

The signed PDF must remain byte-identical to what each recipient's TSP signature authorised — Documenso cannot decorate it after signing. Audit logs and the Certificate of Completion are generated on demand and delivered as separate PDFs:

• GET /sign/{token}/download returns the signed PDF only (or a ZIP for multi-item envelopes).
• GET /sign/{token}/download?version=bundle returns a ZIP containing the signed PDFs, audit log PDF, and Certificate of Completion.
• The completion email attaches all three.

Recipient Flow

For context when supporting end users, here is what a recipient experiences on an AES/QES envelope:

1. Opens the email link, lands on the signing page.
2. Documenso redirects to the TSP for Strong Customer Authentication (first visit only; cached for the session lifetime).
3. Fills fields as normal.
4. Clicks Sign → redirected to the TSP for a second authentication round (issues a per-document Signature Activation Data token).
5. Returns to Documenso; the signing call completes within ~15 seconds.
6. Sees the standard completion screen.

If the TSP returns no eligible credentials for the recipient (e.g. they have not enrolled), they see a blocking page directing them to enrol with the TSP and retry.

Error Codes

CSC-specific error codes surfaced through the standard error channels:

Algorithm Policy

Documenso refuses TSP credentials that do not meet the following minimums, at the OAuth callback boundary and again at sign time:

This is the union of CSC v1.0.4.0 §11.5 requirements and current cryptographic guidance.

Related

• Signature Levels — AES / QES legal framework
• Signing Certificate — overview of all signing transports
• Environment Variables — full env reference
• Enterprise Edition — license requirements