Przepływ pracy z podpisanymi umowami

Spec: ETSI EN 319 142-2, §5.1 Spec: ISO 32000-2:2020, §12.8 Evidence: Mixed evidence

W skrócie

Podpisana umowa to nie „plik PDF z podpisem”. To dokument przygotowany tak, aby podpis chronił właściwe bajty. To dokument podpisany na poziomie odpowiadającym wymaganiu. To dokument złożony tak, aby nadal się weryfikował po wygaśnięciu certyfikatu podpisującego. Ta strona przeprowadza przez scenariusz od pustego dokumentu do długowiecznej umowy. Wprost wskazuje, które kroki są dziś okablowane w silniku, a które silnik udostępnia jako zamrożoną powierzchnię.

Dlaczego to ma znaczenie

Umowa, która weryfikuje się w dniu podpisania, a trzy lata później zawodzi w sporze, jest gorsza niż brak podpisu, ponieważ ktoś na niej polegał. Przyczyną awarii rzadko jest kryptografia. Zazwyczaj winny jest brakujący znacznik czasu albo brakujący dowód unieważnienia, a problem wychodzi na jaw długo po tym, jak podpisujący odszedł.

Wybranie z góry wymagania dotyczącego podpisu i wytworzenie w chwili podpisywania dowodu, którego to wymaganie potrzebuje, odróżnia umowę, która się broni, od takiej, która po cichu niszczeje. To decyzja, którą podejmuje się raz w przepływie pracy, zamiast odkrywać ją na nowo przy każdym sporze.

Wersja skrócona

Najpierw przygotuj, potem podpisz. Podpis obejmuje dokładnie ten zakres bajtów, na podstawie którego został obliczony. Uznaj dokument za ostateczny — wraz ze wszystkimi późniejszymi wersjami dołączanymi do pliku — przed podpisaniem, a nie po.
Dobierz poziom do wymagania, a nie odwrotnie. PAdES definiuje progresję: podpis podstawowy, podpis ze znacznikiem czasu, podpis z osadzonym materiałem walidacyjnym oraz podpis ponownie ostemplowany dla bezterminowej ważności archiwalnej (ETSI EN 319 142-2 §5.1).
Długoterminowa ważność to struktura, a nie właściwość. To Document Security Store wraz ze znacznikiem czasu dokumentu, zapisanym w pliku (ISO 32000-2:2020 §12.8).
Precyzyjnie opisuj styk. Wysokopoziomowa metoda Document::setSignature() w NextPDF zamraża publiczne API, ale zawodzi szybko, zamiast emitować niepodpisany plik. Okablowaną ścieżką jest niskopoziomowy orkiestrator. Ta strona nie udaje, że jest inaczej.

Jak podchodzi do tego NextPDF

NextPDF oddziela decyzję od mechanizmu. Decyzja dotyczy tego, jakiego poziomu PAdES potrzebuje dane wymaganie. Mechanizm to sposób, w jaki bajty są podpisywane oraz to, jak przenoszony jest materiał walidacyjny. Gdy traktuje się je jak jedną rzecz, zespoły kończą z podpisem, który jest ważny, ale nietrwały.

Scenariusz ma cztery etapy.

Prepare the document Compose the agreement and treat it as final. The signature will protect this exact byte range and nothing added outside it without a new revision.
Choose the obligation B-B proves who. B-T adds trusted time. B-LT embeds the material to validate later. B-LTA re-stamps for indefinite validity.
Sign A CMS signature is embedded in the signature dictionary over the byte range; a timestamp is requested from a TSA if the level needs one.
Preserve For long-term levels, the Document Security Store and a document timestamp are written so the signature outlives its certificate.

Scenariusz podpisanej umowy od początku do końca: każdy etap dodaje gwarancję, a poziom wybrany na etapie drugim określa, ile dowodów muszą wytworzyć etapy trzeci i czwarty.

Typ wyliczeniowy poziomu faktycznie istnieje i uczciwie koduje wymaganie. B-B dowodzi tożsamości podpisującego. B-T dodaje zaufany znacznik czasu. Pytanie o „kiedy” jest tak samo stanowcze jak pytanie o „kto”. B-LT osadza certyfikaty i odpowiedzi dotyczące unieważnienia potrzebne do zwalidowania podpisu po wygaśnięciu certyfikatu podpisującego. B-LTA dodaje znaczniki czasu dokumentu, dzięki czemu łańcuch zaufania można rozszerzać bezterminowo, ponownie stemplując przed wygaśnięciem każdego certyfikatu znacznika czasu. Ten typ wyliczeniowy wskazuje, które poziomy wymagają znacznika czasu, a które wymagają osadzonego materiału walidacyjnego, więc silnik może odrzucić niemożliwą kombinację zamiast wytworzyć plik myląco wyglądający na „podpisany”.

