Jak podpisy są osadzone w pliku PDF

Spec: ETSI EN 319 142-1 Spec: RFC 5652 Evidence: Standard-backed

W skrócie

Podpis PDF nie jest owinięty wokół pliku. Jest osadzony wewnątrz niego: tworzy go słownik podpisu oraz skrót obliczony dla zadeklarowanego zakresu bajtów, który celowo pomija samą wartość podpisu. Ta strona wyjaśnia ten mechanizm oraz, równie ważne, czego nie gwarantuje.

Dlaczego to ma znaczenie

„Dokument jest podpisany” to stwierdzenie, na podstawie którego ludzie podejmują decyzje. Łączą je z płatnością, zatwierdzeniem, zobowiązaniem prawnym. Bez dokładnej wiedzy, które bajty obejmuje podpis, nie da się powiedzieć, czego prawidłowy wynik faktycznie dowodzi. Plik PDF może zawierać w pełni prawidłowy podpis i mimo to pokazywać czytelnikowi treść, której podpisujący nigdy nie widział, ponieważ dodano ją po podpisaniu, w obszarze, którego zakres podpisu nigdy nie obejmował. Wiedza o tym, gdzie zaczyna się i kończy zakres podpisu, to różnica między decyzją możliwą do obrony a decyzją opartą na nadziei.

Wersja w skrócie

Podpis PDF znajduje się w słowniku podpisu i w polu podpisu wewnątrz dokumentu, a nie w zewnętrznej kopercie.
Podpisane bajty deklaruje tablica ByteRange: dwa segmenty (offset, length), które razem obejmują cały plik z wyjątkiem szesnastkowej wartości podpisu przechowywanej we wpisie Contents.
To skrót tych dwóch połączonych segmentów jest tym, co podpis kryptograficzny faktycznie chroni.
Wszystko, co dołączono później w nowej rewizji, znajduje się poza pierwotnym zakresem bajtów. Pierwotny podpis pozostaje prawidłowy; nigdy nie obejmował nowych bajtów.
Podpis zatwierdzający i podpis certyfikujący różnią się zakresem: certyfikacja (DocMDP) ogranicza, jakie późniejsze zmiany są dozwolone; podpis zatwierdzający nie nakłada takich ograniczeń.

Jak podchodzi do tego NextPDF

NextPDF buduje podpis zgodnie z modelem formatu, w ustalonej kolejności, dzięki czemu zakres bajtów jest dokładny, a nie przybliżony.

Gdy silnik zapisuje podpis, najpierw rezerwuje miejsce o stałym rozmiarze dla wartości Contents i zapisuje symbol zastępczy ByteRange o stałej szerokości. Czeka, aż cały dokument zostanie zapisany, łącznie z tablicą odsyłaczy i znacznikiem końca pliku. Dopiero wtedy oblicza dwa rzeczywiste przesunięcia, zapisuje je z powrotem w symbolu zastępczym bez przesuwania żadnego bajtu, oblicza skrót z dwóch segmentów i umieszcza powstały obiekt CMS w zarezerwowanym miejscu. Symbol zastępczy jest dopełniany zerami do stałej długości właśnie po to, aby wpisanie rzeczywistych liczb nie mogło przesunąć bajtów objętych skrótowaniem. To jedyna kolejność, która daje spójny wewnętrznie podpis. Silnik traktuje każdy błąd w tej sekwencji jako twardy błąd, a nie cichą ścieżkę awaryjną.

W profilu PDF 2.0 sam obiekt podpisu jest odłączoną strukturą CMS SignedData. Słownik PDF mówi gdzie i jak; obiekt CMS niesie informację o tym, kto, oraz dowód kryptograficzny.

Step 1 of 4: ISO 32000-2 §12.8.1 — ByteRange digest & signature dictionary
Step 2 of 4: ISO 32000-2 §12.8.3.3 — ETSI.CAdES.detached SubFilter
Step 3 of 4: ETSI EN 319 142-1 PAdES baseline profile
Step 4 of 4: RFC 5652 CMS SignedData in Contents

Gdzie definiowany jest podpis PDF — od formatu kontenera aż po obiekt kryptograficzny: ISO 32000-2 określa słownik i mechanizm zakresu bajtów, ETSI EN 319 142-1 profiluje go dla PAdES, a RFC 5652 definiuje obiekt CMS SignedData umieszczany w Contents.

Co mówią dowody

Evidence: Standard-backed Mechanizm definiuje Spec: ISO 32000-2, §12.8.1 . Skrót zakresu bajtów jest obliczany dla zakresu bajtów wskazanego przez wpis ByteRange. Ten zakres powinien obejmować cały plik łącznie z słownikiem podpisu, ale z wyłączeniem wartości podpisu — wpisu Contents. ByteRange jest tablicą par liczb całkowitych — przesunięcia początkowego i długości. Nieciągłe zakresy stosuje się właśnie po to, aby skrót mógł pominąć samą wartość podpisu.

W profilu PDF 2.0 Spec: ISO 32000-2, §12.8.3.3 określa, że gdy SubFilter ma wartość ETSI.CAdES.detached, wartość Contents jest zakodowanym w DER obiektem CMS SignedData — strukturą definiowaną przez Spec: RFC 5652 — a profil PAdES dla tego obiektu opisuje Spec: ETSI EN 319 142-1 .

Zakres nie jest jednolity dla wszystkich podpisów. Spec: ISO 32000-2, §12.7.4.5 definiuje uprawnienie MDP: wartość 0 oznacza podpis zatwierdzający, natomiast wartości 1–3 oznaczają podpis certyfikujący, który ogranicza, które późniejsze zmiany zachowują zgodność dokumentu. Mechanizm zakresu bajtów jest ten sam; inna jest obietnica co do przyszłości.

