Security — HSM, PKCS#11 i tryb FIPS

W skrócie

NextPDF Enterprise dodaje ścieżkę podpisywania tokenem sprzętowym PKCS#11 oraz politykę kryptograficzną w trybie FIPS na powierzchni bezpieczeństwa Core i Pro. Ta strona przedstawia zachowanie, granice oraz jawną postawę wobec certyfikacji FIPS i pieczy nad kluczem.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Przegląd koncepcyjny

Powierzchnia bezpieczeństwa Enterprise ma trzy części: moduł podpisujący tokenem sprzętowym, politykę kryptograficzną w trybie FIPS oraz zabezpieczenie autotestem przy uruchomieniu.

Moduł podpisujący tokenem sprzętowym adaptuje token PKCS#11 — kartę inteligentną, urządzenie USB lub HSM podłączony do sieci. Moduł podpisujący lokalizuje certyfikat oraz klucz prywatny na tokenie według etykiety. Następnie prosi token o obliczenie podpisu. Klucz prywatny nie opuszcza granicy tokenu; operacja działa wewnątrz tokenu. Operacja podpisywania tokenu, sesja oraz logowanie użytkownika są zgodne z PKCS#11 v3.1 §5. Ścieżka HSM wymaga rozszerzenia PHP ext-pkcs11. To rozszerzenie nie jest częścią standardowego PHP. Zainstaluj je osobno. Użyj kontroli dostępności przed konstrukcją modułu podpisującego.

Polityka kryptograficzna w trybie FIPS ogranicza wybory kryptograficzne do zatwierdzonego zbioru. Ma dwa ustawienia wstępne. Ustawienie wstępne strict zezwala na skróty SHA-256, SHA-384 oraz SHA-512; identyfikatory OID podpisu RSA i ECDSA z tymi skrótami; szyfrowanie AES-256-CBC; oraz minimalne rozmiary kluczy RSA 2048 i EC 256. Ustawienie wstępne standard jest takie samo, lecz dodatkowo zezwala na AES-128-CBC dla starszej interoperacyjności. Zabezpieczenie wykonawcze opakowuje politykę. Zabezpieczenie sprawdza każdy skrót, identyfikator OID podpisu, algorytm szyfrowania oraz siłę klucza przed uruchomieniem operacji. Niedozwolony wybór zgłasza typowane naruszenie i zatrzymuje operację. Ścieżka działa w trybie fail-closed: polityka nigdy nie rozluźnia się sama i nigdy nie zastępuje algorytmu słabszym. Minimalna długość klucza RSA jest zgodna z NIST SP 800-131A Rev.2 §3. Dobór krzywej i skrótu ECDSA jest zgodny z FIPS 186-5 §6.1.1.

Zabezpieczenie autotestem przy uruchomieniu uruchamia baterię testów znanej odpowiedzi raz przy starcie procesu. Bateria obejmuje zatwierdzone funkcje skrótu, MAC, szyfrowania, podpisu oraz generowania bitów losowych. Jeśli którykolwiek test zawiedzie, zabezpieczenie FIPS Enterprise wchodzi w stan błędu i odmawia usług kryptograficznych do czasu zresetowania. Wynik jest buforowany na czas życia procesu; dostępne jest ponowne uruchomienie na żądanie. Kategoria autotestu oraz wyzwalacz testu warunkowego są zgodne z ISO/IEC 19790:2025 §7.10 oraz §7.10.3.

Dlaczego działa właśnie tak

Kluczową decyzją jest utrzymanie klucza prywatnego wewnątrz granicy tokenu oraz sprawienie, by polityka kryptograficzna działała w trybie fail-closed. Moduł podpisujący, który mógłby wyeksportować klucz lub po cichu przejść na słabszy algorytm, zniweczyłby gwarancję, dla której istnieje HSM. Dlatego moduł podpisujący prosi token o obliczenie podpisu na miejscu, a zabezpieczenie w trybie FIPS odrzuca każdy skrót, OID lub siłę klucza spoza zatwierdzonego ustawienia wstępnego przed uruchomieniem operacji. Autotest przy uruchomieniu rozszerza tę samą postawę na start: niezweryfikowany moduł odmawia usługi, zamiast podpisywać na nieprzetestowanych prymitywach. Rezultatem jest granica, o której można rozumować i w której piecza nad kluczem należy do operatora i tokenu, a nie do tego oprogramowania.

Kontekst projektowy: Podpisywanie oparte na HSM.

Powierzchnia API

