Enterprise edycja

FIPS 140 — szczegółowa referencja

W skrócie

Ta strona to dogłębna dokumentacja modułu FIPS 140 w NextPDF Enterprise. Moduł jest funkcją polityki i testów samosprawdzających. Ogranicza wybory kryptograficzne do zgodnej z FIPS listy dozwolonych, uruchamia po włączeniu baterię testów znanej odpowiedzi (known-answer) i wstrzymuje wyjście kryptograficzne, gdy bateria zawiedzie. NextPDF nie jest zwalidowanym pod kątem FIPS 140 modułem kryptograficznym, nie posiada żadnej certyfikacji ani jej nie nadaje. Wsparcie nie równa się zgodności, a zgodność nie równa się certyfikacji. Wdrożenie zgodne z FIPS wymaga dodatkowo zwalidowanego pod kątem FIPS dostawcy kryptografii dostarczonego przez operatora.

Dostępność i licencjonowanie

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

Publiczna powierzchnia API

Wszystkie symbole znajdują się w NextPDF\Enterprise\Security\Fips, z wyjątkiem FipsBootstrap w NextPDF\Enterprise\Bootstrap.

Symbol	Parametry	Domyślne zachowanie	Zwraca	Rzuca lub kończy się niepowodzeniem z	Uwagi
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (wszystkie domyślnie `null`)	Uruchamia baterię po włączeniu jednorazowo przy starcie; domyślnie stosuje politykę ścisłą	`FipsModeGuard`	`FipsModuleErrorStateException` przy każdym niepowodzeniu testu po włączeniu	Korzeń kompozycji; ścieżka audytu wyłączona, gdy `$auditLogger` jest `null`
`FipsBootstrap::lazy()`	Tak samo jak `boot()`	Odracza baterię do pierwszej asercji granicznej	`FipsModeGuard`	Brak w chwili wywołania; pierwsza asercja może rzucić `FipsModuleErrorStateException`	Moduł pozostaje `PRE_OPERATIONAL` do pierwszej asercji
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Uruchamia moduł, a następnie opakowuje strażnika dla punktów kontrolnych podpisującego	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` przy każdym niepowodzeniu testu po włączeniu	Deleguje do `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Uruchamia baterię na żądanie i podsumowuje ją	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Nie rzuca; niepowodzenia pojawiają się w `failed`	Do punktów końcowych kondycji dla administratora i użycia w CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Ustawienie FIPS 140-3: SHA-256/384/512; zatwierdzone OID-y RSA, RSASSA-PSS, ECDSA; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Brak	Konstruktor jest prywatny; ustawienia są jedynym wejściem
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Ustawienie FIPS 140-2: zestaw ścisły plus `aes-128-cbc`	`self`	Brak	Wyłącznie dla interoperacyjności ze starszymi rozwiązaniami
`FipsCryptoPolicy::assertPreOperational()`	Brak	Uruchamia lub odtwarza zatrzaśnięty wynik baterii po włączeniu	`void`	`FipsModuleErrorStateException`, gdy dowolny test po włączeniu zawiedzie	Sterowana przez szew egzekwowania Core przed pierwszą operacją
Powierzchnia zapytań `FipsCryptoPolicy`	Dane wejściowe `string` / `int`	Sprawdzenia przynależności do listy dozwolonych; nieznany typ klucza jest odrzucany	`bool` / `string`	Brak	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Opakowuje politykę granicami w stylu assert	—	Brak	Bez `$bootGuard` nie ma bramki testu samosprawdzającego; kompozycja produkcyjna ją dostarcza
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Najpierw katalog wykluczeń, potem lista dozwolonych	`void`	`FipsViolationException`; `FipsModuleErrorStateException`, gdy podłączony jest strażnik startowy	Zapis audytu poprzedza każdy `FipsViolationException`
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Najpierw katalog wykluczeń, potem lista dozwolonych	`void`	Tak samo jak powyżej	OID-y są dopasowywane dokładnie
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Najpierw katalog wykluczeń, potem lista dozwolonych	`void`	Tak samo jak powyżej	Nazwy są porównywane małymi literami
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Najpierw katalog wykluczeń, potem minima polityki	`void`	Tak samo jak powyżej	Nieznany typ klucza jest odrzucany
`FipsModeGuard::getPolicy()`	Brak	Zwraca opakowaną politykę	`CryptoPolicyInterface`	Brak	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Przechowuje baterię; nie uruchamia jej	—	Brak	Jeden cykl po włączeniu na instancję
`FipsBootGuard::report()`	Brak	Uruchamia baterię jednorazowo, buforuje raport, zatrzaskuje przy błędzie	`FipsSelfTestReport`	Brak	Pierwsze wywołanie uruchamia testy
`FipsBootGuard::rerun()`	Brak	Wymusza świeży przebieg; przebieg z błędem zatrzaskuje proces	`FipsSelfTestReport`	Brak	Test samosprawdzający na żądanie; nie ścieżka odzyskiwania po błędzie
`FipsBootGuard::assertOperational()`	Brak	Potwierdza, że moduł jest operacyjny; trwałe w obrębie procesu	`void`	`FipsModuleErrorStateException`	Czysta instancja i tak rzuca, gdy proces zatrzasnął błąd
`FipsBootGuard::status()`	Brak	Zgłasza zbuforowany status	`FipsSelfTestStatus`	Brak	`ERROR` przy zatrzaśnięciu; `PRE_OPERATIONAL`, gdy nigdy nie uruchomiono
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Używa platformowych `hash()` i `random_bytes()`	—	Brak	Istnieją nadpisania dla deterministycznych testów niepowodzenia
`FipsSelfTest::run()`	Brak	Wykonuje pełną baterię; nigdy nie skraca przebiegu	`FipsSelfTestReport`	Brak	Niepowodzenia trafiają do raportu, nie do wyjątków
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Niezmienny agregat jednego przebiegu	—	`assertOperational()` rzuca `FipsModuleErrorStateException` w stanie błędu	Także `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Niezmienny wynik pojedynczego testu	—	Brak	`kind` to `KAT`, `PWCT` lub `HEALTH`; także `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum oparty na string	—	Brak	Przypadki `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Opakowuje strażnika z bramką startową dla punktów kontrolnych podpisywania	—	Brak	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Rozwiązuje OID i siłę klucza, następnie deleguje do strażnika	`void`	`FipsViolationException` (nieznany algorytm, niezatwierdzony skrót PSS, niemożliwy do udowodnienia klucz lub odmowa polityki); `FipsModuleErrorStateException` poprzez strażnika	Wyłącznie ścieżka generowania; weryfikacja nigdy tędy nie przechodzi
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Opakowuje rejestrator PSR-3 i tę samą politykę, którą egzekwuje strażnik	—	Brak	Zapisane decyzje nie mogą się rozejść z egzekwowanymi
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Dane wejściowe `string` / `int` na decyzję	Rejestruje ALLOW na poziomie INFO i DENY na poziomie WARNING	`bool` (true, gdy dozwolone)	Brak	Ustrukturyzowany kontekst: nazwa polityki, element, decyzja
`FipsTransitioningAlgorithms`	Dane wejściowe `string` / `int`	Statyczny katalog wykluczeń SP 800-131A Rev.2	`bool` / `list<string>`	Brak	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, a także `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Typowane naruszenie polityki z publicznymi polami readonly	—	—	Podtyp `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Odmowa stanu błędu niosąca wyniki testów zakończonych niepowodzeniem	—	—	Podtyp `NextPDF\Exception\NextPdfException`

public static function boot(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function lazy(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null, ?LoggerInterface $auditLogger = null): FipsModeGuard
public static function signatureEnforcer(?CryptoPolicyInterface $policy = null, ?FipsSelfTest $selfTest = null): FipsSignatureEnforcer
public static function selfTestReport(?FipsSelfTest $selfTest = null): array

public static function strict(?FipsSelfTest $selfTest = null): self
public static function standard(?FipsSelfTest $selfTest = null): self
public function assertPreOperational(): void
public function isHashAlgorithmAllowed(string $algorithm): bool
public function isSignatureAlgorithmAllowed(string $oid): bool
public function isEncryptionAlgorithmAllowed(string $algorithm): bool
public function isKeyStrengthAllowed(string $keyType, int $bitLength): bool
public function getPreferredHashAlgorithm(): string
public function getName(): string

public function __construct(private CryptoPolicyInterface $policy, private ?FipsBootGuard $bootGuard = null, private ?FipsAuditLogger $auditLogger = null)
public function assertHashAllowed(string $algorithm): void
public function assertSignatureAlgorithmAllowed(string $oid): void
public function assertEncryptionAllowed(string $algorithm): void
public function assertKeyStrengthAllowed(string $keyType, int $bitLength): void
public function getPolicy(): CryptoPolicyInterface

public function __construct(private readonly FipsSelfTest $selfTest)
public function report(): FipsSelfTestReport
public function rerun(): FipsSelfTestReport
public function assertOperational(): void
public function status(): FipsSelfTestStatus

public function __construct(?callable $randomBytesProvider = null, ?callable $hashProvider = null)
public function run(): FipsSelfTestReport

public function __construct(private readonly FipsModeGuard $guard)
public function assertSignatureGenerationAllowed(string $algorithm, string $certificatePem): void

public function __construct(private CryptoPolicyInterface $policy, private LoggerInterface $logger)
public function logHashOperation(string $algorithm): bool
public function logSignatureOperation(string $oid): bool
public function logEncryptionOperation(string $algorithm): bool
public function logKeyStrengthCheck(string $keyType, int $bitLength): bool

public static function isHashDisallowed(string $algorithm): bool
public static function isSignatureOidDisallowed(string $oid): bool
public static function isEncryptionDisallowed(string $algorithm): bool
public static function isKeyStrengthDisallowed(string $keyType, int $bitLength): bool
public static function disallowedHashes(): array
public static function disallowedSignatureOids(): array
public static function disallowedEncryption(): array

public function __construct(public FipsSelfTestStatus $status, public array $results, public array $failedResults)
public function isOperational(): bool
public function isError(): bool
public function assertOperational(): void

// FipsSelfTestResult
public function __construct(public string $algorithm, public string $kind, public bool $passed, public string $message = '')
public function isPassed(): bool
public function isFailed(): bool

// FipsSelfTestStatus
enum FipsSelfTestStatus: string
{
    case PRE_OPERATIONAL = 'pre_operational';
    case OPERATIONAL = 'operational';
    case ERROR = 'error';
}

Kontrakt zachowania

Lista dozwolonych polityki jest miarodajną decyzją. FipsTransitioningAlgorithms dodaje nad nią jawną warstwę wykluczeń SP 800-131A Rev.2 na potrzeby jednoznacznych dla audytu komunikatów o odrzuceniu. Warstwa wykluczeń nigdy nie poszerza ani nie nadpisuje listy dozwolonych.
FipsCryptoPolicy::strict() zezwala na SHA-256, SHA-384 i SHA-512; OID-y podpisów RSA PKCS#1 v1.5, RSASSA-PSS i ECDSA powiązane z tymi skrótami; aes-256-cbc i aes-256-gcm; oraz progi kluczy RSA 2048, EC 256, Ed25519 256. standard() zezwala dodatkowo na aes-128-cbc.
Bateria po włączeniu obejmuje: testy KAT skrótów SHA-256/384/512, KAT HMAC-SHA-256, KAT szyfrowania i deszyfrowania AES-256-CBC, KAT znacznika AES-256-GCM, test spójności parami ECDSA P-256 oraz kontrolę kondycji DRBG. FipsSelfTest::run() zawsze wykonuje każdy test i nigdy nie skraca przebiegu, więc raport jest kompletny jako dowód audytowy.
Wiersz DRBG jest ciągłym testem kondycji (długość losowania plus odrębne kolejne losowania), a nie testem znanej odpowiedzi. Obowiązek znanej odpowiedzi dla DRBG jest delegowany do bazowego, zwalidowanego pod kątem FIPS dostawcy, którego dostarcza operator.
Stan błędu jest trwały w obrębie procesu. Pierwszy raport ERROR zaobserwowany przez dowolny FipsBootGuard zatrzaskuje cały proces. Świeża instancja strażnika lub polityki nie może wyprać błędu, a późniejszy pomyślny ponowny przebieg go nie usuwa. Tylko ponowne uruchomienie procesu (prawdziwy cykl zasilania) resetuje ten stan.
FipsCryptoPolicy implementuje NextPDF\Contracts\CryptoPolicyInterface i NextPDF\Contracts\PreOperationalSelfTestInterface. Skonfigurowany jako polityka kryptograficzna Core, szew egzekwowania Core steruje assertPreOperational() przed wytworzeniem pierwszego podpisu lub szyfrogramu.
FipsSignatureEnforcer kontroluje wyłącznie ścieżkę generowania. Weryfikacja już wygenerowanych podpisów jest użyciem starszego typu (legacy) w rozumieniu SP 800-131A Rev.2 i nigdy nie przechodzi przez egzekutor.
Gdy podłączony jest rejestrator audytu, każda granica assert emituje jeden zapis ALLOW (INFO) lub DENY (WARNING) przed jakimkolwiek rzuceniem naruszenia polityki. Każda odmowa FipsViolationException jest zatem udokumentowana w ścieżce. Bramka strażnika startowego działa jako pierwsza, więc odmowa stanu błędu jest zgłaszana przed zapisem audytu. FipsAuditLogger korzysta z tej samej polityki, którą egzekwuje strażnik, więc zapisane decyzje nie mogą się rozejść z egzekwowanymi.

Przypadki brzegowe i tryby awarii

Nieznany typ klucza jest odrzucany przez obie warstwy: polityka zwraca false, a katalog traktuje go jako niedozwolony.
Identyfikator algorytmu podpisującego, którego egzekutor nie potrafi odwzorować na OID podpisu, jest odrzucany w trybie fail-closed z FipsViolationException.
Każdy wariant RSASSA-PSS współdzieli OID 1.2.840.113549.1.1.10, więc sam OID nie może udowodnić skrótu. Egzekutor wiąże obowiązujący skrót jawnie i odrzuca każdy token PSS, którego skrót nie jest SHA-256/384/512.
Certyfikat, którego nie da się sparsować lub którego długość bitowa klucza publicznego jest niedostępna, jest odrzucany jako key:unprovable.
W środowisku wykonawczym bez asymetrycznych prymitywów OpenSSL test spójności parami ECDSA rejestruje niepowodzenie, a nie pominięcie, i moduł przechodzi w ERROR.
Dwa identyczne kolejne 32-bajtowe losowania zawodzą kontrolę kondycji DRBG (wykrycie zablokowanego wyjścia) i wymuszają ERROR.
FipsModeGuard skonstruowany bez strażnika startowego wykonuje wyłącznie sprawdzenia polityki i nie ma bramki testu samosprawdzającego. Kompozycja produkcyjna przechodzi przez FipsBootstrap, który zawsze podłącza bramkę.
Nazwy skrótów i szyfrów są porównywane małymi literami; OID-y podpisów są dopasowywane dokładnie, bez normalizacji.
Po FipsBootstrap::lazy() moduł pozostaje PRE_OPERATIONAL do czasu, aż pierwsza granica assert uruchomi baterię. PRE_OPERATIONAL jest w chwili asercji traktowany jako nieoperacyjny.

Zachowanie w trybie FIPS

Ten moduł jest samą powierzchnią trybu FIPS. Gdy moduł jest w stanie błędu oraz gdy trwają testy samosprawdzające przed operacyjne, wyjście kryptograficzne jest wstrzymane: każda granica assert rzuca FipsModuleErrorStateException przed wytworzeniem jakiegokolwiek podpisu lub szyfrogramu (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() i FipsBootstrap::selfTestReport() udostępniają ten stan, tak aby operator mógł stwierdzić, że moduł przeszedł w stan błędu (ISO/IEC 19790:2025 §7.10.3). Te zachowania są deklaracjami dotyczącymi możliwości kodu NextPDF, a nie deklaracją walidacji: granicą modułu, którą waliduje FIPS 140, jest dostarczony przez operatora dostawca kryptografii, a nie NextPDF.

Zgodność

Deklaracja	Standard	Klauzula
FIPS 140-3 opiera się na ISO/IEC 19790 i ISO/IEC 24759; ta strona cytuje zatem klauzule ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
Wyjście jest wstrzymane w stanie błędu i podczas testów samosprawdzających przed operacyjnych.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Test znanej odpowiedzi porównuje obliczony wynik ze znanym oczekiwanym wyjściem; bateria realizuje ten kształt.	ISO/IEC 19790:2025	§7.10.4
Operator może stwierdzić stan błędu poprzez wyjście statusu.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Operatorzy mogą inicjować testy samosprawdzające na żądanie w celu okresowego testowania; zapewniają to `rerun()` i `selfTestReport()`.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 jest niedozwolony do generowania nowych podpisów cyfrowych; katalog wykluczeń go odrzuca.	NIST SP 800-131A Rev.2	§9
Generowanie podpisu poniżej siły 112 bitów (RSA < 2048, rząd ECDSA < 224) jest niedozwolone; progi kluczy to egzekwują.	NIST SP 800-131A Rev.2	§3 Table 2
Weryfikacja już wygenerowanych podpisów SHA-1 jest użyciem starszego typu (legacy); nie przechodzi przez bramkę generowania.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Wszystkie klauzule są parafrazowane; nie reprodukuje się żadnego tekstu normatywnego. NextPDF nie składa żadnej deklaracji certyfikacji FIPS 140. Moduł dostosowuje swoje zachowanie do cytowanych klauzul jako funkcja wspomagająca zgodność. To, czy dane wdrożenie jest zgodne z FIPS, zależy od zwalidowanego dostawcy operatora, definicji granicy modułu i programu zgodności — a nie od samego NextPDF.

Uwagi programistyczne

Deterministyczne testy niepowodzenia wstrzykują uszkodzonych dostawców przez konstruktor FipsSelfTest lub przez parametry $selfTest w FipsCryptoPolicy::strict(), standard() oraz metodach FipsBootstrap.
Zatrzask trwałego w obrębie procesu stanu błędu ma wewnętrzny, przeznaczony wyłącznie do testów hak resetu. Nie jest on częścią wspieranego API, a kod produkcyjny nie może go wywoływać.
Każdy proces roboczy PHP uruchamia własną baterię po włączeniu. Raport jest buforowany per instancja, więc asercje na gorącej ścieżce są sprawdzeniami statusu o stałym czasie.
Nie przechwytuj FipsModuleErrorStateException i nie kontynuuj. Wyjątek oznacza, że moduł odmawia usług kryptograficznych; poprawną reakcją jest zatrzymanie i ponowne uruchomienie procesu po naprawie.
FipsBootstrap::selfTestReport() obsługuje potrzeby testów samosprawdzających na żądanie i okresowych, takich jak punkty końcowe kondycji. Pomyślny przebieg na żądanie nigdy nie usuwa zatrzaśniętego błędu.

Zobacz także

Polityka kryptograficzna FIPS 140-2/3 i test samosprawdzający — strona funkcji z konfiguracją i przykładami.
Bezpieczeństwo — dokumentacja szczegółowa — połączone mechanizmy kontroli bezpieczeństwa Enterprise.
Podpis — dokumentacja szczegółowa — producent podpisów długoterminowych PAdES i jego uwaga o trybie FIPS.
Bezpieczeństwo — NextPDF Core — powierzchnia szyfrowania i podpisywania Core, z którą polityka się wiąże.

Granica publikacji

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