TSA-Konfiguration

Auf einen Blick

NextPDF kontaktiert eine Zeitstempelstelle (TSA) nur, wenn Sie auf PAdES B-T oder höher signieren. Auf B-B gibt es keinen Zeitstempel und keinen Netzwerkaufruf; daher gilt diese Seite nicht für eine B-B-Signatur.

Damit B-T sofort einsatzbereit funktioniert, liefert NextPDF eine eingebaute Standard-TSA aus. Dieser Standard ist eine Bequemlichkeit: Er lässt eine zeitgestempelte Signatur ohne zusätzliche Konfiguration gelingen. Er ist nicht öffentlich vertraut und nicht eIDAS-qualifiziert und eignet sich daher ohne eine bewusste Entscheidung nicht für den Produktiv- oder Compliance-Einsatz. Diese Seite erklärt genau, was der Standard ist, wie Sie NextPDF auf Ihre eigene TSA verweisen, wie Sie die Zeitstempelung abschalten und die zwei Upgrade-Pfade.

Drei Eigenschaften sind unabhängig voneinander und dürfen nicht verwechselt werden:

selbst gehostet — wer den Server betreibt und auf welche Wurzel sein Zertifikat zurückführt;
öffentlich vertraut — ob das Validierungsökosystem, das Ihre vertrauenden Parteien verwenden (ihr Vertrauensspeicher oder ihre Vertrauensliste), dieser Wurzel bereits ohne manuelle Einrichtung vertraut, anstatt zu verlangen, dass eine private Wurzel von Hand installiert wird. Dies betrifft die Vertrauensanker der vertrauenden Partei, nicht ein einzelnes Programm wie die Web-PKI;
eIDAS-qualifiziert — ob der Zeitstempel in der EU qualifizierte Rechtswirkung trägt.

Der ausgelieferte Standard ist nur selbst gehostet. Eine öffentlich vertraute TSA fügt die zweite Eigenschaft hinzu. Eine eIDAS-qualifizierte TSA trägt zusätzlich qualifizierten Rechtsstatus, validiert über die EU-Vertrauenslisten, und kann von einem Drittanbieter-QTSP betrieben werden. Die drei Eigenschaften sind unabhängig — keine impliziert eine andere.

Die eingebaute Standard-TSA

Der Standard-Endpunkt ist https://timestamp.pateon.com.tw, NextPDFs eigener RFC 3161-Zeitstempelserver. Er ist selbst gehostet: Das Zertifikat seiner Zeitstempeleinheit führt auf eine private PATEON-Wurzel zurück, nicht auf ein öffentliches Vertrauensprogramm. Eine vertrauende Partei kann einen vom Standard ausgestellten Zeitstempel daher nicht validieren, sofern sie diese PATEON-Wurzel nicht außerhalb des regulären Wegs installiert und ihr vertraut hat.

Da ein RFC 3161-Token keinen externen Nachweis dafür trägt, dass die behauptete Zeit korrekt ist, beruht das Vertrauen in jeden solchen Zeitstempel vollständig auf dem Vertrauen in die ausstellende TSA (ISO/IEC 18014-2 §7.3). Für den ausgelieferten Standard ist dieser Vertrauensanker privat, weshalb der Standard ein Bequemlichkeits- und Entwicklungsstandard ist, kein Compliance-tauglicher.

Wenn der Standard-Endpunkt verwendet wird und Ihr Framework einen Logger konfiguriert hat, gibt NextPDF beim Prozessstart eine einmalige Warnung aus, die darauf hinweist, dass der Standard nicht öffentlich vertraut ist, und auf diese Konfiguration verweist. Die Warnung ist informativ; das Signieren gelingt weiterhin.

Den Standard überschreiben

