Enterprise Edition

FIPS 140 — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Tiefenreferenz für das FIPS-140-Modul von NextPDF Enterprise. Das Modul ist eine Policy- und Selbsttest-Fähigkeit. Es beschränkt kryptografische Auswahlen auf eine FIPS-orientierte Allow-Liste, führt beim Einschalten eine Batterie von Known-Answer-Tests aus und unterbindet die kryptografische Ausgabe, wenn die Batterie fehlschlägt. NextPDF ist kein FIPS-140-validiertes kryptografisches Modul, hält keine Zertifizierung und verleiht keine. Unterstützung ist nicht gleich Konformität, und Konformität ist nicht gleich Zertifizierung. Eine FIPS-kompatible Bereitstellung erfordert zusätzlich einen vom Betreiber bereitgestellten, FIPS-validierten kryptografischen Anbieter.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Enterprise-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

Öffentliche API-Oberfläche

Alle Symbole liegen in NextPDF\Enterprise\Security\Fips, außer FipsBootstrap in NextPDF\Enterprise\Bootstrap.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (alle Standard `null`)	Führt die Einschalt-Batterie einmal beim Start aus; verwendet standardmäßig die strikte Policy	`FipsModeGuard`	`FipsModuleErrorStateException` bei jedem Fehlschlag eines Einschalttests	Composition Root; Audit-Trail aus, wenn `$auditLogger` `null` ist
`FipsBootstrap::lazy()`	Wie `boot()`	Verschiebt die Batterie auf die erste Grenzprüfung	`FipsModeGuard`	Keine zum Aufrufzeitpunkt; die erste Prüfung kann `FipsModuleErrorStateException` werfen	Modul bleibt `PRE_OPERATIONAL` bis zur ersten Prüfung
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Bootet das Modul und umhüllt dann den Wächter für Signierer-Engpässe	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` bei jedem Fehlschlag eines Einschalttests	Delegiert an `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Führt die Batterie bei Bedarf aus und fasst sie zusammen	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Wirft nicht; Fehlschläge erscheinen in `failed`	Für Admin-Health-Endpunkte und CLI-Nutzung
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	FIPS-140-3-Preset: SHA-256/384/512; freigegebene RSA-, RSASSA-PSS-, ECDSA-OIDs; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Keine	Konstruktor ist privat; Presets sind der einzige Einstieg
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	FIPS-140-2-Preset: striktes Set plus `aes-128-cbc`	`self`	Keine	Nur für Legacy-Interoperabilität
`FipsCryptoPolicy::assertPreOperational()`	Keine	Führt die Einschalt-Batterie aus oder spielt ihr eingerastetes Ergebnis erneut ab	`void`	`FipsModuleErrorStateException`, wenn ein Einschalttest fehlschlägt	Angetrieben von der Core-Enforcement-Naht vor der ersten Operation
`FipsCryptoPolicy`-Abfrageoberfläche	`string`- / `int`-Eingaben	Prüfungen auf Allow-Listen-Zugehörigkeit; unbekannter Schlüsseltyp wird verweigert	`bool` / `string`	Keine	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Umhüllt eine Policy mit assert-artigen Grenzen	—	Keine	Ohne `$bootGuard` gibt es kein Selbsttest-Gate; die Produktionskomposition liefert ihn
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Zuerst der Deny-Katalog, dann die Allow-Liste	`void`	`FipsViolationException`; `FipsModuleErrorStateException`, wenn ein Boot-Guard verdrahtet ist	Audit-Eintrag geht jeder `FipsViolationException` voraus
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Zuerst der Deny-Katalog, dann die Allow-Liste	`void`	Wie oben	OIDs werden exakt abgeglichen
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Zuerst der Deny-Katalog, dann die Allow-Liste	`void`	Wie oben	Namen werden in Kleinschreibung verglichen
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Zuerst der Deny-Katalog, dann die Policy-Mindestwerte	`void`	Wie oben	Unbekannter Schlüsseltyp wird verweigert
`FipsModeGuard::getPolicy()`	Keine	Gibt die umhüllte Policy zurück	`CryptoPolicyInterface`	Keine	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Hält die Batterie; führt sie nicht aus	—	Keine	Ein Einschaltzyklus pro Instanz
`FipsBootGuard::report()`	Keine	Führt die Batterie einmal aus, cached den Bericht, rastet bei Fehler ein	`FipsSelfTestReport`	Keine	Der erste Aufruf führt die Tests aus
`FipsBootGuard::rerun()`	Keine	Erzwingt einen frischen Lauf; ein Fehlerlauf rastet den Prozess ein	`FipsSelfTestReport`	Keine	Selbsttest bei Bedarf; kein Pfad zur Fehlerbehebung
`FipsBootGuard::assertOperational()`	Keine	Stellt sicher, dass das Modul betriebsbereit ist; prozessweit persistent	`void`	`FipsModuleErrorStateException`	Eine saubere Instanz wirft dennoch, wenn der Prozess einen Fehler eingerastet hat
`FipsBootGuard::status()`	Keine	Meldet den gecachten Status	`FipsSelfTestStatus`	Keine	`ERROR`, wenn eingerastet; `PRE_OPERATIONAL`, wenn nie ausgeführt
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Verwendet plattformseitiges `hash()` und `random_bytes()`	—	Keine	Overrides existieren für deterministische Fehlschlagtests
`FipsSelfTest::run()`	Keine	Führt die gesamte Batterie aus; kurzschließt nie	`FipsSelfTestReport`	Keine	Fehlschläge landen im Bericht, nicht in Exceptions
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Unveränderliches Aggregat eines Laufs	—	`assertOperational()` wirft `FipsModuleErrorStateException` im Fehlerzustand	Auch `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Unveränderliches Ergebnis pro Test	—	Keine	`kind` ist `KAT`, `PWCT` oder `HEALTH`; auch `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	String-basiertes Enum	—	Keine	Fälle `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Umhüllt einen boot-gegateten Wächter für Signier-Engpässe	—	Keine	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Löst die OID und die Schlüsselstärke auf und delegiert dann an den Wächter	`void`	`FipsViolationException` (unbekannter Algorithmus, nicht freigegebener PSS-Digest, nicht beweisbarer Schlüssel oder Policy-Verweigerung); `FipsModuleErrorStateException` über den Wächter	Nur der Generierungspfad; die Verifizierung wird niemals hierher geleitet
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Umhüllt einen PSR-3-Logger und dieselbe Policy, die der Wächter durchsetzt	—	Keine	Aufgezeichnete Entscheidungen können nicht von den durchgesetzten abweichen
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	`string`- / `int`-Eingaben je Entscheidung	Protokolliert ALLOW auf INFO und DENY auf WARNING	`bool` (true, wenn zulässig)	Keine	Strukturierter Kontext: Policy-Name, Element, Entscheidung
`FipsTransitioningAlgorithms`	`string`- / `int`-Eingaben	Statischer SP-800-131A-Rev.2-Deny-Katalog	`bool` / `list<string>`	Keine	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, plus `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Typisierte Policy-Verletzung mit öffentlichen readonly-Feldern	—	—	Untertyp von `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Verweigerung im Fehlerzustand, die die fehlgeschlagenen Testergebnisse trägt	—	—	Untertyp von `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';
}