Powierzchnia publiczna	Typ	Cel	Stabilność	Od wersji
Moduł podpisujący tokenem PKCS#11	klasa (implementuje Core HsmSignerInterface)	Podpisz tokenem PKCS#11; klucz pozostaje na tokenie	stabilny	1.0.0
Polityka kryptograficzna FIPS	klasa (implementuje Core CryptoPolicyInterface)	Ustawienie wstępne dozwolonego algorytmu i siły klucza	stabilny	1.9.0
Zabezpieczenie trybu FIPS	klasa	Asercjonuje, że skrót, OID podpisu, algorytm szyfrowania lub siła klucza są dozwolone	stabilny	1.9.0
Zabezpieczenie rozruchowe FIPS	klasa	Uruchom i buforuj autotest przy uruchomieniu; asercjonuj, że moduł jest operacyjny	stabilny	3.2.0
Moduł podpisujący OpenSSL CLI / engine	klasa (implementuje HsmSignerInterface)	Podpisz przez silnik OpenSSL lub OpenSSL CLI dla tokenów opartych na silniku	stabilny	1.0.0

Konstruktor modułu podpisującego tokenem przyjmuje ścieżkę biblioteki PKCS#11, numer slotu, kod PIN tokenu, etykietę certyfikatu oraz opcjonalną osobną etykietę klucza. Parametr PIN jest oznaczony jako wrażliwy; nie jest logowany ani serializowany. Moduł podpisujący udostępnia również certyfikat modułu podpisującego oraz łańcuch certyfikatów w formie DER. Autorytatywnym kontraktem parametrów i typów jest opublikowana referencja API pakietu nextpdf/enterprise; traktuj tę referencję — a nie tę stronę — jako kontrakt.

Przykład kodu — Szybki start

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Construct a FIPS-mode guard and assert a hash is allowed

use NextPDF\Enterprise\Security\Fips\FipsCryptoPolicy;
use NextPDF\Enterprise\Security\Fips\FipsModeGuard;

$guard = new FipsModeGuard(FipsCryptoPolicy::strict());

// Throws a typed FIPS violation if the algorithm is not approved.
$guard->assertHashAllowed('sha256');
$guard->assertKeyStrengthAllowed('rsa', 2048);

Przykład kodu — Produkcja

Run the power-on self-test at container boot, then gate signing

use NextPDF\Enterprise\Security\Fips\FipsBootGuard;
use NextPDF\Enterprise\Security\Fips\FipsSelfTest;

// At application bootstrap (one self-test cycle per worker process):
$bootGuard = new FipsBootGuard(new FipsSelfTest());
$bootGuard->assertOperational(); // throws on a known-answer-test failure
$container->set(FipsBootGuard::class, $bootGuard);

// The PKCS#11 token signer is only available when ext-pkcs11 is loaded.
// Check availability before you construct the signer. The PIN is a secret;
// supply it from your secret manager, never from source or logs.

Pełna lista argumentów konstruktora, typy wyjątków oraz konstrukcja modułu podpisującego tokenem PKCS#11 są udokumentowane w szczegółowej referencji bezpieczeństwa Enterprise.

Przypadki brzegowe i pułapki

• Konstruktor modułu podpisującego tokenem PKCS#11 zgłasza typowany wyjątek operacji, gdy ext-pkcs11 nie jest załadowane. Najpierw sprawdź dostępność.
• Moduł podpisujący tokenem buforuje jeden moduł PKCS#11 na ścieżkę biblioteki na proces. Spełnia to regułę „inicjalizuj raz na moduł” interfejsu tokenu.
• Mechanizmy tokenu ECDSA zwracają surowy podpis. Moduł podpisujący konwertuje go do formy zakodowanej w DER na potrzeby interoperacyjności z PDF i OpenSSL.
• Zabezpieczenie FIPS domyślnie odrzuca nieznany typ klucza. Nierozpoznany typ klucza nie jest po cichu akceptowany.
• Ścieżka podpisywania postkwantowego jest eksperymentalna, włączana opcjonalnie i domyślnie wyłączona. Standardowe profile długoterminowej archiwizacji PAdES nie rozpoznają jeszcze pakietów postkwantowych. Nie włączaj jej dla produkcyjnych podpisów AdES.

Wydajność

Kontrole zabezpieczenia FIPS to wyszukiwania w mapie skrótów w czasie stałym. Autotest przy uruchomieniu działa raz na proces; jego koszt jest amortyzowany na czas życia procesu, a nie na wywołanie podpisywania. Operacja podpisywania PKCS#11 dodaje jeden obieg do tokenu. HSM podłączony do sieci dodaje opóźnienie sieciowe tego obiegu.

Uwagi dotyczące bezpieczeństwa

