Konfiguracja TSA

W skrócie

NextPDF kontaktuje się z urzędem znakowania czasem (Time Stamp Authority, TSA) tylko wtedy, gdy podpisujesz na poziomie PAdES B-T lub wyższym. Na poziomie B-B nie ma znacznika czasu ani wywołania sieciowego, dlatego ta strona nie dotyczy podpisu B-B.

Aby poziom B-T działał od razu po instalacji, NextPDF dostarcza wbudowany domyślny urząd TSA. Ten domyślny urząd jest udogodnieniem: pozwala podpisowi ze znacznikiem czasu zakończyć się powodzeniem bez dodatkowej konfiguracji. Nie jest on objęty publicznym zaufaniem i nie jest kwalifikowany według eIDAS, więc nie nadaje się do zastosowań produkcyjnych ani związanych ze zgodnością bez świadomego wyboru. Ta strona wyjaśnia dokładnie, czym jest domyślny urząd, jak wskazać NextPDF własny urząd TSA, jak wyłączyć znakowanie czasem oraz jakie są dwie ścieżki przejścia na wyższy poziom.

Trzy właściwości są niezależne i nie wolno ich mylić:

hostowany samodzielnie — kto obsługuje serwer i do jakiego korzenia łączy się łańcuch jego certyfikatu;
objęty publicznym zaufaniem — czy ekosystem walidacji używany przez strony ufające (ich magazyn zaufania lub lista zaufania) już ufa temu korzeniowi bez ręcznej konfiguracji, zamiast wymagać ręcznego zainstalowania prywatnego korzenia. Dotyczy to kotwic zaufania strony ufającej, a nie żadnego pojedynczego programu, takiego jak Web PKI;
kwalifikowany według eIDAS — czy znacznik czasu niesie kwalifikowany skutek prawny w UE.

Dostarczony domyślny urząd jest wyłącznie hostowany samodzielnie. Urząd TSA objęty publicznym zaufaniem dodaje drugą właściwość. Urząd TSA kwalifikowany według eIDAS dodatkowo niesie kwalifikowany status prawny, walidowany za pośrednictwem unijnych list zaufanych (EU Trusted Lists), i może być obsługiwany przez zewnętrznego QTSP. Te trzy właściwości są niezależne — jedna nie pociąga za sobą drugiej.

Wbudowany domyślny urząd TSA

Domyślny punkt końcowy to https://timestamp.pateon.com.tw, należący do NextPDF serwer znakowania czasem zgodny z RFC 3161. Jest hostowany samodzielnie: łańcuch certyfikatu jego jednostki znakowania czasem prowadzi do prywatnego korzenia PATEON, a nie do publicznego programu zaufania. Strona ufająca nie może zatem zwalidować znacznika czasu wystawionego przez domyślny urząd, dopóki nie zainstaluje i nie obdarzy zaufaniem tego korzenia PATEON poza pasmem.

Ponieważ token RFC 3161 nie niesie żadnego zewnętrznego dowodu na to, że deklarowany czas jest poprawny, zaufanie do każdego takiego znacznika czasu opiera się w całości na zaufaniu do wystawiającego urzędu TSA (ISO/IEC 18014-2 §7.3). Dla dostarczonego domyślnego urzędu ta kotwica zaufania jest prywatna, dlatego domyślny urząd jest urzędem dla wygody i pracy deweloperskiej, a nie urzędem klasy zgodności.

Gdy używany jest domyślny punkt końcowy, a Twój framework ma skonfigurowany rejestrator, NextPDF emituje jednorazowe ostrzeżenie przy starcie procesu, zaznaczając, że domyślny urząd nie jest objęty publicznym zaufaniem, i wskazując tę konfigurację. Ostrzeżenie ma charakter informacyjny; podpisywanie i tak kończy się powodzeniem.

Nadpisywanie domyślnego urzędu

