Enterprise editie

Contracts — Diepe referentie

In een oogopslag

De Contracts-module is de Enterprise-integratienaad voor RFC 3161 Time Stamp Authority-clients.

TsaClientInterface declareert één bewerking: een DER-gecodeerde TimeStampToken aanvragen voor een vooraf berekende document-digest.
TsaClientAdapter overbrugt de Core-tijdstempelclient, een final class, naar die interface zonder het gedrag te wijzigen.
Enterprise-componenten zoals LtvManager en DocumentTimestamp accepteren de interface, zodat TSA-gedrag injecteerbaar en vervangbaar is in tests.
Alleen een documenthash passeert de naad; documentinhoud nooit.

Lees voor workflowbegeleiding eerst de Contracts-capaciteitspagina.

Beschikbaarheid en licentiëring

Deze capaciteit wordt meegeleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder die entitlement laadt de classes van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

De interface voert geen werk uit en schermt op zichzelf niets af. Consumerende Enterprise-oppervlakken handhaven hun eigen capability-codes, zoals enterprise.compliance.evidence op het compliance-evidence-oppervlak.

Tier	Levert
Core	Concrete `TsaClient` (`final`) die RFC 3161-aanvragen uitvoert
Pro	Geen equivalent in de Contracts-module
Enterprise	`TsaClientInterface`-naad en de `TsaClientAdapter`-brug

composer require nextpdf/enterprise:^3

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Declareert een aanvraag voor een tijdstempeltoken voor een vooraf berekende document-digest	`string` — DER-gecodeerde TimeStampToken	Implementatieafhankelijk; de interface declareert geen exceptie	Enige bewerking; de bron documenteert een SHA-256-digest als invoer
`TsaClientAdapter::__construct()`	`TsaClient $client`	Slaat de Core-tijdstempelclient op	`TsaClientAdapter`	Niets gedeclareerd	`final readonly`; constructor promotion
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Stuurt ongewijzigd door naar `TsaClient::getDocumentTimestamp()`	`string` — DER-gecodeerde TimeStampToken	`TsaException` van de Core-client, ongewijzigd doorgestuurd	Voegt geen gedrag toe; slikt niets in

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
}

Gedragscontract

TsaClientInterface::getDocumentTimestamp(string $documentHash): string retourneert een DER-gecodeerde RFC 3161 TimeStampToken voor een documenthash. Extern waarneembare regels:

De interface declareert één bewerking; deze valideert het token niet, staat niet garant voor de TSA en beweert geen juridisch effect.
TsaClientAdapter stuurt de aanroep ongewijzigd door naar de Core-tijdstempelclient — geen toegevoegd gedrag, geen extra retries, geen ingeslikte excepties, geen extra garanties. Het enige doel is om een final Core-client te laten voldoen aan een Enterprise-gerichte interface voor dependency inversion en testen.
Alleen een documenthash passeert de grens; er wordt geen documentinhoud doorgegeven.
Achter de adapter verwerpt de Core-client een digest waarvan de lengte niet overeenkomt met zijn geconfigureerde imprint-algoritme met TsaException, fail-closed, vóór enige netwerkactiviteit. Een verkeerd gelabelde imprint zou anders een token opleveren dat geen enkele conforme validator kan binden.
Consumerende oppervlakken: LtvManager accepteert een optionele TsaClientInterface en vereist er een voor PAdES B-LTA. DocumentTimestamp gebruikt het contract om de /Contents van een /DocTimeStamp-signature-dictionary te vullen. De LTV-archief-vernieuwingsexecutor (LtvaRenewalExecutor) bedraadt een TsaClientAdapter rond de Core-client bij het vernieuwen van documenttijdstempels.

Randgevallen en faalmodi

De adapter stuurt excepties van de onderliggende client ongewijzigd door; TSA-fouten moeten op de aanroepplaats worden afgehandeld.
De digest moet ruwe binaire data zijn onder het geconfigureerde imprint-algoritme van de concrete client (standaard SHA-256, 32 bytes). Een hex-gecodeerde digest heeft de verkeerde lengte en wordt verworpen voordat er een aanvraag wordt verzonden.
Een geretourneerd token is bytes, geen oordeel; valideer het waar dat vereist is.
Een aangepaste implementatie is eigenaar van zijn eigen faaloppervlak. Het contract legt alleen de retourvorm vast: een DER-gecodeerde TimeStampToken.

FIPS-modusgedrag

Deze module voert geen cryptografische bewerkingen uit. De algoritmekeuze en het FIPS-modusgedrag worden beheerd door de concrete TSA-client en de Security-module. Zie de FIPS 140 diepe referentie.

Conformiteit

Gedrag	Referentie
Aanvraag en binding van het tijdstempeltoken	IETF RFC 3161 §2
Een TimeStampReq draagt een MessageImprint: een hash-algoritme-identifier en de hash van de te tijdstempelen data	IETF RFC 3161 §2.4.1
De messageImprint van het token moet gelijk zijn aan de waarde van de aanvraag, waarbij de hashgrootte overeenkomt met het geïdentificeerde algoritme	IETF RFC 3161 §2.4.2

Het contract is vormgegeven rond RFC 3161; de werkelijke tokenaanvraag en eventuele verificatie worden uitgevoerd door de concrete client en de Evidence/Signature-oppervlakken. De interface doet geen conformiteits- of attestatieclaim. NextPDF doet geen certificeringsclaim.

Ontwikkelnotities

Beide types dragen @since 3.0.0; deze referentie documenteert het oppervlak zoals meegeleverd in nextpdf/enterprise 3.1.0.
Injecteer TsaClientInterface in componenten die tijdstempels nodig hebben; bedraad TsaClientAdapter, of een aangepaste implementatie, in de composition root. Vervang in unittests een test double in plaats van een live TSA.
De operator is eigenaar van de concrete TSA-client achter de adapter: gegevenslocatie, de vertrouwensgrens van het TSA-endpoint en de verificatie van de certificaatketen gelden voor die client, niet voor deze interface.
Er geldt geen exportcontrolebeperking voor dit contractoppervlak. Het verkrijgen van een tijdstempeltoken ondersteunt audit- en langetermijnvalidatieworkflows; het is geen juridische attestatie of certificering. Deze referentie is geen juridisch advies.
Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.