Security — pełna dokumentacja referencyjna

W skrócie

To pełna dokumentacja referencyjna powierzchni bezpieczeństwa NextPDF Pro: maskowanie w czasie generowania, wykrywanie PII w warstwie tekstu, sesja podpisywania zdalnego i przez chmurowy KMS, wielostronne podpisywanie sekwencyjne, ścieżka przyjmowania CAdES i XAdES, poziom bazowy PAdES B-B oraz obsługa podpisywania PAdES B-T (podpis B-B plus jeden znacznik czasu podpisu RFC 3161 na wartości podpisu). Opisuje kontrakt publicznego API, zachowanie obserwowalne z zewnątrz oraz granicę Enterprise B-LT/B-LTA. Jest na poziomie zachowania; nie przywołuje żadnych wewnętrznych ścieżek implementacji.

Dostępność i licencjonowanie

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

Core dostarcza programowy moduł podpisujący CMS, klienta znaczników czasu RFC 3161, walidację ścieżki RFC 5280 oraz sprawdzanie unieważnień OCSP i CRL. Pro dodaje opisane tutaj maskowanie, wykrywanie PII, powierzchnię podpisywania zdalnego i przez chmurowy KMS oraz obsługę podpisywania PAdES B-T (komponuje stos RFC 3161 z Core, aby dodać znacznik czasu podpisu). Flagą możliwości dla tej powierzchni jest pro: wdrożenie bez aktywnego uprawnienia Pro nie ładuje tych klas, kontrakt podpisywania Core nadal działa bez zmian, a kod zależny od kontraktu Core nie ulega awarii, gdy uprawnienie jest nieobecne.

Instalacja

composer require nextpdf/pro:^3

Kontrakt zachowania

Silnik maskowania stosuje uporządkowaną listę reguł do tekstu, zanim strona zostanie zapisana. Reguła dopasowuje wzorzec PCRE i zastępuje dopasowanie w jednym z trzech trybów:

• BlackBox — usuwa dopasowany tekst ze strumienia treści i rezerwuje obszar wypełnienia. Ten tryb usuwa leżące u podstaw obiekty tekstowe, co zostało przetestowane.
• Asterisks — zastępuje każdy dopasowany znak gwiazdką, zachowując liczbę znaków.
• FixedLabel — zastępuje całe dopasowanie konfigurowalną etykietą, domyślnie [REDACTED].

Reguła jest budowana z dokładnego literału przez MaskingRule::exactMatch (literał jest escapowany jako regex) lub z niestandardowego wzorca PCRE przez MaskingRule::regex. MaskingConfig przechowuje uporządkowaną listę reguł, tryb domyślny oraz kolor wypełnienia. MaskingConfig::fromArray parsuje mapę konfiguracji i po cichu odrzuca wpis reguły, który nie ma użytecznego wzorca łańcuchowego, zamiast przerywać cały import.

Powierzchnia PII wyodrębnia warstwę tekstu PDF, a następnie stosuje wbudowane wzorce dla adresów e-mail, numerów telefonów, numerów ubezpieczenia społecznego Stanów Zjednoczonych (Social Security) oraz numerów kart kredytowych. Zwraca ustrukturyzowany wynik: wartość logiczną mówiącą, czy znaleziono jakiekolwiek dopasowanie, liczbę dopasowań, zamaskowany widok tekstu oraz listę przeskanowanych typów. Wywołujący może ograniczyć skan do podzbioru tych czterech typów. Powierzchnia nie nadpisuje wyrenderowanych glifów strony; przeskanowana strona bez warstwy tekstu nie daje żadnych dopasowań. Traktuj wynik jako wykrywanie wzorców w warstwie tekstu dla skonfigurowanych typów, a nie jako kompletne usunięcie danych osobowych i nie jako oświadczenie o zgodności regulacyjnej.

