Mapowanie poziomów bazowych PAdES

W skrócie

PDF Advanced Electronic Signatures (PAdES) to rodzina profili znormalizowana w ETSI EN 319 142. Definiuje ona cztery bazowe poziomy zgodności — B-B, B-T, B-LT i B-LTA — w których każdy wyższy poziom dodaje materiał względem poziomu niższego. Ta strona mapuje te poziomy na artefakty generowane przez NextPDF. Rozdziela zakres Core od edycji Pro i Enterprise. Mapowanie jest behawioralne: opisuje to, co emituje silnik, a nie jego wewnętrzne klasy.

W skrócie: NextPDF Core generuje struktury podpisu zgodne z B-B i B-T. Ścieżka producenta dla B-LT i B-LTA jest dostarczana w edycjach Pro i Enterprise. To, czy wygenerowany podpis zostanie zaakceptowany jako zgodny na danym poziomie, zależy od weryfikatora oraz skonfigurowanych w nim kotwic zaufania. Producent nie może orzec zgodności w imieniu weryfikatora.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Cyfrowy podpis PDF to struktura SignedData Cryptographic Message Syntax (CMS) przechowywana w pozycji Contents słownika podpisu. Tablica ByteRange wskazuje zakresy bajtów objęte skrótem — ISO 32000-2 §12.8.1. CMS SignerInfo przenosi podpisane atrybuty, w tym atrybuty content-type i message-digest — RFC 5652 §5.3. Proces z §5.4 określa sposób obliczania skrótu komunikatu dla tych atrybutów. PAdES wykorzystuje model atrybutów CMS Advanced Electronic Signatures (CAdES) wewnątrz słownika podpisu PDF.

Cztery poziomy bazowe są przyrostowe:

• B-B zawiera podpis podstawowy wraz z obowiązkowymi podpisanymi atrybutami.
• B-T dodaje atrybut znacznika czasu podpisu obliczony nad wartością podpisu. Atrybut znacznika czasu dowodzi, że podpis istniał w chwili wskazanej przez znacznik — ETSI PAdES §5.4.3. Urząd znakowania czasem zgodny z RFC 3161 generuje token — RFC 3161 §2.4.1.
• B-LT dodaje materiał walidacji długoterminowej — certyfikat, dane Online Certificate Status Protocol (OCSP) oraz listy unieważnionych certyfikatów (CRL) — umieszczany w Document Security Store — ETSI PAdES §6.2.2, ISO 32000-2 §12.8.4.3 oraz zgodnie z rozmieszczeniem danych walidacji opisanym w ETSI EN 319 142-2 §6.3.
• B-LTA dodaje archiwalny znacznik czasu dokumentu, aby utrzymać ważność przez długie okresy — ETSI PAdES §6.2.2.

Cztery poziomy są ściśle przyrostowe — każdy wyższy poziom zachowuje wszystko, co obejmował poziom niższy, i dodaje dokładnie jedną nową warstwę materiału. Etykiety przejść wskazują edycję producenta, która dostarcza dany krok.

Diagram

Powierzchnia API

Aby wybrać poziom, użyj wyliczenia SignatureLevel. Definiuje ono przypadki PAdES_B_B, PAdES_B_T, PAdES_B_LT i PAdES_B_LTA. Jego metody requiresTimestamp(), requiresDss(), requiresDocumentTimestamp() i isAvailableInEnvironment() informują o wymaganiach każdego poziomu oraz o tym, czy bieżące środowisko uruchomieniowe może je spełnić. W dystrybucji Core isAvailableInEnvironment() zwraca true dla B-B i B-T oraz false dla B-LT i B-LTA. Zwraca false dla B-LT i B-LTA, ponieważ producent walidacji długoterminowej jest rozwiązywany w czasie uruchomienia i nie jest częścią pakietu open source. Kod produkcyjny powinien korzystać z kontraktu SignerInterface, a nie z tych typów wewnętrznych.

Macierz wsparcia poziomów

Poziom	Co dodaje	Core (nextpdf/core)	Pro / Enterprise
B-B	Podpis podstawowy z obowiązkowymi podpisanymi atrybutami	Generuje zgodną strukturę; testy porównują ją z syntetycznymi wzorcami golden	Ta sama powierzchnia
B-T	Znacznik czasu podpisu nad wartością podpisu	Generuje zgodną strukturę, gdy dostępna jest usługa znacznika czasu zgodna z RFC 3161	Ta sama powierzchnia
B-LT	Dane walidacji w Document Security Store	Producent nie jest dostarczany w Core; wybór B-LT bez pakietu Enterprise kończy się bezpiecznym odrzuceniem	Producent dostarczony
B-LTA	Archiwalny znacznik czasu dokumentu	Producent nie jest dostarczany w Core; bezpieczne odrzucenie jak powyżej	Producent dostarczony