Ustaw punkt końcowy TSA w konfiguracji adaptera swojego frameworka. Dokładny klucz różni się w zależności od adaptera (zobacz tabelę dla poszczególnych frameworków): w Laravel jest to zmienna środowiskowa NEXTPDF_TSA_URL, w Symfony węzeł bundle nextpdf.tsa.url, a w CodeIgniter klucz środowiskowy nextPdf.tsa.url.

Efektywny urząd TSA jest rozstrzygany według tego pierwszeństwa, od najwyższego:

Jawny TsaClient, który sam konstruujesz i wstrzykujesz — zawsze wygrywa.
URL skonfigurowany w Twoim adapterze — używany, gdy nie wstrzykujesz klienta.
Wbudowany domyślny urząd — używany tylko wtedy, gdy żaden z powyższych nie jest ustawiony.

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

Wyłączanie znacznika czasu

Pozostawienie url urzędu TSA w adapterze na wartości domyślnej (nieskonfigurowanej) zachowuje wbudowany domyślny punkt końcowy. Ustawienie tego url na pustą wartość jest czymś innym: wyłącza znakowanie czasem. Bez skonfigurowanego urzędu TSA podpis żądany na poziomie B-T lub wyższym kończy się niepowodzeniem fail-closed z błędem „TSA required”, zamiast po cichu obniżać poziom do B-B.

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

Wybór algorytmu skrótu messageImprint

Żądanie znacznika czasu RFC 3161 niesie messageImprint — skrót danych poddawanych znakowaniu czasem — a NextPDF domyślnie używa dla tego odcisku SHA-256. Domyślny wybór jest celowy i interoperacyjny; rzadko trzeba go zmieniać.

Gdy konstruujesz TsaClient ręcznie, możesz wybrać inny skrót odcisku za pomocą parametru konstruktora imprintHashAlgorithm, który przyjmuje przypadek TsaImprintHashAlgorithm: Sha256 (wartość domyślna), Sha384, Sha512, Sha3_256, Sha3_384 lub Sha3_512. Wartość domyślna utrzymuje każde emitowane żądanie bajt w bajt identyczne z wcześniejszymi wydaniami, więc aktualizacja niczego nie zmienia, dopóki świadomie się na to nie zdecydujesz.

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

Zanim odejdziesz od wartości domyślnej, warto znać dwa ograniczenia:

Wsparcie ekosystemu obejmuje dziś SHA-256. Odcisk inny niż SHA-256 współdziała z weryfikatorem tokenów Core, ale bramka dowodu PAdES B-T w nextpdf-server oraz mapa skrótów walidacji w Premium rozpoznają obecnie wyłącznie odciski SHA-256. Znacznik czasu podpisu zbudowany z innym skrótem odcisku nie udowodni zatem jeszcze B-T na tych powierzchniach. Zachowaj wartość domyślną, chyba że wiadomo, iż każdy odbiorca Twoich znaczników czasu akceptuje wybrany przez Ciebie skrót.
Wstępnie obliczone skróty muszą pasować do algorytmu. getDocumentTimestamp() przyjmuje już obliczony skrót dokumentu; kończy się niepowodzeniem fail-closed, przed jakimkolwiek wywołaniem sieciowym, gdy długość tego skrótu nie odpowiada skonfigurowanemu algorytmowi odcisku, zamiast wysyłać niedopasowane żądanie.

Ścieżki przejścia na wyższy poziom

W przypadku czegokolwiek poza pracą deweloperską lub użyciem wewnętrznym zastąp domyślny urząd jedną z dwóch silniejszych opcji.

Urząd TSA objęty publicznym zaufaniem

