Enterprise Edition

Contracts — Ausführliche Referenz

Auf einen Blick

Das Contracts-Modul ist die Enterprise-Integrationsnahtstelle für RFC-3161-Time-Stamp-Authority-Clients.

TsaClientInterface deklariert eine Operation: die Anforderung eines DER-kodierten TimeStampToken für einen vorab berechneten Dokument-Digest.
TsaClientAdapter überbrückt den Core-Timestamp-Client, eine final-Klasse, auf diese Schnittstelle, ohne das Verhalten zu ändern.
Enterprise-Komponenten wie LtvManager und DocumentTimestamp akzeptieren die Schnittstelle, sodass das TSA-Verhalten injizierbar und in Tests austauschbar ist.
Nur ein Dokument-Hash überquert die Nahtstelle; Dokumentinhalt niemals.

Lesen Sie für eine Anleitung zum Arbeitsablauf zuerst die Contracts-Funktionsseite.

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und wird mit einem Lizenz-Envelope der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erhalten.

Die Schnittstelle führt keine Arbeit aus und schützt für sich genommen nichts. Konsumierende Enterprise-Oberflächen erzwingen ihre eigenen Capability-Codes, etwa enterprise.compliance.evidence auf der Compliance-Evidence-Oberfläche.

Stufe	Stellt bereit
Core	Konkreter `TsaClient` (`final`), der RFC-3161-Anforderungen ausführt
Pro	Kein Contracts-Modul-Äquivalent
Enterprise	`TsaClientInterface`-Nahtstelle und die `TsaClientAdapter`-Brücke

composer require nextpdf/enterprise:^3

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Deklariert eine Timestamp-Token-Anforderung für einen vorab berechneten Dokument-Digest	`string` — DER-kodiertes TimeStampToken	Implementierungsdefiniert; die Schnittstelle deklariert keine Ausnahme	Einzige Operation; die Quelle dokumentiert eine SHA-256-Digest-Eingabe
`TsaClientAdapter::__construct()`	`TsaClient $client`	Speichert den Core-Timestamp-Client	`TsaClientAdapter`	Nichts deklariert	`final readonly`; Constructor-Promotion
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Leitet unverändert an `TsaClient::getDocumentTimestamp()` weiter	`string` — DER-kodiertes TimeStampToken	`TsaException` vom Core-Client, unverändert weitergeleitet	Fügt kein Verhalten hinzu; verschluckt nichts

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

Verhaltensvertrag

TsaClientInterface::getDocumentTimestamp(string $documentHash): string gibt ein DER-kodiertes RFC-3161-TimeStampToken für einen Dokument-Hash zurück. Extern beobachtbare Regeln:

Die Schnittstelle deklariert eine Operation; sie validiert das Token nicht, bürgt nicht für die TSA und macht keine Aussage über eine Rechtswirkung.
TsaClientAdapter leitet den Aufruf unverändert an den Core-Timestamp-Client weiter — kein zusätzliches Verhalten, keine zusätzlichen Wiederholungen, keine verschluckten Ausnahmen, keine zusätzlichen Garantien. Sein einziger Zweck besteht darin, einem final-Core-Client zu ermöglichen, eine Enterprise-orientierte Schnittstelle für Dependency Inversion und Tests zu erfüllen.
Nur ein Dokument-Hash überquert die Grenze; kein Dokumentinhalt wird übergeben.
Hinter dem Adapter weist der Core-Client einen Digest, dessen Länge nicht zu seinem konfigurierten Imprint-Algorithmus passt, mit TsaException zurück — fail-closed, vor jeder Netzwerkaktivität. Ein falsch gekennzeichneter Imprint würde andernfalls ein Token erzeugen, das kein konformer Validator binden kann.
Konsumierende Oberflächen: LtvManager akzeptiert ein optionales TsaClientInterface und benötigt eines für PAdES B-LTA. DocumentTimestamp verwendet den Vertrag, um die /Contents eines /DocTimeStamp-Signatur-Dictionarys zu füllen. Der LTV-Archiv-Erneuerungs-Executor (LtvaRenewalExecutor) verdrahtet beim Erneuern von Dokument-Timestamps einen TsaClientAdapter um den Core-Client.

Randfälle & Fehlermodi

Der Adapter leitet Ausnahmen des zugrunde liegenden Clients unverändert weiter; TSA-Fehler müssen an der Aufrufstelle behandelt werden.
Der Digest muss unter dem konfigurierten Imprint-Algorithmus des konkreten Clients rohes Binär sein (Standard SHA-256, 32 Bytes). Ein hex-kodierter Digest hat die falsche Länge und wird abgewiesen, bevor eine Anforderung gesendet wird.
Ein zurückgegebenes Token besteht aus Bytes, nicht aus einem Urteil; validieren Sie es, wo es erforderlich ist.
Eine benutzerdefinierte Implementierung besitzt ihre eigene Fehleroberfläche. Der Vertrag legt nur die Rückgabeform fest: ein DER-kodiertes TimeStampToken.

FIPS-Modus-Verhalten

Dieses Modul führt keine kryptografischen Operationen aus. Die Algorithmuswahl und das FIPS-Modus-Verhalten werden vom konkreten TSA-Client und vom Security-Modul bestimmt. Siehe die ausführliche FIPS-140-Referenz.

Konformität

Verhalten	Referenz
Timestamp-Token-Anforderung und -Bindung	IETF RFC 3161 §2
Ein TimeStampReq trägt einen MessageImprint: einen Hash-Algorithmus-Identifier und den Hash der zu zeitstempelnden Daten	IETF RFC 3161 §2.4.1
Der messageImprint des Tokens muss dem Wert der Anforderung entsprechen, wobei die Hash-Größe zum identifizierten Algorithmus passt	IETF RFC 3161 §2.4.2

Der Vertrag ist um RFC 3161 herum gestaltet; die eigentliche Token-Anforderung und jede Verifizierung werden vom konkreten Client und den Evidence-/Signature-Oberflächen ausgeführt. Die Schnittstelle erhebt keinen Konformitäts- oder Attestierungsanspruch. NextPDF erhebt keinen Zertifizierungsanspruch.

Entwicklungshinweise

Beide Typen tragen @since 3.0.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/enterprise 3.1.0 ausgeliefert wird.
Injizieren Sie TsaClientInterface in Komponenten, die Timestamps benötigen; verdrahten Sie TsaClientAdapter oder eine benutzerdefinierte Implementierung am Composition Root. Setzen Sie in Unit-Tests ein Test-Double anstelle einer Live-TSA ein.
Der Betreiber besitzt den konkreten TSA-Client hinter dem Adapter: Residenz, die Vertrauensgrenze des TSA-Endpunkts und die Zertifikatsketten-Verifizierung gelten für diesen Client, nicht für diese Schnittstelle.
Für diese Vertragsoberfläche gilt keine Exportkontrollbeschränkung. Das Erlangen eines Timestamp-Tokens unterstützt Audit- und Langzeitvalidierungs-Arbeitsabläufe; es ist keine rechtliche Attestierung und keine Zertifizierung. Diese Referenz ist kein Rechtsgutachten.
Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.