TSA-configuratie

In een oogopslag

NextPDF benadert een Time Stamp Authority (TSA) alleen wanneer u ondertekent op PAdES B-T of hoger. Op B-B is er geen tijdstempel en geen netwerkaanroep, dus deze pagina is niet van toepassing op een B-B-handtekening.

Om B-T meteen te laten werken, levert NextPDF een ingebouwde standaard-TSA. Die standaard is een gemak: hij laat een getijdstempelde handtekening slagen zonder extra configuratie. Hij is niet publiek vertrouwd en niet eIDAS-gekwalificeerd, dus hij is niet geschikt voor productie- of conformiteitsgebruik zonder een bewuste keuze. Deze pagina legt precies uit wat de standaard is, hoe u NextPDF naar uw eigen TSA laat wijzen, hoe u tijdstempeling uitschakelt, en de twee upgradepaden.

Drie eigenschappen zijn onafhankelijk en mogen niet worden verward:

zelfgehost — wie de server beheert en naar welke root het certificaat ketent;
publiek vertrouwd — of het validatie-ecosysteem dat uw relying parties gebruiken (hun vertrouwensopslag of vertrouwenslijst) die root al vertrouwt zonder handmatige installatie, in plaats van te vereisen dat een private root met de hand wordt geïnstalleerd. Dit gaat over de vertrouwensankers van de relying party, niet over één bepaald programma zoals de Web PKI;
eIDAS-gekwalificeerd — of de tijdstempel gekwalificeerde rechtsgevolgen draagt in de EU.

De meegeleverde standaard is alleen zelfgehost. Een publiek vertrouwde TSA voegt de tweede eigenschap toe. Een eIDAS-gekwalificeerde TSA draagt daarnaast gekwalificeerde juridische status, gevalideerd via de EU Trusted Lists, en mag worden beheerd door een externe QTSP. De drie eigenschappen zijn onafhankelijk — de ene impliceert de andere niet.

De ingebouwde standaard-TSA

Het standaardeindpunt is https://timestamp.pateon.com.tw, NextPDF’s eigen RFC 3161 tijdstempelserver. Hij is zelfgehost: het certificaat van zijn tijdstempeleenheid ketent naar een private PATEON-root, niet naar een publiek vertrouwensprogramma. Een relying party kan daarom een door de standaard uitgegeven tijdstempel niet valideren tenzij ze die PATEON-root buiten de band heeft geïnstalleerd en vertrouwd.

Omdat een RFC 3161-token geen extern bewijs draagt dat de beweerde tijd juist is, rust het vertrouwen in zo’n tijdstempel volledig op het vertrouwen in de uitgevende TSA (ISO/IEC 18014-2 §7.3). Voor de meegeleverde standaard is dat vertrouwensanker privaat, en daarom is de standaard een gemak- en ontwikkelstandaard, geen conformiteitswaardige standaard.

Wanneer het standaardeindpunt in gebruik is en uw framework een logger geconfigureerd heeft, geeft NextPDF bij het starten van het proces een eenmalige waarschuwing dat de standaard niet publiek vertrouwd is en die naar deze configuratie wijst. De waarschuwing is informatief; ondertekenen slaagt nog steeds.

De standaard overschrijven

Stel het TSA-eindpunt in in de configuratie van uw frameworkadapter. De exacte sleutel verschilt per adapter (zie de tabel per framework): in Laravel is het de omgevingsvariabele NEXTPDF_TSA_URL, in Symfony de bundelnode nextpdf.tsa.url, en in CodeIgniter de env-sleutel nextPdf.tsa.url.

De effectieve TSA wordt met deze voorrang bepaald, hoogste eerst:

Een expliciete TsaClient die u zelf construeert en injecteert — deze wint altijd.
De in uw adapter geconfigureerde URL — gebruikt wanneer u geen client injecteert.
De ingebouwde standaard — alleen gebruikt wanneer geen van beide bovenstaande is ingesteld.

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

De tijdstempel uitschakelen

Als u de TSA-url van uw adapter op de standaard (niet-geconfigureerd) laat staan, behoudt u het ingebouwde standaardeindpunt. Die url op een lege waarde zetten is iets anders: het schakelt tijdstempeling uit. Zonder geconfigureerde TSA mislukt een handtekening die op B-T of hoger wordt aangevraagd fail-closed met een “TSA required”-fout, in plaats van stilzwijgend terug te vallen naar 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=

Het messageImprint-digestalgoritme kiezen

Een RFC 3161-tijdstempelverzoek draagt een messageImprint — een hash van de gegevens die worden getijdstempeld — en NextPDF gebruikt standaard SHA-256 voor dat imprint. De standaard is een bewuste, interoperabele keuze; u hoeft die zelden te wijzigen.

Wanneer u met de hand een TsaClient construeert, kunt u een ander imprint-digest kiezen via de constructorparameter imprintHashAlgorithm, die een TsaImprintHashAlgorithm-case aanneemt: Sha256 (de standaard), Sha384, Sha512, Sha3_256, Sha3_384, of Sha3_512. De standaard houdt elk uitgezonden verzoek byte-identiek aan eerdere releases, dus upgraden verandert niets tenzij u er expliciet voor kiest.

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,
);