• Ścieżka podpisywania działa w trybie fail-closed. Niepowodzenie prymitywu lub luka w polityce zgłasza typowany wyjątek. Ścieżka nigdy nie obniża po cichu poziomu do słabszego algorytmu.
• Parametr PIN tokenu jest oznaczony jako wrażliwy. Nie jest logowany ani serializowany.
• Klucz prywatny dla tokenu PKCS#11 pozostaje na tokenie. Operacja podpisywania działa wewnątrz granicy tokenu.
• Autotest przy uruchomieniu wprowadza zabezpieczenie FIPS Enterprise w stan błędu przy niezgodności testu znanej odpowiedzi i odmawia usług kryptograficznych do czasu zresetowania.
• Użycie AES-GCM wymaga unikalnego wektora inicjującego dla każdego klucza, zgodnie z NIST SP 800-38D §5.

Rezydencja danych i środki ograniczające PII

Kod podpisywania oraz polityki FIPS działa w procesie. Żadna treść dokumentu nie opuszcza hosta na potrzeby kontroli polityki FIPS ani autotestu przy uruchomieniu. Token PKCS#11 otrzymuje dane do podpisania, a nie niepowiązaną treść dokumentu. HSM podłączony do sieci otrzymuje te dane kanałem sieciowym, który konfigurujesz. Materiał klucza pozostaje wewnątrz granicy tokenu lub HSM.

Bezpieczna telemetria i czyszczenie logów

PIN tokenu to wrażliwy parametr konstruktora i jest wykluczony z logów i serializacji. Nie dodawaj kodu PIN, etykiety tokenu ani materiału klucza do własnych logów aplikacji. Traktuj wszystkie poświadczenia tokenu jako sekrety w swojej polityce logowania i śledzenia.

Model zagrożeń

To granica kryptograficzna, więc model zagrożeń jest jawny. Dane do podpisania są przekazywane do tokenu; token przechowuje klucz. Błąd tokenu lub HSM zgłasza typowany wyjątek; moduł podpisujący nie tworzy wyniku niepodpisanego ani częściowo podpisanego. Ochrona klucza zależy od tokenu lub HSM, od wdrożenia oraz od operatora — a nie wyłącznie od tego oprogramowania. Zobacz granicę wdrożenia.

Zgodność

• Model autotestu przy uruchomieniu oraz testu warunkowego jest zgodny z ISO/IEC 19790:2025 §7.10 oraz §7.10.3.
• Minimalna długość klucza podpisu RSA jest zgodna z NIST SP 800-131A Rev.2 §3.
• Zatwierdzony dobór krzywej i skrótu ECDSA jest zgodny z FIPS 186-5 §6.1.1.
• Operacja podpisywania tokenem PKCS#11 oraz logowanie sesji są zgodne z PKCS#11 v3.1 §5.
• Odpowiedzialność za ochronę klucza jest zgodna z NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Unikalność wektora inicjującego AES-GCM jest zgodna z NIST SP 800-38D §5.

Każde źródło normatywne jest parafrazowane. Na tej stronie nie odtwarza się żadnego tekstu normatywnego. Ta strona dotyczy kryptograficznego podpisywania.

Zachowanie w trybie FIPS

Polityka trybu FIPS ogranicza wybory kryptograficzne do opisanego powyżej zatwierdzonego zbioru. Po skonfigurowaniu z dostawcą OpenSSL zwalidowanym zgodnie z FIPS bazowy prymityw działa w tej zwalidowanej granicy. Sam NextPDF Enterprise wykonuje montaż strukturalny, obliczanie skrótu oraz egzekwowanie polityki.

NextPDF Enterprise nie jest modułem kryptograficznym zwalidowanym zgodnie z FIPS i nie wysuwa żadnej deklaracji certyfikacji FIPS. NextPDF Enterprise działa w trybie zgodnym z FIPS wyłącznie wtedy, gdy jest skonfigurowany z dostawcą kryptografii zwalidowanym zgodnie z FIPS — na przykład dostawcą OpenSSL zwalidowanym zgodnie z FIPS — lub z HSM zwalidowanym zgodnie z FIPS. Polityka trybu FIPS wspomaga zgodność; nie jest certyfikacją.

Granica edycji