Sesja podpisywania jest dwufazowa. RemoteSigningSession::create otwiera sesję. prepare oblicza skrót dokumentu na dwóch obszarach ByteRange, a następnie buduje podpisane atrybuty CMS. complete wywołuje strategię i osadza wynik; suspend serializuje sesję, aby pracownik (worker) mógł ją później wznowić za pomocą resume i completeWithRawSignature. Sesja składa CMS SignedData i przechowuje je zakodowane w DER we wpisie Contents słownika podpisu — ISO 32000-2 §12.8.1. Gdy dostarczony zostanie parsowalny certyfikat X.509, sesja emituje pełny obowiązkowy zestaw podpisanych atrybutów PAdES B-B: content-type, message-digest, signing-time, signing-certificate-v2 oraz atrybut ochrony algorytmu — RFC 5652 §5.3 i RFC 5652 §5. Weryfikator ponownie oblicza skrót treści i porównuje go z atrybutem message-digest; porównanie musi się zgadzać, aby podpis był ważny — RFC 5652 §5.4.

Gdy skonfigurowany poziom PAdES to B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T) lub przez SequentialSigner::withTimestamping) i podłączony jest dostawca znaczników czasu, sesja dodatkowo osadza dokładnie jeden signature-time-stamp RFC 3161 jako niepodpisany atrybut CMS na pierwszym SignerInfo. signature-time-stamp to niepodpisany atrybut niosący jeden znacznik czasu obliczony na wartości podpisu cyfrowego dla danego podpisującego — ETSI EN 319 122-1 §5.3; jego MessageImprint to skrót wartości pola podpisu SignerInfo z wyłączeniem znacznika i długości ASN.1 — ETSI EN 319 122-1 §5.3 i RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Ponieważ znacznik czasu jest atrybutem niepodpisanym, podpisane atrybuty B-B, message-digest, wartość podpisu SignerInfo oraz /ByteRange PDF są identyczne bajtowo z wynikiem B-B; rośnie wyłącznie CMS o niepodpisany atrybut, a zarezerwowana przestrzeń /Contents dla B-T jest zwiększana, aby się zmieścił. Token jest żądany od skonfigurowanego dostawcy znaczników czasu (domyślnego klienta RFC 3161 z Core lub dostawcy wskazanego przez wywołującego). Na ścieżce dostawcy domyślnego skrótem odcisku (imprint) jest SHA-256; związana z SHA-1 starsza forma ESSCertID v1 jest odrzucana, a wymagany jest ESSCertIDv2 — RFC 5816 §1. Błąd TSA, odrzucone żądanie, błędny nonce lub echo odcisku komunikatu, zniekształcony token lub token z nieobsługiwanym algorytmem albo token, który nie przechodzi weryfikacji kryptograficznej, ujawnia się jako typowany wyjątek PadesBt, z zachowaniem pierwotnego wyjątku Core jako poprzedniego rzucalnego (previous throwable). NextPDF Pro implementuje obsługę podpisywania PAdES B-T zgodnie z ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 oraz RFC 5816 i jest to zweryfikowane na fixtures; nie deklaruje niezależnej certyfikacji ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu.