Wskaż url urzędu TSA w swoim adapterze na urząd TSA, którego certyfikat łączy się w łańcuchu z publicznym korzeniem, któremu Twoje strony ufające już ufają — na przykład http://timestamp.digicert.com. Nie trzeba rozprowadzać żadnego prywatnego korzenia. Urząd TSA klasy produkcyjnej zwykle deklaruje zgodność z polityką znakowania czasem, taką jak ETSI EN 319 421 §5, oraz stosuje profil protokołu RFC 3161 opisany w ETSI EN 319 422 §7; potwierdź to względem opublikowanej polityki operatora, zamiast zakładać to wyłącznie na podstawie publicznego zaufania.

Urząd TSA kwalifikowany według eIDAS

W przypadku znaczników czasu, które muszą nieść kwalifikowany skutek prawny w Unii Europejskiej, użyj kwalifikowanej usługi znakowania czasem od kwalifikowanego dostawcy usług zaufania (QTSP) umieszczonego na unijnej liście zaufanej. Kwalifikowany elektroniczny znacznik czasu wiąże czas z danymi w taki sposób, by w rozsądnym stopniu uniemożliwić niewykrywalną zmianę, opiera się na dokładnym źródle czasu powiązanym z uniwersalnym czasem koordynowanym (UTC) i jest chroniony zaawansowanym podpisem elektronicznym lub zaawansowaną pieczęcią elektroniczną QTSP albo metodą równoważną (Regulation (EU) 910/2014, Art 42). To najsilniejsza opcja i ta, którą należy wybrać, gdy przepis prawny wprost wymienia kwalifikowane znaczniki czasu.

Konfiguracja dla poszczególnych frameworków

Wartość domyślna znajduje się w konfiguracji każdego adaptera frameworka, a nie w samym silniku core. Core nigdy nie wymyśla URL: zbudowany ręcznie TsaClient wymaga jawnego punktu końcowego i zgłasza wyjątek, jeśli jest on pusty. Poziomy długoterminowe (B-LT i B-LTA) ponownie wykorzystują ten sam skonfigurowany urząd TSA co B-T.

Integracja	Gdzie znajduje się wartość domyślna	Jak nadpisać
Laravel	`config/nextpdf.php` -> `tsa.url`	ustaw `NEXTPDF_TSA_URL` w `.env`
Symfony	konfiguracja bundle `nextpdf.tsa.url`	ustaw węzeł lub powiąż go ze zmienną środowiskową
CodeIgniter	`Config\NextPdf::$tsa['url']`	nadpisz przez klucz środowiskowy `nextPdf.tsa.url`
Plain core	brak niejawnej wartości domyślnej	skonstruuj `TsaClient` z jawnym URL + utwardzonym klientem PSR-18

W każdym adapterze B-B nigdy nie buduje klienta TSA, więc podpis bez znacznika czasu nie jest objęty żadną z tych konfiguracji.

Model zaufania i normy

Wartością znacznika czasu jest łańcuch zaufania za nim stojący, a nie same bajty. Token RFC 3161 stwierdza wyłącznie czas; to, czy to stwierdzenie jest wiarygodne, jest właściwością urzędu TSA, który go podpisał (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Pozostając przy dostarczonym domyślnym urzędzie, wybierasz hostowaną samodzielnie, prywatną kotwicę zaufania — dobrą do pracy deweloperskiej i procesów wewnętrznych, gdzie każda strona ufająca może zainstalować korzeń PATEON, ale nie do dokumentów walidowanych przez strony trzecie. W ich przypadku przejdź na urząd TSA objęty publicznym zaufaniem lub na urząd TSA kwalifikowany według eIDAS, gdy wymagany jest kwalifikowany skutek prawny.

Jeśli sam obsługujesz domyślny urząd, możesz przypiąć klucz publiczny urzędu TSA we własnym wstrzykiwanym kliencie PSR-18. Nie przypinaj dostarczonego domyślnego urzędu we współdzielonym kodzie: rotacja klucza po stronie operatora zepsułaby wtedy naraz wszystkich użytkowników domyślnego urzędu. Zaufaniem do znacznika czasu jest łańcuch certyfikatów i korzeń PATEON, a nie przypięcie transportowe.