Verhaltensvertrag

Die Policy-Allow-Liste ist die maßgebliche Entscheidung. FipsTransitioningAlgorithms fügt darüber eine explizite SP-800-131A-Rev.2-Deny-Schicht hinzu, für audit-klare Ablehnungsmeldungen. Die Deny-Schicht erweitert oder überschreibt die Allow-Liste niemals.
FipsCryptoPolicy::strict() erlaubt SHA-256, SHA-384 und SHA-512; RSA PKCS#1 v1.5, RSASSA-PSS und ECDSA-Signatur-OIDs, die an diese Hashes gebunden sind; aes-256-cbc und aes-256-gcm; sowie Schlüsseluntergrenzen von RSA 2048, EC 256, Ed25519 256. standard() erlaubt zusätzlich aes-128-cbc.
Die Einschalt-Batterie deckt ab: Digest-KATs für SHA-256/384/512, einen HMAC-SHA-256-KAT, einen AES-256-CBC-Verschlüsseln-und-Entschlüsseln-KAT, einen AES-256-GCM-Tag-KAT, einen ECDSA-P-256-Pairwise-Consistency-Test und einen DRBG-Health-Check. FipsSelfTest::run() führt stets jeden Test aus und kurzschließt nie, sodass der Bericht als Audit-Nachweis vollständig ist.
Die DRBG-Zeile ist ein kontinuierlicher Health-Test (Ziehungslänge plus verschiedene aufeinanderfolgende Ziehungen), kein Known-Answer-Test. Die Known-Answer-Pflicht für den DRBG wird an den zugrunde liegenden, vom Betreiber bereitgestellten FIPS-validierten Anbieter delegiert.
Der Fehlerzustand ist prozess-persistent. Der erste ERROR-Bericht, den irgendein FipsBootGuard beobachtet, rastet den gesamten Prozess ein. Eine frische Wächter- oder Policy-Instanz kann den Fehler nicht reinwaschen, und ein späterer bestehender Rerun löscht ihn nicht. Nur ein Prozess-Neustart (ein echter Power-Cycle) setzt den Zustand zurück.
FipsCryptoPolicy implementiert NextPDF\Contracts\CryptoPolicyInterface und NextPDF\Contracts\PreOperationalSelfTestInterface. Wenn es als Core-Krypto-Policy konfiguriert ist, treibt die Core-Enforcement-Naht assertPreOperational() an, bevor die erste Signatur oder der erste Chiffretext erzeugt wird.
FipsSignatureEnforcer gatet nur den Generierungspfad. Die Verifizierung bereits generierter Signaturen ist Legacy-Nutzung unter SP 800-131A Rev.2 und wird niemals durch den Enforcer geleitet.
Wenn ein Audit-Logger verdrahtet ist, gibt jede Assert-Grenze einen ALLOW- (INFO) oder DENY- (WARNING) Eintrag aus, bevor irgendeine Policy-Verletzung geworfen wird. Jede FipsViolationException-Verweigerung ist daher im Trail belegt. Das Boot-Guard-Gate läuft zuerst, sodass eine Verweigerung im Fehlerzustand vor dem Audit-Eintrag ausgelöst wird. Der FipsAuditLogger konsultiert dieselbe Policy, die der Wächter durchsetzt, sodass aufgezeichnete Entscheidungen nicht von den durchgesetzten abweichen können.