Silnik NextPDF realizuje dokładnie ten model: symbol zastępczy ByteRange o stałej szerokości, dwusegmentowy połączony skrót oraz odłączony obiekt CMS w zarezerwowanym miejscu Contents, finalizowane dopiero po skompletowaniu pliku.

Przykład praktyczny

Rzadko buduje się ByteRange ręcznie. Celem przykładu jest pokazanie kształtu wyniku, aby był rozpoznawalny podczas inspekcji podpisanego pliku.

<?php

declare(strict_types=1);

use NextPDF\Security\Signature\ByteRangeCalculator;

// Offsets the engine knows only after the whole PDF is written:
//   $contentsStart — byte just before the '<' of the hex signature
//   $contentsEnd   — byte just after the '>' that closes it
//   $fileLength    — total file size in bytes
$range = ByteRangeCalculator::calculate(
    contentsStart: $contentsStart,
    contentsEnd: $contentsEnd,
    fileLength: $fileLength,
);
// $range === [0, $contentsStart, $contentsEnd, $fileLength - $contentsEnd]
// Segment 1: file start  → just before the signature value
// Segment 2: just after the signature value → end of file
// The signature value itself is the gap. It is never hashed.

$signedMessage = ByteRangeCalculator::extractSignedData($pdfBytes, $range);
// $signedMessage is segment 1 concatenated with segment 2 — exactly the
// bytes the cryptographic digest is computed over.

Luka między tymi dwoma segmentami to wartość podpisu. Nie może stanowić części własnego skrótu, dlatego zakres składa się z dwóch części, a nie jednej.

Częste nieporozumienie

Pułapką jest przekonanie, że prawidłowy podpis oznacza, że podpisano cały plik, na który patrzysz. Tak nie jest. Oznacza, że bajty wewnątrz zadeklarowanego zakresu są nienaruszone. Późniejsza rewizja może zgodnie z zasadami dołączyć treść — drugi podpis, dane formularza, materiał walidacyjny — poza tym zakresem. Pierwszy podpis pozostaje prawidłowy i nie mówi nic o tym dodatku. Prawidłowa przeglądarka informuje, że podpis obejmuje „dokument w stanie z chwili podpisania”, a nie „każdy bajt na ekranie”. Traktowanie tych dwóch rzeczy jako tożsamych to sposób, w jaki podpisany dokument zyskuje niepodpisaną treść, która wygląda na podpisaną.

Ograniczenia i granice

Ta strona wyjaśnia strukturę, a nie zaufanie. Poprawnie utworzony ByteRange oraz obiekt CMS mówią, że bajty są nienaruszone i który klucz je podpisał. Same z siebie nie mówią, czy ten klucz należy do podmiotu, któremu go przypisujesz, czy jego certyfikat był prawidłowy w chwili podpisania, ani czy został później unieważniony. To zadanie dla walidacji ścieżki certyfikatu i statusu unieważnienia, omówione w Poprawna walidacja podpisu. Ta strona nie obejmuje też kiedy nastąpiło podpisanie według jakiegokolwiek niezależnego źródła. Czas podpisania zadeklarowany przez samego podpisującego nie jest zaufanym czasem — zobacz Znaczniki czasu i zaufany czas. NextPDF buduje opisaną tu strukturę; certyfikaty, kotwice zaufania oraz urząd znaczników czasu dostarcza wdrożenie, a nie silnik.

W zależności od wersji silnik udostępnia następujące możliwości budowania struktury:

PAdES signature structure (byte range, signature dictionary, detached CMS) — edition availability
Edition	Availability
Core	PAdES B-B: słownik podpisu, ByteRange o stałej szerokości oraz odłączony obiekt CMS SignedData opisany na tej stronie.
Pro	Dodaje PAdES B-T — zaufany znacznik czasu na wartości podpisu — oparty na tej samej strukturze.
Enterprise	Dodaje profile długoterminowe (B-LT, B-LTA): osadzony materiał walidacyjny oraz znaczniki czasu dokumentu oparte na tym samym fundamencie zakresu bajtów.

Powiązane dokumenty

Aktualizacje przyrostowe i dlaczego mają znaczenie — dlaczego to dołączanie, a nie przepisywanie, zachowuje nienaruszony zakres bajtów pierwszego podpisu.
Profile bazowe PAdES — co nakłada się na tę strukturę i którego profilu wymaga dane zobowiązanie.
Walidacja długoterminowa — jak osadza się dowody walidacji, aby podpis pozostawał weryfikowalny przez lata.

Słowniczek

Słownik podpisu — słownik PDF, który wskazuje procedurę obsługi podpisu, SubFilter, ByteRange oraz wartość Contents.
ByteRange — tablica par liczb całkowitych (offset, length) deklarująca dokładne bajty objęte skrótem podpisu.
Contents — szesnastkowy wpis przechowujący wartość podpisu (dla PDF 2.0 jest to odłączony obiekt CMS SignedData); jest wyłączony z własnego skrótu.
CMS SignedData — struktura Cryptographic Message Syntax (RFC 5652) zawierająca certyfikat podpisującego oraz bajty podpisu.
PAdES — PDF Advanced Electronic Signatures: profil ETSI podpisów CMS dla PDF, zdefiniowany w serii ETSI EN 319 142.
Podpis zatwierdzający — podpis z uprawnieniem MDP o wartości 0; potwierdza treść, nie ograniczając późniejszych zmian.
Podpis certyfikujący — podpis z uprawnieniem DocMDP (MDP 1–3), który ogranicza, które późniejsze zmiany zachowują zgodność dokumentu.