Legen Sie den TSA-Endpunkt in der Konfiguration Ihres Framework-Adapters fest. Der genaue Schlüssel unterscheidet sich je Adapter (siehe die Tabelle je Framework): in Laravel ist es die Umgebungsvariable NEXTPDF_TSA_URL, in Symfony der Bundle-Knoten nextpdf.tsa.url und in CodeIgniter der Env-Schlüssel nextPdf.tsa.url.

Die wirksame TSA wird mit dieser Rangfolge aufgelöst, höchste zuerst:

Ein expliziter TsaClient, den Sie selbst konstruieren und injizieren — dieser gewinnt immer.
Die in Ihrem Adapter konfigurierte URL — wird verwendet, wenn Sie keinen Client injizieren.
Der eingebaute Standard — wird nur verwendet, wenn keines der beiden oben Genannten gesetzt ist.

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

Den Zeitstempel deaktivieren

Wenn Sie die TSA-URL Ihres Adapters auf ihrem Standard (unkonfiguriert) belassen, bleibt der eingebaute Standard-Endpunkt erhalten. Diese URL auf einen leeren Wert zu setzen, ist etwas anderes: Es deaktiviert die Zeitstempelung. Ohne konfigurierte TSA schlägt eine auf B-T oder höher angeforderte Signatur fail-closed mit einem Fehler “TSA required” fehl, anstatt stillschweigend auf B-B herunterzufallen.

# 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=

Den messageImprint-Digest-Algorithmus wählen

Eine RFC 3161-Zeitstempelanforderung trägt einen messageImprint — einen Hash der zu zeitstempelnden Daten — und NextPDF verwendet standardmäßig SHA-256 für diesen Imprint. Der Standard ist eine bewusste, interoperable Wahl; Sie müssen ihn selten ändern.

Wenn Sie einen TsaClient von Hand konstruieren, können Sie über den Konstruktorparameter imprintHashAlgorithm einen anderen Imprint-Digest auswählen, der einen TsaImprintHashAlgorithm-Case annimmt: Sha256 (den Standard), Sha384, Sha512, Sha3_256, Sha3_384 oder Sha3_512. Der Standard hält jede ausgesendete Anforderung byte-identisch zu früheren Releases, sodass ein Upgrade nichts ändert, sofern Sie sich nicht ausdrücklich dafür entscheiden.

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

Zwei Einschränkungen sollten Sie kennen, bevor Sie vom Standard abweichen:

Die Ökosystemunterstützung ist heute SHA-256. Ein Nicht-SHA-256-Imprint funktioniert mit dem Core-Token-Verifizierer zusammen, aber das PAdES-B-T-Nachweis-Gate von nextpdf-server und die Validierungs-Digest-Zuordnung von Premium erkennen derzeit nur SHA-256-Imprints. Ein Signatur-Zeitstempel, der mit einem anderen Imprint-Digest erstellt wurde, wird daher auf diesen Oberflächen noch kein B-T nachweisen. Behalten Sie den Standard bei, sofern nicht von jedem Konsumenten Ihrer Zeitstempel bekannt ist, dass er den von Ihnen gewählten Digest akzeptiert.
Vorberechnete Digests müssen zum Algorithmus passen. getDocumentTimestamp() nimmt einen bereits berechneten Dokument-Hash entgegen; es schlägt fail-closed fehl, noch vor jedem Netzwerkaufruf, wenn die Länge dieses Hashes nicht zum konfigurierten Imprint-Algorithmus passt, anstatt eine nicht passende Anforderung zu senden.

Upgrade-Pfade

Für alles, was über Entwicklung oder interne Nutzung hinausgeht, ersetzen Sie den Standard durch eine von zwei stärkeren Optionen.

Öffentlich vertraute TSA