„Generuje zgodną strukturę” oznacza, że NextPDF emituje podpis, którego struktura odpowiada przywołanym klauzulom. Artefakty tests/Corpus/pades/ i tests/Golden/baselines/ w projekcie potwierdzają tę strukturę. Nie oznacza to, że zewnętrzny weryfikator certyfikuje wynik na tym poziomie. Zobacz sekcję dotyczącą zgodności.

Przykład kodu — szybki start

examples/contracts/signing-quickstart.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\SignerInterface;

/**
 * Sign a byte range with any SignerInterface implementation.
 *
 * @param SignerInterface $signer    A Core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData for the PDF /Contents field.
 */
function signByteRange(SignerInterface $signer, string $byteRange): string
{
    return $signer->sign($byteRange)->toHex();
}

Funkcja zależy od kontraktu SignerInterface, a nie od konkretnej klasy. Implementują go zarówno programowy komponent podpisujący Core (B-B lub B-T), jak i komponent podpisujący ze sprzętowym modułem bezpieczeństwa (HSM) w wersji Premium. Kod wywołujący nie zmienia się przy zmianie edycji.

Przykład kodu — produkcja

examples/contracts/signing-level.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Security\Signature\SignatureLevel;

/**
 * Resolve the highest baseline level the current runtime can produce.
 *
 * B-B and B-T are produced by the Core distribution. B-LT and B-LTA
 * require the Enterprise long-term-validation package; without it the
 * level reports unavailable so callers fail closed rather than emit a
 * structure that does not carry the validation material the level names.
 *
 * @return SignatureLevel The highest level available in this runtime.
 */
function highestAvailableLevel(): SignatureLevel
{
    foreach ([
        SignatureLevel::PAdES_B_LTA,
        SignatureLevel::PAdES_B_LT,
        SignatureLevel::PAdES_B_T,
        SignatureLevel::PAdES_B_B,
    ] as $level) {
        if ($level->isAvailableInEnvironment()) {
            return $level;
        }
    }

    return SignatureLevel::PAdES_B_B;
}

isAvailableInEnvironment() zwraca true dla B-B i B-T bez dodatkowego pakietu. Zwraca true dla B-LT i B-LTA tylko wtedy, gdy zainstalowany jest pakiet walidacji długoterminowej Enterprise. Jeśli wybierzesz niedostępny poziom bez włączenia degradacji, NextPDF zgłasza typowany wyjątek informujący o nieosiągalnym poziomie, a jego komunikat wskazuje brakujący pakiet. Błędnie skonfigurowane wdrożenie kończy się więc bezpiecznym odrzuceniem, zamiast po cichu emitować poziom niższy niż żądany przez wywołującego.

Przypadki brzegowe i pułapki

• Strukturalnie poprawny podpis B-T to nie to samo co podpis zweryfikowany jako B-T. Walidacja odbywa się w weryfikatorze, z jego kotwicami zaufania i świeżością informacji o unieważnieniach. Producent nie może przesądzić o wyniku.
• PAdES B-LT i B-LTA wymagają pakietu NextPDF Enterprise (nextpdf/enterprise). Jeśli nie jest zainstalowany, komponent podpisujący kończy się bezpiecznym odrzuceniem, a B-LT/B-LTA są niedostępne. Core udostępnia B-B/B-T przez publiczny NextPDF\Contracts\SignerInterface; walidacja długoterminowa pozostaje za LtvManagerInterface. Wybór niedostępnego poziomu w Core domyślnie kończy się bezpiecznym odrzuceniem. Typowany wyjątek wskazuje brakujący pakiet publiczny, a nie typ wewnętrzny. Łagodna degradacja do niższego poziomu jest opcjonalna, nigdy domyślna.
• Skrót zakresu bajtów musi wyłączać wartość podpisu. Jeśli skrót obejmie również oktety Contents, weryfikacja nigdy się nie powiedzie — ISO 32000-2 §12.8.1.
• W B-T znacznik czasu podpisu obejmuje wartość podpisu, a nie bajty dokumentu. W B-LTA archiwalny znacznik czasu jest osobnym znacznikiem czasu dokumentu. Nie są one wymienne — ETSI PAdES §5.4.3 i §6.2.2.
• ETSI EN 319 142-1 (część dotycząca poziomów bazowych) nie znajduje się w korpusie dowodowym tego projektu. Twierdzenia o strukturze poziomów są tu oparte na ETSI EN 319 142-2, dokumencie profilu pades, ISO 32000-2 §12.8 oraz RFC 5652 / RFC 3161. Nazwy poziomów i struktura przyrostowa są przedstawione zgodnie z implementacją w v3.x. Ta strona nie rości sobie prawa do żadnego wyniku testu zgodności ani atestacji strony trzeciej.