Uczciwie postawiona granica: Document::setSignature() istnieje po to, aby powierzchnia publicznego API pozostała zamrożona dla konsumentów zależnych, lecz styk zapisu, który zamienia ją w rzeczywiście podpisaną wersję, nie jest jeszcze okablowany. Wywołanie tej metody, a następnie save() nie emituje niepodpisanego pliku PDF i nie traktuje zadania jako ukończonego. Zawodzi szybko, zgłaszając blokujący komunikat diagnostyczny, który wskazuje obsługiwaną ścieżkę. Szybka awaria zamiast cichego, błędnego artefaktu to świadoma decyzja projektowa. Umowa, która wygląda na podpisaną, choć nie jest podpisana, to dokładnie ta awaria, której ten mechanizm unika. Dziś okablowaną ścieżką jest niskopoziomowy dwufazowy orkiestrator, a możliwości długoterminowej archiwizacji są w warstwie Premium.

Co mówią dowody

Progresja jest poparta standardem. Evidence: Standard-backed Spec: ETSI EN 319 142-2, §5.1 opisuje poziomy PAdES zbudowane na blokach konstrukcyjnych EN 319 142-1, od podstawowego osadzonego podpisu wzwyż. Strukturę długoterminową ustala Spec: ISO 32000-2:2020, §12.8 : długoterminowa walidacja opiera się na Document Security Store i słowniku znacznika czasu dokumentu zapisanych w pliku.

Model poziomów jest poparty kodem. Evidence: Code-backed Typ wyliczeniowy SignatureLevel ma cztery przypadki PAdES (B-B, B-T, B-LT, B-LTA) z metodami predykatowymi odpowiadającymi na pytania: „wymaga znacznika czasu”, „wymaga osadzonego materiału walidacyjnego” oraz „wymaga znaczników czasu dokumentu”. Wysokopoziomowa metoda Document::setSignature() jest okablowana do strażnika szybkiej awarii, który zgłasza blokujący komunikat diagnostyczny pozwalający działać dalej, zamiast emitować niepodpisany dokument — to weryfikowalne zachowanie, a nie deklaracja.

Zachowanie związane z długoterminowym utrzymaniem jest udokumentowane na poziomie możliwości dla warstwy Premium: powierzchnia archiwalna zapisuje DSS oraz VRI per-podpis, sprawdza kompletność archiwum za pomocą kontroli stanu i ponownie stempluje dokument znacznikiem czasu przed wygaśnięciem certyfikatu znacznika czasu. Dokumentacja wprost stwierdza, że ostateczna decyzja nadal należy do weryfikatora.

Przykład praktyczny

Ten przykład pokazuje decyzję — wybór wymagania — przy użyciu rzeczywistego typu wyliczeniowego. Okablowaną ścieżką podpisywania jest niskopoziomowy orkiestrator. Wywołanie wysokopoziomowe pokazano wyłącznie po to, aby uwidocznić zachowanie szybkiej awarii.

<?php

declare(strict_types=1);

use NextPDF\Security\Signature\SignatureLevel;

/**
 * Map a business obligation to a PAdES level.
 *
 * The obligation drives the level, not the reverse — choosing B-B for a
 * 10-year contract is a decision you do not want to make implicitly.
 */
function levelForObligation(string $obligation): SignatureLevel
{
    return match ($obligation) {
        // Internal sign-off, short retention, signer identity is enough.
        'internal_approval' => SignatureLevel::PAdES_B_B,

        // Counterparty agreement: prove the moment of signing.
        'counterparty_agreement' => SignatureLevel::PAdES_B_T,

        // Regulated contract that must verify after cert expiry.
        'regulated_contract' => SignatureLevel::PAdES_B_LT,

        // Long-lived legal record: indefinite, re-stampable validity.
        'long_term_legal_record' => SignatureLevel::PAdES_B_LTA,

        default => throw new \InvalidArgumentException(
            "Unknown obligation: {$obligation}",
        ),
    };
}

$level = levelForObligation('regulated_contract');

// The enum carries the obligation's implications with it.
$needsTsa     = $level->requiresTimestamp();         // true for B-T+
$needsDss     = $level->requiresDss();               // true for B-LT+
$needsArchive = $level->requiresDocumentTimestamp(); // true only for B-LTA

Obiekt poziomu nie jest etykietą. Odpowiada na konsekwencje wymagania, więc okablowanie niższego szczebla nie musi ich ponownie wyprowadzać.

Częste nieporozumienie