Randfälle & Fehlermodi

Ein unbekannter Schlüsseltyp wird von beiden Schichten verweigert: Die Policy gibt false zurück, und der Katalog behandelt ihn als unzulässig.
Ein Signieralgorithmus-Bezeichner, den der Enforcer nicht auf eine Signatur-OID abbilden kann, wird fail-closed mit FipsViolationException abgelehnt.
Jede RSASSA-PSS-Variante teilt sich die OID 1.2.840.113549.1.1.10, sodass die OID allein den Digest nicht beweisen kann. Der Enforcer bindet den effektiven Digest explizit und verweigert jedes PSS-Token, dessen Digest nicht SHA-256/384/512 ist.
Ein Zertifikat, das nicht geparst werden kann oder dessen Public-Key-Bitlänge nicht verfügbar ist, wird als key:unprovable verweigert.
Auf einer Laufzeit ohne asymmetrische OpenSSL-Primitive verzeichnet der ECDSA-Pairwise-Consistency-Test einen Fehlschlag, kein Überspringen, und das Modul geht in ERROR.
Zwei identische aufeinanderfolgende 32-Byte-Zufallsziehungen lassen den DRBG-Health-Check fehlschlagen (Erkennung fixierter Ausgabe) und erzwingen ERROR.
Ein FipsModeGuard, der ohne Boot-Guard konstruiert wird, führt nur Policy-Prüfungen aus und hat kein Selbsttest-Gate. Die Produktionskomposition geht über FipsBootstrap, das das Gate stets verdrahtet.
Hash- und Chiffre-Namen werden in Kleinschreibung verglichen; Signatur-OIDs werden exakt abgeglichen, ohne Normalisierung.
Nach FipsBootstrap::lazy() bleibt das Modul PRE_OPERATIONAL, bis die erste Assert-Grenze die Batterie ausführt. PRE_OPERATIONAL wird zum Prüfzeitpunkt als nicht betriebsbereit behandelt.

Verhalten im FIPS-Modus