Verweisen Sie die TSA-URL Ihres Adapters auf eine TSA, deren Zertifikat auf eine öffentliche Wurzel zurückführt, der Ihre vertrauenden Parteien bereits vertrauen — zum Beispiel http://timestamp.digicert.com. Es muss keine private Wurzel verteilt werden. Eine produktionstaugliche TSA wird in der Regel Konformität zu einer Zeitstempelrichtlinie wie ETSI EN 319 421 §5 angeben und dem in ETSI EN 319 422 §7 beschriebenen RFC 3161-Protokollprofil folgen; bestätigen Sie dies anhand der veröffentlichten Richtlinie des Betreibers, anstatt es allein aus öffentlichem Vertrauen abzuleiten.

eIDAS-qualifizierte TSA

Für Zeitstempel, die in der Europäischen Union qualifizierte Rechtswirkung tragen müssen, verwenden Sie einen qualifizierten Zeitstempeldienst eines qualifizierten Vertrauensdiensteanbieters (QTSP), der auf einer EU-Vertrauensliste geführt wird. Ein qualifizierter elektronischer Zeitstempel bindet die Zeit so an die Daten, dass eine unbemerkte Änderung mit hinreichender Sicherheit ausgeschlossen wird, beruht auf einer genauen, an die koordinierte Weltzeit (UTC) gekoppelten Zeitquelle und ist durch eine fortgeschrittene elektronische Signatur oder ein fortgeschrittenes elektronisches Siegel des QTSP oder durch ein gleichwertiges Verfahren geschützt (Regulation (EU) 910/2014, Art 42). Dies ist die stärkste Option und die zu wählende, wenn eine Verordnung qualifizierte Zeitstempel ausdrücklich benennt.

Konfiguration je Framework

Der Standard liegt in der Konfiguration jedes Framework-Adapters, nicht in der Core-Engine. Core erfindet niemals eine URL: Ein TsaClient, den Sie von Hand bauen, erfordert einen expliziten Endpunkt und wirft, wenn dieser leer ist. Langzeitstufen (B-LT und B-LTA) verwenden dieselbe konfigurierte TSA wie B-T wieder.

Integration	Wo der Standard liegt	Wie überschreiben
Laravel	`config/nextpdf.php` -> `tsa.url`	`NEXTPDF_TSA_URL` in `.env` setzen
Symfony	Bundle-Konfiguration `nextpdf.tsa.url`	den Knoten setzen oder an eine Env-Variable binden
CodeIgniter	`Config\NextPdf::$tsa['url']`	über den Env-Schlüssel `nextPdf.tsa.url` überschreiben
Plain core	kein impliziter Standard	einen `TsaClient` mit einer expliziten URL + einem gehärteten PSR-18-Client konstruieren

In jedem Adapter baut B-B niemals einen TSA-Client, sodass eine nicht zeitgestempelte Signatur von keiner dieser Konfigurationen betroffen ist.

Vertrauensmodell und Standards

Der Wert eines Zeitstempels ist die Vertrauenskette dahinter, nicht die Bytes selbst. Das RFC 3161-Token behauptet nur eine Zeit; ob diese Behauptung glaubwürdig ist, ist eine Eigenschaft der TSA, die es signiert hat (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Wenn Sie den ausgelieferten Standard behalten, wählen Sie einen selbst gehosteten Vertrauensanker mit privatem Vertrauen — geeignet für Entwicklung und interne Workflows, in denen jede vertrauende Partei die PATEON-Wurzel installieren kann, aber nicht für Dokumente, die von Dritten validiert werden. Für diese wechseln Sie zu einer öffentlich vertrauten TSA oder zu einer eIDAS-qualifizierten TSA, wenn qualifizierte Rechtswirkung erforderlich ist.

Wenn Sie den Standard selbst betreiben, können Sie den öffentlichen Schlüssel der TSA in Ihrem eigenen injizierten PSR-18-Client pinnen. Pinnen Sie den ausgelieferten Standard nicht in gemeinsam genutztem Code: Eine Schlüsselrotation auf Betreiberseite würde dann jeden Standardnutzer auf einen Schlag brechen. Das Vertrauen in einen Zeitstempel ist die Zertifikatskette und die PATEON-Wurzel, nicht ein Transport-Pin.