Wydajność

Koszt rośnie wraz z poziomem. B-B to pojedyncza operacja podpisu, która dla klucza programowego zajmuje jednocyfrową liczbę milisekund. B-T dodaje jedną rundę sieciową do urzędu znakowania czasem. B-LT dodaje jedno pobranie danych o unieważnieniach na każdy certyfikat w łańcuchu. B-LTA dodaje kolejny znacznik czasu dokumentu. Budżet 1500 ms czasu ściennego obejmuje pojedynczy podpis B-T ze zdalnym urzędem znakowania czasem (TSA) na rozgrzanym połączeniu. W przypadku wolnego punktu końcowego unieważnień B-LT lub B-LTA przekracza ten budżet i należy przenieść je poza ścieżkę żądania. Profil odtwarzalności to structural, nie bitwise. Znacznik czasu osadza chwilę podpisania, więc dwa uruchomienia różnią się bajtami znacznika czasu, podczas gdy struktura dokumentu pozostaje identyczna.

Uwagi dotyczące bezpieczeństwa

Poziom deklarowany przez podpis i poziom, na którym podpis jest walidowany, to dwa różne fakty. Ta strona opisuje wyłącznie zakres producenta. Walidacja długoterminowa zależy od danych walidacji zebranych w chwili podpisywania oraz od tego, czy weryfikator zaufa później tym samym kotwicom. Producent nie może zagwarantować żadnego z tych faktów. Zaufanie do znacznika czasu sprowadza się do zaufania do urzędu znakowania czasem, który wdrożenie przypina za pomocą wstrzykiwanego dostawcy. Ta strona jest oznaczona jako export_control_class: legal-review-required, ponieważ dotyczy kryptograficznych profili podpisu. Wszystkie źródła normatywne są parafrazowane, a żadne nie jest odtwarzane, zgodnie z higieną cytowań.

Zgodność

Twierdzenie	Standard	Klauzula	Dowód
Wartość podpisu jest przechowywana w kodowaniu DER jako CMS SignedData lub TimeStampToken w pozycji Contents słownika podpisu.	ISO 32000-2	§12.8.1
Skrót jest obliczany nad zakresami ByteRange i wyłącza wartość podpisu.	ISO 32000-2	§12.8.1
Atrybut znacznika czasu podpisu jest obliczany nad wartością podpisu (B-T).	ETSI PAdES (EN 319 142)	§5.4.3
Materiał walidacji długoterminowej jest przenoszony w Document Security Store (B-LT).	ETSI PAdES (EN 319 142) / ISO 32000-2	§6.2.2 / §12.8.4.3	,
Dane walidacji są umieszczane w słownikach DSS i VRI.	ETSI EN 319 142-2	§6.3	,
Archiwalny znacznik czasu dokumentu utrzymuje ważność przez długie okresy (B-LTA).	ETSI PAdES (EN 319 142)	§6.2.2
SignerInfo niesie podpisane atrybuty content-type i message-digest.	RFC 5652	§5.3
Skrót komunikatu jest obliczany nad podpisanymi atrybutami w kodowaniu DER (proces z §5.4).	RFC 5652	§5.4
Znacznik czasu jest żądany od TSA zgodnego z RFC 3161 i zwraca strukturę TSTInfo.	RFC 3161	§2.4.1

Wszystkie klauzule są parafrazowane. NextPDF nie odtwarza tekstu normatywnego. Po autorytatywne brzmienie sięgnij do opublikowanych standardów. ETSI EN 319 142-1 nie znajduje się w korpusie dowodowym. Twierdzenia strukturalne dotyczące poziomów bazowych są oparte na powyższych źródłach i przedstawione zgodnie z implementacją w v3.x.

Kontekst komercyjny

Core generuje struktury podpisu B-B i B-T. Ścieżka producenta B-LT i B-LTA, kustodia kluczy HSM i PKCS#11 oraz profil polityki kryptograficznej FIPS 140-3 są dostarczane w edycjach Pro i Enterprise. Core rozwiązuje producenta walidacji długoterminowej w czasie uruchomienia, więc silnik open source nie zawiera żadnej zależności komercyjnej. API SignerInterface nie zmienia się przy aktualizacji.

Zobacz też

• Bezpieczeństwo / Podpisywanie — zakres implementacji CMS, znacznika czasu, walidacji długoterminowej (LTV), łańcucha zaufania i unieważnień.
• Kontrakty / Podpisywanie — interfejs dostawcy usług (SPI) SignerInterface oraz poziomy stabilności.
• Bezpieczeństwo — powierzchnia implementacji szyfrowania i podpisu.
• Zgodność — egzekwowanie PDF/A i profili powiązanych z podpisaną archiwizacją.
• PAdES · PAdES B-T · DSS · CAdES — terminy z glosariusza.