Dieses Modul ist die FIPS-Modus-Oberfläche selbst. Während sich das Modul im Fehlerzustand befindet und während die vorbetrieblichen Selbsttests laufen, wird die kryptografische Ausgabe unterbunden: Jede Assert-Grenze wirft FipsModuleErrorStateException, bevor irgendeine Signatur oder ein Chiffretext erzeugt wird (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() und FipsBootstrap::selfTestReport() legen den Zustand offen, sodass ein Betreiber feststellen kann, dass das Modul in den Fehlerzustand eingetreten ist (ISO/IEC 19790:2025 §7.10.3). Diese Verhaltensweisen sind Fähigkeitsansprüche über NextPDF-Code, keine Validierungsbehauptung: Die Modulgrenze, die FIPS 140 validiert, ist der vom Betreiber bereitgestellte kryptografische Anbieter, nicht NextPDF.

Konformität

Anspruch	Standard	Klausel
FIPS 140-3 basiert auf ISO/IEC 19790 und ISO/IEC 24759; diese Seite zitiert daher ISO/IEC-19790-Klauseln.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
Die Ausgabe wird im Fehlerzustand und während der vorbetrieblichen Selbsttests unterbunden.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Ein Known-Answer-Test vergleicht ein berechnetes Ergebnis mit einer bekannten erwarteten Ausgabe; die Batterie setzt diese Form um.	ISO/IEC 19790:2025	§7.10.4
Der Betreiber kann den Fehlerzustand über eine Statusausgabe feststellen.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Betreiber können die Selbsttests bei Bedarf für periodische Tests initiieren; `rerun()` und `selfTestReport()` bieten dies.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 ist für die Erzeugung neuer digitaler Signaturen unzulässig; der Deny-Katalog lehnt es ab.	NIST SP 800-131A Rev.2	§9
Signaturerzeugung unter 112-Bit-Stärke (RSA < 2048, ECDSA-Ordnung < 224) ist unzulässig; die Schlüsseluntergrenzen setzen dies durch.	NIST SP 800-131A Rev.2	§3 Table 2
Die Verifizierung bereits generierter SHA-1-Signaturen ist Legacy-Nutzung; sie wird nicht durch das Generierungs-Gate geleitet.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Alle Klauseln sind paraphrasiert; kein normativer Text wird wiedergegeben. NextPDF erhebt keinen Anspruch auf eine FIPS-140-Zertifizierung. Das Modul richtet sein Verhalten als Compliance-Unterstützungsfähigkeit an den zitierten Klauseln aus. Ob eine Bereitstellung FIPS-konform ist, hängt vom validierten Anbieter des Betreibers, der Definition der Modulgrenze und dem Compliance-Programm ab — nicht von NextPDF allein.

Entwicklungshinweise

Deterministische Fehlschlagtests injizieren defekte Anbieter über den FipsSelfTest-Konstruktor oder über die $selfTest-Parameter von FipsCryptoPolicy::strict(), standard() und den FipsBootstrap-Methoden.
Der prozess-persistente Fehler-Latch hat einen internen, nur für Tests bestimmten Reset-Hook. Er ist nicht Teil der unterstützten API, und Produktionscode darf ihn nicht aufrufen.
Jeder PHP-Worker-Prozess führt seine eigene Einschalt-Batterie aus. Der Bericht wird pro Instanz gecached, sodass Hot-Path-Prüfungen konstante Statusabfragen sind.
Fangen Sie FipsModuleErrorStateException nicht ab und fahren Sie fort. Die Exception bedeutet, dass das Modul kryptografische Dienste verweigert; die korrekte Reaktion ist, den Prozess nach der Behebung zu stoppen und neu zu starten.
FipsBootstrap::selfTestReport() bedient On-Demand- und periodische Selbsttest-Bedürfnisse, etwa Health-Endpunkte. Ein bestehender On-Demand-Lauf löscht einen eingerasteten Fehler niemals.

Siehe auch

FIPS-140-2/3-Krypto-Policy und Selbsttest — die Fähigkeitsseite mit Einrichtung und Beispielen.
Sicherheit — Tiefenreferenz — die kombinierten Enterprise-Sicherheitskontrollen.
Signatur — Tiefenreferenz — der PAdES-Langzeit-Produzent und seine FIPS-Modus-Notiz.
Sicherheit — NextPDF Core — die Core-Verschlüsselungs- und Signieroberfläche, an die die Policy bindet.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind außerhalb des Umfangs.