NextPDF Core dostarcza programowy moduł podpisujący, konsumpcję znaczników czasu RFC 3161, walidację ścieżki RFC 5280 oraz sprawdzanie unieważnień OCSP i CRL. Core tworzy poziomy PAdES B-B i B-T. NextPDF Pro dodaje maskowanie, wykrywanie PII w warstwie tekstowej, wielostronne podpisywanie sekwencyjne oraz zdalne i chmurowe strategie podpisywania KMS (AWS KMS, GCP Cloud KMS, Azure Key Vault). NextPDF Pro nie zapewnia ścieżki tokenu sprzętowego PKCS#11 i nie zapewnia profilu polityki kryptograficznej w trybie FIPS. Moduł podpisujący tokenem sprzętowym PKCS#11, profil polityki kryptograficznej w trybie FIPS, zabezpieczenie autotestem przy uruchomieniu oraz producent PAdES B-LT i B-LTA są dostarczane wyłącznie w pakiecie nextpdf/enterprise. Wdrożenie bez uprawnienia Enterprise nie ładuje klas Enterprise.

Rozwiązanie zastępcze Pro

We wdrożeniu wyłącznie z Pro obsługiwaną ścieżką podpisywania sprzętowego i chmurowego jest strategia chmurowego KMS Pro: chmurowy KMS lub KMS oparty na HSM przechowuje klucz, a Pro wysyła do dostawcy skrót atrybutów podpisanych, a nie dokument. Pro zapewnia integrację KMS, a nie fabrykę tokenu PKCS#11 Enterprise ani profil w trybie FIPS. Konfiguracja żądająca B-LT, B-LTA, tokenu PKCS#11 lub profilu w trybie FIPS we wdrożeniu wyłącznie z Pro kończy się w trybie fail-closed z komunikatem wskazującym brakujący komponent Enterprise. Zobacz Security — NextPDF Pro, aby poznać powierzchnię podpisywania Pro.

Rozwiązanie zastępcze Core

We wdrożeniu wyłącznie z Core programowy moduł podpisujący tworzy PAdES B-B i B-T z kluczem lokalnym lub kluczem dostarczonym przez kontrakt strategii podpisywania Core. Core nie ma ścieżki tokenu sprzętowego ani profilu w trybie FIPS. Zobacz Security — NextPDF Core.

Uwaga o granicy Enterprise

Integracja tokenu PKCS#11, jej odwzorowanie mechanizmów oraz obsługa sesji są opisane wyłącznie na poziomie zachowania. Wewnętrzna tabela odwzorowania mechanizmów, wewnętrzna logika odzyskiwania sesji oraz materiał migracji postkwantowej są poza zakresem powierzchni publicznej i nie są tutaj odtwarzane.

Granica wdrożenia

NextPDF Enterprise integruje się z tokenem PKCS#11, HSM lub KMS. Sam nie przechowuje, nie generuje ani nie gwarantuje bezpieczeństwa klucza podpisującego. Bezpieczeństwo klucza zależy od tokenu, HSM lub KMS, od wdrożenia oraz od operatora — a nie wyłącznie od NextPDF Enterprise. Operator odpowiada za dostarczanie tokenów, obsługę kodu PIN, konfigurację slotu, ochronę sieciową dla HSM podłączonego do sieci oraz konfigurację zaufania. Odpowiedzialność za ochronę klucza jest zgodna z NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise nie ujawnia w tej dokumentacji obsługi kodu PIN tokenu, wewnętrznych mechanizmów konfiguracji slotu ani materiału poświadczeń dostawcy.

Granica zgodności prawnej

Dotyczy kryptograficznego podpisywania oraz integracji ze sprzętowym modułem bezpieczeństwa. Polityka trybu FIPS to funkcja wspomagająca zgodność. Nie jest opinią prawną ani certyfikacją. W sprawie obowiązków regulacyjnych skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Kontrakt zachowania

• Zabezpieczenie FIPS asercjonuje każdy skrót, identyfikator OID podpisu, algorytm szyfrowania oraz siłę klucza względem aktywnego ustawienia wstępnego i zgłasza typowane naruszenie przy niedozwolonym wyborze.
• Autotest przy uruchomieniu działa raz na proces i odmawia usług kryptograficznych przy niepowodzeniu testu znanej odpowiedzi do czasu zresetowania.
• Moduł podpisujący tokenem PKCS#11 wymaga ext-pkcs11; zgłasza typowany wyjątek operacji, gdy rozszerzenie jest nieobecne.
• Ścieżka podpisywania działa w trybie fail-closed i nigdy nie zastępuje algorytmu słabszym.

Zobacz też

• Security — NextPDF Enterprise (szczegółowa referencja)
• Security — NextPDF Pro
• Signature — NextPDF Enterprise
• Accelerator — NextPDF Enterprise
• Security — NextPDF Core
• PAdES · HSM · PKCS#11 · tryb FIPS · KMS — terminy glosariusza.