Enterprise edizione

Contracts — Riferimento approfondito

In sintesi

Il modulo Contracts è il punto di giunzione (seam) di integrazione Enterprise per i client di Time Stamp Authority conformi a RFC 3161.

TsaClientInterface dichiara una sola operazione: richiedere un TimeStampToken codificato in DER per un digest di documento pre-calcolato.
TsaClientAdapter collega il client di marca temporale di Core, una classe final, a tale interfaccia senza modificarne il comportamento.
Componenti Enterprise come LtvManager e DocumentTimestamp accettano l’interfaccia, così il comportamento della TSA è iniettabile e sostituibile nei test.
Solo un hash di documento attraversa il seam; il contenuto del documento non lo fa mai.

Per indicazioni sul flusso di lavoro, leggere prima la pagina della funzionalità Contracts.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

L’interfaccia non esegue alcun lavoro e non applica alcun gate da sola. Le superfici Enterprise che la consumano applicano i propri codici di funzionalità, come enterprise.compliance.evidence sulla superficie compliance-evidence.

Tier	Fornisce
Core	`TsaClient` concreto (`final`) che esegue le richieste RFC 3161
Pro	Nessun equivalente del modulo Contracts
Enterprise	Il seam `TsaClientInterface` e il bridge `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Dichiara una richiesta di timestamp-token per un digest di documento pre-calcolato	`string` — TimeStampToken codificato in DER	Definito dall’implementazione; l’interfaccia non dichiara alcuna eccezione	Unica operazione; la sorgente documenta un input digest SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Memorizza il client di marca temporale di Core	`TsaClientAdapter`	Nulla dichiarato	`final readonly`; promozione del costruttore
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Inoltra a `TsaClient::getDocumentTimestamp()` invariato	`string` — TimeStampToken codificato in DER	`TsaException` dal client di Core, inoltrata invariata	Non aggiunge comportamento; non sopprime nulla

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
}

Contratto di comportamento

TsaClientInterface::getDocumentTimestamp(string $documentHash): string restituisce un TimeStampToken RFC 3161 codificato in DER per un hash di documento. Regole osservabili dall’esterno:

L’interfaccia dichiara una sola operazione; non convalida il token, non garantisce per la TSA e non asserisce alcun effetto legale.
TsaClientAdapter inoltra la chiamata al client di marca temporale di Core invariata — nessun comportamento aggiunto, nessun retry aggiunto, nessuna eccezione soppressa, nessuna garanzia aggiuntiva. Il suo unico scopo è consentire a un client final di Core di soddisfare un’interfaccia rivolta a Enterprise per l’inversione delle dipendenze e per il testing.
Solo un hash di documento attraversa il confine; nessun contenuto del documento viene passato.
Dietro l’adapter, il client di Core rifiuta un digest la cui lunghezza non corrisponde all’algoritmo di imprint configurato con TsaException, fail-closed, prima di qualsiasi attività di rete. Un imprint etichettato in modo errato produrrebbe altrimenti un token che nessun validatore conforme può vincolare.
Superfici che la consumano: LtvManager accetta un TsaClientInterface opzionale e ne richiede uno per PAdES B-LTA. DocumentTimestamp usa il contratto per riempire il /Contents di un dizionario di firma /DocTimeStamp. L’executor di rinnovo dell’archivio LTV (LtvaRenewalExecutor) collega un TsaClientAdapter attorno al client di Core quando rinnova i timestamp di documento.

Casi limite e modalità di errore

L’adapter inoltra invariate le eccezioni del client sottostante; gli errori della TSA devono essere gestiti nel punto di chiamata.
Il digest deve essere binario grezzo secondo l’algoritmo di imprint configurato del client concreto (default SHA-256, 32 byte). Un digest codificato in esadecimale ha la lunghezza errata e viene rifiutato prima che venga inviata qualsiasi richiesta.
Un token restituito è costituito da byte, non da un verdetto; convalidarlo ove richiesto.
Un’implementazione personalizzata detiene la propria superficie di errore. Il contratto fissa solo la forma del valore restituito: un TimeStampToken codificato in DER.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna operazione crittografica. La scelta dell’algoritmo e il comportamento in modalità FIPS sono governati dal client TSA concreto e dal modulo Security. Vedere il riferimento approfondito su FIPS 140.

Conformità

Comportamento	Riferimento
Richiesta e binding del token di marca temporale	IETF RFC 3161 §2
Una TimeStampReq porta una MessageImprint: un identificatore dell’algoritmo di hash e l’hash dei dati da marcare temporalmente	IETF RFC 3161 §2.4.1
Il messageImprint del token deve essere uguale al valore della richiesta, con la dimensione dell’hash corrispondente all’algoritmo identificato	IETF RFC 3161 §2.4.2

Il contratto è modellato attorno a RFC 3161; la richiesta effettiva del token e qualsiasi verifica sono eseguite dal client concreto e dalle superfici Evidence/Signature. L’interfaccia non avanza alcuna rivendicazione di conformità o attestazione. NextPDF non avanza alcuna rivendicazione di certificazione.

Note di sviluppo

Entrambi i tipi riportano @since 3.0.0; questo riferimento documenta la superficie così come inclusa in nextpdf/enterprise 3.1.0.
Iniettare TsaClientInterface nei componenti che necessitano di timestamp; collegare TsaClientAdapter, o un’implementazione personalizzata, nella composition root. Sostituire un test double nei test unitari anziché una TSA reale.
L’operatore detiene il client TSA concreto dietro l’adapter: la residenza, il confine di fiducia dell’endpoint TSA e la verifica della catena di certificati si applicano a quel client, non a questa interfaccia.
Nessuna restrizione di controllo delle esportazioni si applica a questa superficie di contratto. Ottenere un token di marca temporale supporta i flussi di lavoro di audit e di convalida a lungo termine; non è un’attestazione legale né una certificazione. Questo riferimento non è un parere legale.
I dettagli del meccanismo interno restano nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismo, nomi di file di runbook e prefissi di ticket sono fuori ambito.