SequentialSigner koordynuje podpisywanie wielostronne. Każdy podpisujący to oddzielna rewizja aktualizacji przyrostowej. Pierwszym podpisującym może być podpis certyfikujący z ograniczeniem DocMDP ustawionym przez certifyFirst. PadesWrapper przyjmuje istniejący podpis: fromCades osadza strukturę CMS bezpośrednio, fromXades parsuje dokument XAdES i ponownie wykorzystuje jego rdzeniowy materiał podpisu, a detect automatycznie wybiera według formatu. Ścieżka XAdES ponownie wykorzystuje certyfikat, łańcuch, wartość podpisu i algorytm; nie przenosi kwalifikujących właściwości XAdES.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Typ	Rodzaj	Rola	Stabilność	Od wersji
RemoteSigningSession	class	Dwufazowa sesja podpisywania zdalnego lub asynchronicznego	stable	1.9.0
RemoteSigningConfig	class	Niemutowalna konfiguracja sesji, w tym poziom PAdES i algorytm	stable	1.9.0
SequentialSigner	class	Wielostronne podpisywanie sekwencyjne z obsługą DocMDP	stable	1.9.0
SequentialSigningResult	class	Wynik przebiegu sekwencyjnego: bajty PDF, łańcuch, liczba, kompletność	stable	1.9.0
SigningStrategy	interface	Kontrakt mechanizmu podpisywania wywoływany przez sesję	stable	1.9.0
PadesWrapper	class	Opakowuje istniejący podpis CAdES lub XAdES do osadzenia w PAdES	stable	1.9.0
KmsSignerInterface	interface (SPI)	Kontrakt sterownika HSM i KMS firm trzecich; rozszerza kontrakt modułu HSM z Core	stable	2.1.0
SignatureAlgorithm	enum	Identyfikatory OID algorytmów podpisu Pro i nazwy skrótów	stable	2.1.0
GenerationTimeMasker	class	Maskowanie sterowane regułami stosowane przed zapisem strony	stable	1.9.0
MaskingConfig	class	Niemutowalna konfiguracja maskowania	stable	1.9.0
MaskingRule	class	Pojedyncza reguła maskowania (literał lub PCRE)	stable	1.9.0
MaskingMode	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

Kontrakt SigningStrategy

Strategia operuje na podpisanych atrybutach zakodowanych w DER i zwraca surowe bajty podpisu. To sesja, a nie strategia, składa CMS SignedData. Strategia udostępnia DER certyfikatu podpisującego, DER łańcucha uporządkowanego od liścia do korzenia, OID algorytmu podpisu, nazwę algorytmu skrótu oraz flagę isAsync oznaczającą strategię, której sesja może zostać zserializowana i wznowiona.

SPI KmsSignerInterface

KmsSignerInterface rozszerza kontrakt modułu HSM z Core. Dodaje stabilny providerId na potrzeby wyszukiwania w rejestrze, metodę signWithVersion z jawnym parametrem wersji klucza dla każdego wywołania oraz supportsAlgorithm i supportedAlgorithms, dzięki czemu wywołujący odkrywa zgodność algorytmów przed wywołaniem podpisu. Zarezerwowane wbudowane identyfikatory dostawców to aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli oraz openssl-engine. Sterownik firmy trzeciej musi przestrzennie nazwać swój identyfikator (namespace), aby uniknąć kolizji. Domyślna semantyka wersji klucza różni się w zależności od dostawcy: dostawca rozwiązujący aliasy rozwiązuje aktywny klucz z aliasu, gdy wersja jest null; dostawca wybierający najnowszą włączoną wersję robi to przez swój transport; dostawca, który nie ma serwerowego pojęcia aktywnej wersji, musi użyć wersji przypiętej w swojej konfiguracji i musi zgłosić błąd zarządzania kluczami, gdy ani wywołanie, ani konfiguracja nie przypina wersji. Niepusta wersja przypina tę wersję, a dostawca musi zgłosić błąd zarządzania kluczami, gdy wersja jest nieznana, wyłączona lub unieważniona.

Przypadki brzegowe i pułapki

