Enterprise edycja

Contracts — szczegółowa referencja

W skrócie

Moduł Contracts to szew integracyjny Enterprise dla klientów RFC 3161 Time Stamp Authority.

TsaClientInterface deklaruje jedną operację: żądanie zakodowanego w DER tokenu TimeStampToken dla wstępnie obliczonego skrótu dokumentu.
TsaClientAdapter łączy klienta znaczników czasu Core, klasę final, z tym interfejsem bez zmiany zachowania.
Komponenty Enterprise, takie jak LtvManager i DocumentTimestamp, przyjmują ten interfejs, dzięki czemu zachowanie TSA jest wstrzykiwalne i wymienne w testach.
Przez szew przechodzi wyłącznie skrót dokumentu; treść dokumentu nigdy.

Wskazówki dotyczące procesu znajdziesz najpierw na stronie możliwości Contracts.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Interfejs nie wykonuje żadnej pracy i samodzielnie niczego nie bramkuje. Korzystające z niego powierzchnie Enterprise egzekwują własne kody możliwości, takie jak enterprise.compliance.evidence na powierzchni compliance-evidence.

Poziom	Zapewnia
Core	Konkretny `TsaClient` (`final`), który wykonuje żądania RFC 3161
Pro	Brak odpowiednika modułu Contracts
Enterprise	Szew `TsaClientInterface` i most `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Powierzchnia publicznego API

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Deklaruje żądanie tokenu znacznika czasu dla wstępnie obliczonego skrótu dokumentu	`string` — zakodowany w DER TimeStampToken	Zależne od implementacji; interfejs nie deklaruje żadnego wyjątku	Jedyna operacja; źródło dokumentuje wejście jako skrót SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Przechowuje klienta znaczników czasu Core	`TsaClientAdapter`	Nic nie zadeklarowano	`final readonly`; promocja konstruktora
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Przekazuje do `TsaClient::getDocumentTimestamp()` bez zmian	`string` — zakodowany w DER TimeStampToken	`TsaException` od klienta Core, przekazany bez zmian	Nie dodaje zachowania; niczego nie połyka

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
}

Kontrakt zachowania

TsaClientInterface::getDocumentTimestamp(string $documentHash): string zwraca zakodowany w DER token TimeStampToken zgodny z RFC 3161 dla skrótu dokumentu. Reguły obserwowalne z zewnątrz:

Interfejs deklaruje jedną operację; nie waliduje tokenu, nie poręcza za TSA ani nie stwierdza skutku prawnego.
TsaClientAdapter przekazuje wywołanie do klienta znaczników czasu Core bez zmian — bez dodanego zachowania, bez dodatkowych ponowień, bez połkniętych wyjątków, bez dodatkowych gwarancji. Jego jedynym celem jest umożliwienie, aby final klient Core spełniał interfejs skierowany do Enterprise na potrzeby inwersji zależności i testowania.
Przez granicę przechodzi wyłącznie skrót dokumentu; żadna treść dokumentu nie jest przekazywana.
Za adapterem klient Core odrzuca — z TsaException, fail-closed, przed jakąkolwiek aktywnością sieciową — skrót, którego długość nie odpowiada skonfigurowanemu algorytmowi odcisku. W przeciwnym razie błędnie oznaczony odcisk wytworzyłby token, którego żaden zgodny walidator nie może powiązać.
Powierzchnie korzystające: LtvManager przyjmuje opcjonalny TsaClientInterface i wymaga go dla PAdES B-LTA. DocumentTimestamp używa kontraktu do wypełnienia /Contents słownika podpisu /DocTimeStamp. Wykonawca odnawiania archiwum LTV (LtvaRenewalExecutor) podłącza TsaClientAdapter wokół klienta Core przy odnawianiu znaczników czasu dokumentu.

Przypadki brzegowe i tryby awarii

Adapter przekazuje wyjątki z bazowego klienta bez zmian; niepowodzenia TSA muszą być obsłużone w miejscu wywołania.
Skrót musi być surowymi bajtami zgodnie ze skonfigurowanym algorytmem odcisku konkretnego klienta (domyślnie SHA-256, 32 bajty). Skrót zakodowany szesnastkowo ma niewłaściwą długość i jest odrzucany przed wysłaniem jakiegokolwiek żądania.
Zwrócony token to bajty, a nie werdykt; waliduj go tam, gdzie jest to wymagane.
Własna implementacja jest właścicielem swojej własnej powierzchni awarii. Kontrakt ustala jedynie kształt zwracanej wartości: zakodowany w DER TimeStampToken.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnych operacji kryptograficznych. Wybór algorytmu oraz zachowanie w trybie FIPS są zarządzane przez konkretnego klienta TSA i moduł Security. Zobacz pełną dokumentację referencyjną FIPS 140.

Zgodność

Zachowanie	Odniesienie
Żądanie i powiązanie tokenu znacznika czasu	IETF RFC 3161 §2
TimeStampReq niesie MessageImprint: identyfikator algorytmu skrótu oraz skrót danych do oznaczenia znacznikiem czasu	IETF RFC 3161 §2.4.1
messageImprint tokenu musi być równy wartości żądania, przy czym rozmiar skrótu odpowiada zidentyfikowanemu algorytmowi	IETF RFC 3161 §2.4.2

Kontrakt jest ukształtowany wokół RFC 3161; właściwe żądanie tokenu oraz ewentualna weryfikacja są wykonywane przez konkretnego klienta i powierzchnie Evidence/Signature. Interfejs nie formułuje żadnego twierdzenia o zgodności ani atestacji. NextPDF nie formułuje żadnego twierdzenia o certyfikacji.

Uwagi programistyczne

Oba typy noszą @since 3.0.0; ta dokumentacja opisuje powierzchnię w postaci dostarczonej w nextpdf/enterprise 3.1.0.
Wstrzykuj TsaClientInterface w komponentach, które potrzebują znaczników czasu; podłącz TsaClientAdapter lub własną implementację w korzeniu kompozycji. W testach jednostkowych podstaw atrapę testową zamiast działającego TSA.
Operator jest właścicielem konkretnego klienta TSA stojącego za adapterem: rezydencja, granica zaufania punktu końcowego TSA oraz weryfikacja łańcucha certyfikatów dotyczą tego klienta, a nie tego interfejsu.
Do tej powierzchni kontraktu nie ma zastosowania żadne ograniczenie kontroli eksportu. Uzyskanie tokenu znacznika czasu wspiera procesy audytu i walidacji długoterminowej; nie jest atestacją prawną ani certyfikacją. Niniejsza dokumentacja nie stanowi opinii prawnej.
Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.