Powracające nieporozumienie to „podpis jest ważny, więc skończyliśmy.” Ważność dziś jest konieczna, ale niewystarczająca. Podpis jest obliczany na podstawie zakresu bajtów. Wszystko, co dołączono poza tym zakresem w późniejszej wersji, nie jest nim objęte — i właśnie dlatego przygotowanie poprzedza podpisywanie. A podpis, który weryfikuje się teraz, może zawieść później, gdy jego certyfikat wygaśnie, chyba że materiał walidacyjny osadzono w chwili podpisywania. „Ważny” i „trwały” to różne gwarancje i tylko wymaganie mówi, której z nich faktycznie potrzebujesz.

Powiązana pułapka charakterystyczna dla tego silnika: założenie, że wysokopoziomowa metoda setSignature() wytwarza podpisany plik dzisiaj. Tak nie jest. Zawodzi szybko celowo. Traktuj komunikat diagnostyczny jak kontrakt.

Ograniczenia i granice

Document::setSignature() to zamrożona powierzchnia publiczna, a nie okablowany mechanizm podpisywania. Zawodzi szybko, zgłaszając blokujący komunikat diagnostyczny. Nigdy nie emituje niepodpisanego pliku PDF zamiast podpisanego. Okablowaną ścieżką jest niskopoziomowy dwufazowy orkiestrator.
Utrzymanie długoterminowej walidacji (DSS/VRI, kontrola stanu, pętla archiwalnego znacznika czasu) to możliwość warstwy Premium. Core nie udostępnia pętli archiwalnej. Zobacz granicę poniżej.
Podpis chroni dokładnie swój zakres bajtów. Późniejsze dołączone wersje są odrębne. Silnik nie rozszerza wstecznie ochrony.
NextPDF wytwarza i utrzymuje struktury; nie rozstrzyga. To, czy podpis jest zaufany, zależy od kotwic zaufania i polityki weryfikatora, które są poza silnikiem.
B-LTA sam w sobie nie czyni podpisu wiecznym. Umożliwia bezterminową ważność tylko wtedy, gdy pętla ponownego stemplowania działa zgodnie z harmonogramem przed wygaśnięciem każdego certyfikatu znacznika czasu.
Ta strona opisuje powierzchnię archiwalną Premium na poziomie zachowania. Nie zakłada akceptacji przez żaden konkretny sąd ani organ.

PAdES signing and long-term validity — edition availability
Edition	Availability
Core	Core udostępnia typ wyliczeniowy `SignatureLevel` oraz zamrożoną powierzchnię `Document::setSignature()` (szybka awaria). Okablowany niskopoziomowy orkiestrator obejmuje podpisywanie podstawowe. Długoterminowe utrzymanie archiwalne nie jest dostępne w Core.
Pro	Podstawowe podpisywanie PAdES (B-B / B-T) przez orkiestrator jest dostępne.
Enterprise	Dodaje B-LT / B-LTA, Document Security Store oraz utrzymanie VRI per-podpis, kontrolę stanu LTV oraz pętlę archiwalną znacznika czasu dokumentu dla bezterminowej ważności.

Powiązane dokumenty

Profile bazowe PAdES — B-B, B-T, B-LT, B-LTA objaśnione jako progresja oraz jak wybierać.
Długoterminowa walidacja — dlaczego podpis, który weryfikuje się dzisiaj, może zawieść za dziesięć lat oraz jak LTV osadza dowody.
Przewodnik decyzyjny dotyczący integracji — który pakiet z ekosystemu pasuje do przepływu pracy podpisywania, w tym styk zatwierdzania przez człowieka w NextPDF Connect.

Słownik

PAdES — PDF Advanced Electronic Signatures: rodzina profili ETSI definiująca, jak zaawansowany podpis elektroniczny jest przenoszony w pliku PDF.
Zakres bajtów — ciągły obszar bajtów pliku, na podstawie którego obliczany jest podpis; treść poza nim nie jest chroniona tym podpisem.
Poziom podpisu (B-B / B-T / B-LT / B-LTA) — progresja PAdES określająca, kto podpisał i kiedy, z osadzonym materiałem walidacyjnym oraz z możliwością ponownego stemplowania dla bezterminowej ważności archiwalnej.
TSA — Time-Stamping Authority (urząd znacznika czasu): usługa RFC 3161, która poświadcza, że stan dokumentu istniał w danej chwili UTC.
DSS (Document Security Store) — wbudowany w plik magazyn certyfikatów, odpowiedzi OCSP i list CRL potrzebnych do zwalidowania podpisu po wygaśnięciu jego certyfikatu.
LTV (Long-Term Validation) — utrzymywanie weryfikowalności podpisu w czasie poprzez osadzanie dowodów walidacyjnych i ponowne stemplowanie.
Fail-fast (szybka awaria) — odmowa wytworzenia mylącego artefaktu i zgłoszenie w zamian gotowego do działania błędu, bez cichego emitowania błędnego pliku.