• Wytworzony podpis nie jest podpisem zweryfikowanym. Walidacja ścieżki przebiega u weryfikatora z jego kotwicami zaufania i sprawdzeniami podstawowych ograniczeń (basic-constraint) — RFC 5280 §6.1. Wytwórca nie może deklarować wyniku.
• Sesja ma starszą trzyatrybutową ścieżkę awaryjną dla syntetycznych bajtów certyfikatu spoza X.509. Strategie produkcyjne zawsze dostarczają prawdziwy DER X.509, więc pełny zestaw atrybutów B-B jest ścieżką produkcyjną. Ścieżka awaryjna istnieje wyłącznie dla historycznej powierzchni testowej mechaniki DER.
• Struktura CMS musi zmieścić się w zarezerwowanej przestrzeni Contents. CMS SignedData B-B z pełnym łańcuchem certyfikatów ma pewien rozmiar; sesja zgłasza błąd przepełnienia, gdy złożone CMS przekracza zarezerwowaną przestrzeń szesnastkową. Odpowiednio wymiaruj zarezerwowaną przestrzeń. Dla B-T osadzony token RFC 3161 (zdominowany przez łańcuch certyfikatów TSA) powiększa CMS; zarezerwowana przestrzeń B-T jest podnoszona automatycznie, a niedowymiarowana skonfigurowana przestrzeń kończy się błędem konfiguracji o typowanym wyjątku (fail closed), zamiast obcinania.
• MaskingConfig::fromArray odrzuca wpis bez użytecznego wzorca łańcuchowego, zamiast przerywać import. Zwaliduj źródło konfiguracji, jeśli ciche odrzucenie jest nie do zaakceptowania.
• Tryb black-box maskowania emituje puste zastąpienie dla dopasowanego fragmentu i usuwa leżący u podstaw tekst. Reguła, która nie dopasowuje wartości, nie maskuje jej; silnik nie deklaruje, że cała wrażliwa treść została znaleziona.
• B-T wymaga podłączonego dostawcy znaczników czasu. Na ścieżce domyślnego dostawcy RFC 3161 z Core skrótem odcisku jest SHA-256; skrót odcisku inny niż SHA-256 na tej ścieżce jest odrzucany błędem konfiguracji o typowanym wyjątku, a nie po cichu degradowany, natomiast dostarczony przez wywołującego dostawca niestandardowy może w sposób uprawniony użyć innego zatwierdzonego skrótu. serialNumber znacznika czasu jest unikalny dla każdego tokenu od danego urzędu znaczników czasu (Time-Stamping Authority), a genTime to chwila UTC, w której token został utworzony — RFC 3161 §2.4.1, §2.4.2. Materiał walidacji długoterminowej B-LT/B-LTA pozostaje sprawą granicy Enterprise; Pro nie wytwarza żadnego DSS, żadnego VRI ani żadnego znacznika czasu dokumentu.
• OCSP unknown to nie good, a świeżość statusu jest ograniczona przez thisUpdate i nextUpdate — RFC 6960 §2.2, §4.2.

Zachowanie w trybie FIPS

Pro wybiera algorytm na podstawie skonfigurowanego algorytmu podpisu i strategii. Gdy skonfigurowany jest względem zwalidowanego zgodnie z FIPS KMS lub HSM, operacja kryptograficzna przebiega w tej zwalidowanej granicy, a zbiór algorytmów to ten, na który ta granica zezwala. NextPDF Pro wykonuje strukturalne składanie CMS i obliczanie skrótu; nie jest zwalidowanym zgodnie z FIPS modułem kryptograficznym i nie formułuje żadnego twierdzenia o certyfikacji FIPS. Wdrożenie wymagające postawy FIPS musi skonfigurować zwalidowany zgodnie z FIPS KMS lub HSM, a profil polityki kryptograficznej FIPS 140-3 jest możliwością Enterprise.

Postawa kontroli eksportu

Ten moduł dotyczy funkcjonalności kryptograficznej; traktuj go jako wrażliwy pod względem bezpieczeństwa we własnym przeglądzie.

Granica Enterprise

NextPDF Pro wytwarza poziom bazowy B-B oraz poziom B-T. Dla B-B sesja składa CMS SignedData z zestawem podpisanych atrybutów B-B i nie stosuje znacznika czasu. Dla B-T dodaje dokładnie jeden signature-time-stamp RFC 3161 jako niepodpisany atrybut CMS obliczony na wartości podpisu cyfrowego dla danego podpisującego — ETSI EN 319 122-1 §5.3. NextPDF Pro implementuje to zgodnie z ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 oraz RFC 5816 i jest to zweryfikowane na fixtures; nie deklaruje niezależnej certyfikacji, zgodności (conformance) ani zgodności (compliance) z ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu.

