TSA configuration

At a glance

NextPDF contacts a Time Stamp Authority (TSA) only when you sign at PAdES B-T or above. At B-B there is no timestamp and no network call, so this page does not apply to a B-B signature.

To make B-T work out of the box, NextPDF ships a built-in default TSA. That default is a convenience: it lets a timestamped signature succeed with no extra configuration. It is not publicly-trusted and not eIDAS-qualified, so it is not appropriate for production or compliance use without a deliberate choice. This page explains exactly what the default is, how to point NextPDF at your own TSA, how to turn timestamping off, and the two upgrade paths.

Three properties are independent and must not be confused:

• self-hosted — who operates the server and which root its certificate chains to;
• publicly-trusted — whether the validation ecosystem your relying parties use (their trust store or trust list) already trusts that root with no manual setup, rather than requiring a private root to be installed by hand. This is about the relying party’s trust anchors, not any one program such as the Web PKI;
• eIDAS-qualified — whether the timestamp carries qualified legal effect in the EU.

The shipped default is self-hosted only. A publicly-trusted TSA adds the second property. An eIDAS-qualified TSA additionally carries qualified legal status, validated through the EU Trusted Lists, and may be operated by a third-party QTSP. The three properties are independent — one does not imply another.

The built-in default TSA

The default endpoint is https://timestamp.pateon.com.tw, NextPDF’s own RFC 3161 time-stamping server. It is self-hosted: its time-stamping unit certificate chains to a private PATEON root, not to a public trust program. A relying party therefore cannot validate a timestamp issued by the default unless it has installed and trusted that PATEON root out of band.

Because an RFC 3161 token carries no external evidence that the asserted time is correct, the trust in any such timestamp rests entirely on trusting the issuing TSA (ISO/IEC 18014-2 §7.3). For the shipped default that trust anchor is private, which is why the default is a convenience and development default, not a compliance-grade one.

When the default endpoint is in use and your framework has a logger configured, NextPDF emits a one-time warning at process start noting that the default is not publicly-trusted and pointing at this configuration. The warning is informational; signing still succeeds.

Overriding the default

Set the TSA endpoint in your framework adapter’s configuration. The exact key differs per adapter (see the per-framework table): in Laravel it is the NEXTPDF_TSA_URL environment variable, in Symfony the nextpdf.tsa.url bundle node, and in CodeIgniter the nextPdf.tsa.url env key.

The effective TSA is resolved with this precedence, highest first:

1. An explicit TsaClient you construct and inject yourself — this always wins.
2. The URL configured in your adapter — used when you do not inject a client.
3. The built-in default — used only when neither of the above is set.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Disabling the timestamp

Leaving your adapter’s TSA url at its default (unconfigured) keeps the built-in default endpoint. Setting that url to an empty value is different: it disables timestamping. With no TSA configured, a signature requested at B-T or above fails closed with a “TSA required” error rather than silently dropping to B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Choosing the messageImprint digest algorithm

An RFC 3161 timestamp request carries a messageImprint — a hash of the data being timestamped — and NextPDF uses SHA-256 for that imprint by default. The default is a deliberate, interoperable choice; you rarely need to change it.

When you construct a TsaClient by hand you can select a different imprint digest through the imprintHashAlgorithm constructor parameter, which takes a TsaImprintHashAlgorithm case: Sha256 (the default), Sha384, Sha512, Sha3_256, Sha3_384, or Sha3_512. The default keeps every emitted request byte-identical to earlier releases, so upgrading changes nothing unless you opt in.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Two constraints are worth knowing before you move off the default:

• Ecosystem support is SHA-256 today. A non-SHA-256 imprint interoperates with the Core token verifier, but the nextpdf-server PAdES B-T proof gate and the Premium validation digest map recognize SHA-256 imprints only at present. A signature timestamp built with a different imprint digest will therefore not prove B-T on those surfaces yet. Keep the default unless every consumer of your timestamps is known to accept the digest you choose.
• Pre-computed digests must match the algorithm. getDocumentTimestamp() takes an already-computed document hash; it fails closed, before any network call, when that hash’s length does not match the configured imprint algorithm, rather than sending a mismatched request.

Upgrade paths

For anything beyond development or internal use, replace the default with one of two stronger options.

Publicly-trusted TSA

Point your adapter’s TSA url at a TSA whose certificate chains to a public root your relying parties already trust — for example http://timestamp.digicert.com. No private root has to be distributed. A production-grade TSA will typically state conformance to a time-stamping policy such as ETSI EN 319 421 §5 and follow the RFC 3161 protocol profile described in ETSI EN 319 422 §7; confirm this against the operator’s published policy rather than assuming it from public trust alone.

eIDAS-qualified TSA

For timestamps that must carry qualified legal effect in the European Union, use a qualified time-stamping service from a qualified trust service provider (QTSP) listed on an EU Trusted List. A qualified electronic time stamp binds the time to the data so as to reasonably prevent undetectable alteration, is based on an accurate time source linked to Coordinated Universal Time, and is protected by an advanced electronic signature or advanced electronic seal of the QTSP, or by an equivalent method (Regulation (EU) 910/2014, Art 42). This is the strongest option and the one to choose when a regulation names qualified timestamps explicitly.

Per-framework configuration

The default lives in each framework adapter’s configuration, not in the core engine. Core never invents a URL: a TsaClient you build by hand requires an explicit endpoint and throws if it is empty. Long-term levels (B-LT and B-LTA) reuse the same configured TSA as B-T.

Integration	Where the default lives	How to override
Laravel	config/nextpdf.php -> tsa.url	set NEXTPDF_TSA_URL in .env
Symfony	bundle config nextpdf.tsa.url	set the node, or bind it to an env var
CodeIgniter	Config\NextPdf::$tsa['url']	override via the nextPdf.tsa.url env key
Plain core	no implicit default	construct a TsaClient with an explicit URL + a hardened PSR-18 client

In every adapter, B-B never builds a TSA client, so a non-timestamped signature is unaffected by any of this configuration.

Trust model and standards

A timestamp’s value is the trust chain behind it, not the bytes themselves. The RFC 3161 token only asserts a time; whether that assertion is believable is a property of the TSA that signed it (RFC 3161 §2; ISO/IEC 18014-2 §7.3). When you keep the shipped default you are choosing a self-hosted, private-trust anchor — fine for development and internal workflows where every relying party can install the PATEON root, but not for documents validated by third parties. For those, move to a publicly-trusted TSA, or to an eIDAS-qualified TSA when qualified legal effect is required.

If you operate the default yourself, you can pin the TSA’s public key in your own injected PSR-18 client. Do not pin the shipped default in shared code: a key rotation on the operator’s side would then break every default user at once. The trust in a timestamp is the certificate chain and the PATEON root, not a transport pin.

See also

• Security / Signing: CMS, RFC 3161 timestamp, LTV, trust
• Sign a PDF at PAdES B-B and B-T
• PAdES specification notes