Twee beperkingen zijn het waard om te kennen voordat u van de standaard afwijkt:

Ecosysteemondersteuning is vandaag SHA-256. Een niet-SHA-256-imprint werkt samen met de Core-tokenverifier, maar de PAdES B-T-bewijspoort van nextpdf-server en de Premium-validatiedigestmap herkennen op dit moment alleen SHA-256-imprints. Een handtekeningtijdstempel die met een ander imprint-digest is gebouwd, bewijst daarom op die oppervlakken nog geen B-T. Behoud de standaard tenzij van elke consument van uw tijdstempels bekend is dat die het digest accepteert dat u kiest.
Vooraf berekende digests moeten overeenkomen met het algoritme. getDocumentTimestamp() neemt een reeds berekende documenthash aan; deze mislukt fail-closed, vóór enige netwerkaanroep, wanneer de lengte van die hash niet overeenkomt met het geconfigureerde imprint-algoritme, in plaats van een niet-overeenkomend verzoek te verzenden.

Upgradepaden

Voor alles buiten ontwikkeling of intern gebruik vervangt u de standaard door een van twee sterkere opties.

Publiek vertrouwde TSA

Laat de TSA-url van uw adapter wijzen naar een TSA waarvan het certificaat ketent naar een publieke root die uw relying parties al vertrouwen — bijvoorbeeld http://timestamp.digicert.com. Er hoeft geen private root te worden gedistribueerd. Een productiewaardige TSA zal doorgaans conformiteit verklaren met een tijdstempelbeleid zoals ETSI EN 319 421 §5 en het RFC 3161-protocolprofiel volgen dat beschreven is in ETSI EN 319 422 §7; bevestig dit aan de hand van het gepubliceerde beleid van de operator in plaats van het uit publiek vertrouwen alleen aan te nemen.

eIDAS-gekwalificeerde TSA

Voor tijdstempels die gekwalificeerde rechtsgevolgen moeten dragen in de Europese Unie, gebruikt u een gekwalificeerde tijdstempeldienst van een gekwalificeerde vertrouwensdienstverlener (QTSP) die op een EU Trusted List staat. Een gekwalificeerde elektronische tijdstempel bindt de tijd aan de gegevens zodat onopgemerkte wijziging redelijkerwijs wordt voorkomen, is gebaseerd op een nauwkeurige tijdbron gekoppeld aan Coordinated Universal Time, en is beschermd door een geavanceerde elektronische handtekening of geavanceerd elektronisch zegel van de QTSP, of door een gelijkwaardige methode (Regulation (EU) 910/2014, Art 42). Dit is de sterkste optie en degene om te kiezen wanneer een verordening expliciet gekwalificeerde tijdstempels noemt.

Configuratie per framework

De standaard leeft in de configuratie van elke frameworkadapter, niet in de core-engine. Core verzint nooit een URL: een TsaClient die u met de hand bouwt vereist een expliciet eindpunt en werpt een fout op als dit leeg is. Langetermijnniveaus (B-LT en B-LTA) hergebruiken dezelfde geconfigureerde TSA als B-T.

Integratie	Waar de standaard leeft	Hoe te overschrijven
Laravel	`config/nextpdf.php` -> `tsa.url`	stel `NEXTPDF_TSA_URL` in in `.env`
Symfony	bundelconfig `nextpdf.tsa.url`	stel de node in, of bind hem aan een env-variabele
CodeIgniter	`Config\NextPdf::$tsa['url']`	overschrijf via de env-sleutel `nextPdf.tsa.url`
Plain core	geen impliciete standaard	construeer een `TsaClient` met een expliciete URL + een geharde PSR-18-client

In elke adapter bouwt B-B nooit een TSA-client, dus een niet-getijdstempelde handtekening wordt niet beïnvloed door enige van deze configuratie.

Vertrouwensmodel en standaarden

De waarde van een tijdstempel is de vertrouwensketen erachter, niet de bytes zelf. Het RFC 3161-token beweert alleen een tijd; of die bewering geloofwaardig is, is een eigenschap van de TSA die het ondertekend heeft (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Wanneer u de meegeleverde standaard behoudt, kiest u een zelfgehost, privaat vertrouwensanker — prima voor ontwikkeling en interne workflows waar elke relying party de PATEON-root kan installeren, maar niet voor documenten die door derden worden gevalideerd. Voor die documenten gaat u over naar een publiek vertrouwde TSA, of naar een eIDAS-gekwalificeerde TSA wanneer gekwalificeerde rechtsgevolgen vereist zijn.

Als u de standaard zelf beheert, kunt u de publieke sleutel van de TSA vastpinnen in uw eigen geïnjecteerde PSR-18-client. Pin de meegeleverde standaard niet in gedeelde code: een sleutelrotatie aan de kant van de operator zou dan elke standaardgebruiker in één keer breken. Het vertrouwen in een tijdstempel is de certificaatketen en de PATEON-root, niet een transportpin.