Poziomy B-LT i B-LTA są możliwościami Enterprise i nie są wytwarzane przez Pro. B-LT i B-LTA dodają Document Security Store oraz znaczniki czasu dokumentu na potrzeby długoterminowej walidacji archiwalnej — ETSI EN 319 142-2 §5.5. Moduł obsługi podpisu wytwarzający te poziomy obsługuje wpisy DSS i znaczniki czasu dokumentu — ETSI EN 319 142-2 §6.3.3.3. RemoteSigningConfig z Pro może nieść poziom powyżej B-T (B-LT lub B-LTA), który żąda Document Security Store, ale Pro nie dostarcza tego wytwórcy i nie działa na jego podstawie; taki poziom jest wartością zadeklarowaną z wyprzedzeniem (forward-declared). Przepływ podpisywania Core rozwiązuje wytwórcę długoterminowego w czasie wykonania przez kontrakt Core, a ten wytwórca jest dostarczany w pakiecie nextpdf/enterprise. We wdrożeniu wyłącznie Pro żądanie B-LT lub B-LTA kończy się błędem (fail closed) z komunikatem nazywającym brakujący komponent Enterprise. Pro nie wytwarza żadnego DSS, żadnego słownika VRI, żadnego znacznika czasu dokumentu ani żadnej pętli archiwalnej i nie formułuje żadnego twierdzenia o walidacji długoterminowej (LTV). Sprzętowe przechowywanie kluczy przez PKCS#11 oraz profil polityki kryptograficznej FIPS 140-3 są również możliwościami Enterprise. Ta strona nie dokumentuje implementacji walidacji długoterminowej Enterprise; opisuje wyłącznie granicę oraz publiczną nazwę pakietu.

Poziom PAdES	Dodaje	Edycja wytwórcy
B-B	Podpis CMS z podpisanymi atrybutami	Core, Pro
B-T	Jeden niepodpisany atrybut signature-time-stamp RFC 3161 na wartości podpisu	Core, Pro
B-LT	Document Security Store z materiałem walidacyjnym	Enterprise (nextpdf/enterprise)
B-LTA	Znaczniki czasu dokumentu dla ważności archiwalnej	Enterprise (nextpdf/enterprise)

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz obsługiwaną 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.

Rozwiązanie awaryjne w Core

Wdrożenie bez uprawnienia Pro zachowuje kontrakt podpisywania Core. Kod zależny od kontraktu SignerInterface z Core nadal podpisuje za pomocą programowego modułu podpisującego CMS na poziomie bazowym B-B. Maskowanie, wykrywanie PII oraz strategie podpisywania zdalnego i przez chmurowy KMS nie są obecne bez pakietu Pro, a wywołanie tych typów jest twardym błędem zależności, a nie cichym brakiem działania (no-op).

Rezydencja danych i ograniczanie ryzyka PII

Powierzchnie maskowania i PII działają w obrębie procesu. Żadna treść dokumentu nie opuszcza hosta na potrzeby maskowania ani wykrywania PII. Strategia chmurowego KMS wysyła do dostawcy skrót podpisanych atrybutów, a nie dokument, na potrzeby operacji podpisywania. Wykrywanie PII odbywa się przez dopasowywanie wzorców dla skonfigurowanych typów i usuwa leżące u podstaw obiekty tekstowe w trybie black-box, co zostało przetestowane. Nie jest to gwarancja kompletnego usunięcia danych osobowych i nie jest to oświadczenie o zgodności regulacyjnej.

Bezpieczna telemetria i czyszczenie logów

Biblioteka zgłasza typowane wyjątki ze strukturalnymi komunikatami. Nie zapisuje treści dokumentu ani wykrytych wartości PII do komunikatów wyjątków ani logów. Wdrożenie logujące wokół ścieżki podpisywania powinno logować pola strukturalne, a nie bajty dokumentu.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Podpis CMS jest przechowywany zakodowany w DER we wpisie Contents słownika podpisu.	ISO 32000-2	§12.8.1
Proces obliczania skrótu komunikatu; podpisane atrybuty niosą content-type i message-digest.	RFC 5652	§5.4
Weryfikator nie może polegać na skrótach obliczonych przez nadawcę; samodzielnie ponownie oblicza i porównuje (proces weryfikacji podpisu).	RFC 5652	§5.6
SignerInfo niesie identyfikator algorytmu skrótu oraz blok podpisanych atrybutów.	RFC 5652	§5
Żądanie znacznika czasu zwraca strukturę TSTInfo.	RFC 3161	§2.4.1
serialNumber znacznika czasu jest unikalny dla każdego tokenu od danego TSA.	RFC 3161	§2.4.2
genTime znacznika czasu to chwila UTC, w której token został utworzony.	RFC 3161	§2.4.2
signature-time-stamp PAdES B-T to niepodpisany atrybut niosący jeden znacznik czasu obliczony na wartości podpisu cyfrowego dla danego podpisującego (Pro wytwarza B-T).	ETSI EN 319 122-1	§5.3
Odcisk (imprint) signature-time-stamp to skrót wartości pola podpisu SignerInfo z wyłączeniem znacznika i długości ASN.1.	ETSI EN 319 122-1	§5.3
Token signature-time-stamp używa OID id-aa-timeStampToken; jego MessageImprint to skrót wartości pola podpisu SignerInfo.	RFC 3161	Appendix A
Po stronie weryfikacji NextPDF wiąże MessageImprint znacznika signature-time-stamp z wartością podpisu SignerInfo i kończy się błędem (fail closed) przy niezgodności, brakującym lub zdublowanym tokenie albo odcisku SHA-1 (ścisła weryfikacja, nie certyfikacja).	RFC 3161	Appendix A
ESSCertIDv2 zastępuje związany z SHA-1 starszy ESSCertID; ścisła ścieżka B-T wymaga ESSCertIDv2.	RFC 5816	§1
Walidacja ścieżki certyfikacji sprawdza podstawowe ograniczenia oraz dane wejściowe ścieżki do kotwicy zaufania.	RFC 5280	§6.1
OCSP raportuje certStatus jako good, revoked lub unknown.	RFC 6960	§2.2
Świeżość statusu OCSP jest ograniczona przez thisUpdate i nextUpdate.	RFC 6960	§4.2
B-LT i B-LTA dodają Document Security Store oraz znaczniki czasu dokumentu na potrzeby walidacji długoterminowej (granica Enterprise).	ETSI EN 319 142-2	§5.5
Moduł obsługi podpisu wytwarzający poziomy długoterminowe obsługuje wpisy DSS i znaczniki czasu dokumentu (granica Enterprise).	ETSI EN 319 142-2	§6.3.3.3

Wszystkie klauzule są sparafrazowane. NextPDF nie powiela tekstu normatywnego. Po autorytatywne brzmienie sięgnij do opublikowanych standardów. NextPDF Pro implementuje obsługę podpisywania PAdES B-T zgodnie z ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 oraz RFC 5816 i jest to zweryfikowane na fixtures. ETSI EN 319 142-1 (część dotycząca poziomów bazowych PAdES) leży poza przywołanym zbiorem dowodów; NextPDF Pro nie deklaruje zatem niezależnej certyfikacji, zgodności (conformance) ani zgodności (compliance) z ETSI EN 319 142-1 i nie deklaruje mocy prawnej dokumentu. Ta strona opisuje wytwarzaną strukturę, standardy, które implementuje obsługa B-T, oraz granicę Enterprise B-LT/B-LTA, a nie certyfikowany poziom zgodności.

Zobacz także

• Core signing — moduł podpisujący CMS, znacznik czasu RFC 3161, walidacja ścieżki RFC 5280, OCSP i CRL.
• PAdES clause map — B-B, B-T, B-LT, B-LTA w poszczególnych edycjach.
• Security (przegląd funkcjonalności) — publiczna strona funkcjonalności bezpieczeństwa Pro.
• CMS · PAdES · RFC 3161 timestamp · KMS · DSS — terminy ze słownika.