Enterprise edizione

FIPS 140 — Riferimento approfondito

In sintesi

Questa pagina è il riferimento approfondito del modulo FIPS 140 di NextPDF Enterprise. Il modulo è una capacità di policy e self-test. Restringe le scelte crittografiche a un allow-list allineato a FIPS, esegue una batteria di known-answer-test al power-on e inibisce l’output crittografico quando la batteria fallisce. NextPDF non è un modulo crittografico FIPS 140 validated, non detiene alcuna certificazione e non ne conferisce alcuna. Il supporto non equivale alla conformità e la conformità non equivale alla certificazione. Un deployment FIPS-compatible richiede inoltre un provider crittografico FIPS-validated fornito dall’operatore.

Disponibilità e licenze

Questa capacità è distribuita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Un deployment privo di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Superficie API pubblica

Tutti i simboli risiedono in NextPDF\Enterprise\Security\Fips, tranne FipsBootstrap in NextPDF\Enterprise\Bootstrap.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Lancia o fallisce con	Note
`FipsBootstrap::boot()`	`?CryptoPolicyInterface $policy`, `?FipsSelfTest $selfTest`, `?LoggerInterface $auditLogger` (tutti predefiniti a `null`)	Esegue una volta la batteria al power-on all’avvio; usa come predefinita la policy strict	`FipsModeGuard`	`FipsModuleErrorStateException` in caso di qualsiasi fallimento di un test al power-on	Composition root; audit trail disattivato quando `$auditLogger` è `null`
`FipsBootstrap::lazy()`	Come `boot()`	Rimanda la batteria alla prima assertion di confine	`FipsModeGuard`	Nessuna al momento della chiamata; la prima assertion può lanciare `FipsModuleErrorStateException`	Il modulo resta `PRE_OPERATIONAL` fino alla prima assertion
`FipsBootstrap::signatureEnforcer()`	`?CryptoPolicyInterface $policy = null`, `?FipsSelfTest $selfTest = null`	Avvia il modulo, poi avvolge il guard per i chokepoint di firma	`FipsSignatureEnforcer`	`FipsModuleErrorStateException` in caso di qualsiasi fallimento di un test al power-on	Delega a `boot()`
`FipsBootstrap::selfTestReport()`	`?FipsSelfTest $selfTest = null`	Esegue la batteria on demand e la riepiloga	`array{status: FipsSelfTestStatus, operational: bool, failed: list<string>}`	Non lancia; i fallimenti compaiono in `failed`	Per endpoint di health amministrativi e uso da CLI
`FipsCryptoPolicy::strict()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-3: SHA-256/384/512; OID approvati di RSA, RSASSA-PSS, ECDSA; `aes-256-cbc`, `aes-256-gcm`; RSA >= 2048, EC >= 256	`self`	Nessuna	Il costruttore è privato; i preset sono l’unico punto d’ingresso
`FipsCryptoPolicy::standard()`	`?FipsSelfTest $selfTest = null`	Preset FIPS 140-2: insieme strict più `aes-128-cbc`	`self`	Nessuna	Solo per interoperabilità legacy
`FipsCryptoPolicy::assertPreOperational()`	Nessuno	Esegue, o riproduce il risultato latched, della batteria al power-on	`void`	`FipsModuleErrorStateException` quando qualsiasi test al power-on fallisce	Guidata dal seam di enforcement del Core prima della prima operazione
Superficie di query di `FipsCryptoPolicy`	Input `string` / `int`	Controlli di appartenenza all’allow-list; un tipo di chiave sconosciuto viene negato	`bool` / `string`	Nessuna	`isHashAlgorithmAllowed`, `isSignatureAlgorithmAllowed`, `isEncryptionAlgorithmAllowed`, `isKeyStrengthAllowed`, `getPreferredHashAlgorithm`, `getName`
`FipsModeGuard::__construct()`	`CryptoPolicyInterface $policy`, `?FipsBootGuard $bootGuard = null`, `?FipsAuditLogger $auditLogger = null`	Avvolge una policy con confini in stile assert	—	Nessuna	Senza `$bootGuard` non c’è alcun gate di self-test; la composizione di produzione lo fornisce
`FipsModeGuard::assertHashAllowed()`	`string $algorithm`	Prima il deny catalogue, poi l’allow-list	`void`	`FipsViolationException`; `FipsModuleErrorStateException` quando un boot guard è cablato	Il record di audit precede qualsiasi `FipsViolationException`
`FipsModeGuard::assertSignatureAlgorithmAllowed()`	`string $oid`	Prima il deny catalogue, poi l’allow-list	`void`	Come sopra	Gli OID sono confrontati esattamente
`FipsModeGuard::assertEncryptionAllowed()`	`string $algorithm`	Prima il deny catalogue, poi l’allow-list	`void`	Come sopra	I nomi sono confrontati in minuscolo
`FipsModeGuard::assertKeyStrengthAllowed()`	`string $keyType`, `int $bitLength`	Prima il deny catalogue, poi i minimi della policy	`void`	Come sopra	Un tipo di chiave sconosciuto viene negato
`FipsModeGuard::getPolicy()`	Nessuno	Restituisce la policy avvolta	`CryptoPolicyInterface`	Nessuna	—
`FipsBootGuard::__construct()`	`FipsSelfTest $selfTest`	Detiene la batteria; non la esegue	—	Nessuna	Un ciclo al power-on per istanza
`FipsBootGuard::report()`	Nessuno	Esegue la batteria una volta, memorizza in cache il report, latch in caso di errore	`FipsSelfTestReport`	Nessuna	La prima chiamata esegue i test
`FipsBootGuard::rerun()`	Nessuno	Forza una nuova esecuzione; un’esecuzione con errore fa latch del processo	`FipsSelfTestReport`	Nessuna	Self-test on demand; non è un percorso di error-recovery
`FipsBootGuard::assertOperational()`	Nessuno	Verifica che il modulo sia operational; sticky per tutto il processo	`void`	`FipsModuleErrorStateException`	Un’istanza pulita lancia comunque quando il processo ha fatto latch di un errore
`FipsBootGuard::status()`	Nessuno	Riporta lo stato in cache	`FipsSelfTestStatus`	Nessuna	`ERROR` quando latched; `PRE_OPERATIONAL` quando mai eseguito
`FipsSelfTest::__construct()`	`?callable $randomBytesProvider = null`, `?callable $hashProvider = null`	Usa `hash()` e `random_bytes()` della piattaforma	—	Nessuna	Esistono override per test di fallimento deterministici
`FipsSelfTest::run()`	Nessuno	Esegue la batteria completa; non fa mai short-circuit	`FipsSelfTestReport`	Nessuna	I fallimenti finiscono nel report, non nelle eccezioni
`FipsSelfTestReport`	`FipsSelfTestStatus $status`, `array $results`, `array $failedResults`	Aggregato immutabile di una singola esecuzione	—	`assertOperational()` lancia `FipsModuleErrorStateException` nello stato di errore	Anche `isOperational()`, `isError()`
`FipsSelfTestResult`	`string $algorithm`, `string $kind`, `bool $passed`, `string $message = ''`	Esito immutabile per singolo test	—	Nessuna	`kind` è `KAT`, `PWCT` o `HEALTH`; anche `isPassed()`, `isFailed()`
`FipsSelfTestStatus`	—	Enum backed da stringa	—	Nessuna	Casi `PRE_OPERATIONAL`, `OPERATIONAL`, `ERROR`
`FipsSignatureEnforcer::__construct()`	`FipsModeGuard $guard`	Avvolge un guard boot-gated per i chokepoint di firma	—	Nessuna	—
`FipsSignatureEnforcer::assertSignatureGenerationAllowed()`	`string $algorithm`, `string $certificatePem`	Risolve l’OID e la robustezza di chiave, poi delega al guard	`void`	`FipsViolationException` (algoritmo sconosciuto, digest PSS non approvato, chiave non dimostrabile o negazione da policy); `FipsModuleErrorStateException` tramite il guard	Solo percorso di generazione; la verifica non passa mai di qui
`FipsAuditLogger::__construct()`	`CryptoPolicyInterface $policy`, `LoggerInterface $logger`	Avvolge un logger PSR-3 e la stessa policy applicata dal guard	—	Nessuna	Le decisioni registrate non possono divergere da quelle applicate
`FipsAuditLogger::logHashOperation()` / `logSignatureOperation()` / `logEncryptionOperation()` / `logKeyStrengthCheck()`	Input `string` / `int` per decisione	Registra ALLOW a INFO e DENY a WARNING	`bool` (true quando consentito)	Nessuna	Contesto strutturato: nome della policy, item, decisione
`FipsTransitioningAlgorithms`	Input `string` / `int`	Deny catalogue statico SP 800-131A Rev.2	`bool` / `list<string>`	Nessuna	`isHashDisallowed`, `isSignatureOidDisallowed`, `isEncryptionDisallowed`, `isKeyStrengthDisallowed`, più `disallowedHashes`, `disallowedSignatureOids`, `disallowedEncryption`
`FipsViolationException`	`string $policyName`, `string $violatingItem`, `string $reason`	Violazione di policy tipizzata con campi public readonly	—	—	Sottotipo di `NextPDF\Exception\NextPdfException`
`FipsModuleErrorStateException`	`array $failedResults`, `?string $message = null`	Rifiuto in stato di errore che trasporta i risultati dei test falliti	—	—	Sottotipo di `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';
}

Contratto di comportamento

L’allow-list della policy è la decisione autoritativa. FipsTransitioningAlgorithms aggiunge sopra di essa un layer di deny esplicito SP 800-131A Rev.2, per messaggi di rifiuto chiari ai fini dell’audit. Il layer di deny non allarga né sovrascrive mai l’allow-list.
FipsCryptoPolicy::strict() consente SHA-256, SHA-384 e SHA-512; OID di firma RSA PKCS#1 v1.5, RSASSA-PSS ed ECDSA legati a quegli hash; aes-256-cbc e aes-256-gcm; e soglie di chiave RSA 2048, EC 256, Ed25519 256. standard() consente in aggiunta aes-128-cbc.
La batteria al power-on copre: KAT di digest SHA-256/384/512, un KAT HMAC-SHA-256, un KAT di cifratura-e-decifratura AES-256-CBC, un KAT di tag AES-256-GCM, un test di consistenza pair-wise ECDSA P-256 e un health check del DRBG. FipsSelfTest::run() esegue sempre ogni test e non fa mai short-circuit, così il report è completo come evidenza di audit.
La riga del DRBG è un health test continuo (lunghezza dell’estrazione più estrazioni successive distinte), non un known-answer test. L’obbligo di known-answer del DRBG è delegato al provider FIPS-validated sottostante fornito dall’operatore.
Lo stato di errore è process-sticky. Il primo report ERROR osservato da qualsiasi FipsBootGuard fa latch dell’intero processo. Un guard o una policy istanziati di fresco non possono ripulire l’errore, e un rerun con esito positivo successivo non lo cancella. Solo un riavvio del processo (un vero power cycle) reimposta lo stato.
FipsCryptoPolicy implementa NextPDF\Contracts\CryptoPolicyInterface e NextPDF\Contracts\PreOperationalSelfTestInterface. Quando configurata come policy crittografica del Core, il seam di enforcement del Core guida assertPreOperational() prima che venga prodotta la prima firma o il primo ciphertext.
FipsSignatureEnforcer presidia solo il percorso di generazione. La verifica di firme già generate è uso legacy secondo SP 800-131A Rev.2 e non passa mai attraverso l’enforcer.
Quando un audit logger è cablato, ogni confine di assert emette un record ALLOW (INFO) o DENY (WARNING) prima di qualsiasi throw di violazione di policy. Ogni negazione FipsViolationException è quindi documentata nel trail. Il gate del boot-guard viene eseguito per primo, così un rifiuto in stato di errore viene sollevato prima del record di audit. FipsAuditLogger consulta la stessa policy applicata dal guard, così le decisioni registrate non possono divergere da quelle applicate.

Casi limite e modalità di guasto

Un tipo di chiave sconosciuto viene negato da entrambi i layer: la policy restituisce false e il catalogue lo tratta come disallowed.
Un identificatore di algoritmo di firma che l’enforcer non riesce a mappare a un OID di firma viene rifiutato fail-closed con FipsViolationException.
Ogni variante RSASSA-PSS condivide l’OID 1.2.840.113549.1.1.10, quindi l’OID da solo non può dimostrare il digest. L’enforcer lega esplicitamente il digest effettivo e nega qualsiasi token PSS il cui digest non sia SHA-256/384/512.
Un certificato che non può essere analizzato, o la cui lunghezza in bit della chiave pubblica non è disponibile, viene negato come key:unprovable.
Su un runtime privo di primitive asimmetriche OpenSSL, il test di consistenza pair-wise ECDSA registra un fallimento, non uno skip, e il modulo entra in ERROR.
Due estrazioni casuali successive identiche da 32 byte fanno fallire l’health check del DRBG (rilevamento di stuck-output) e forzano ERROR.
Un FipsModeGuard costruito senza un boot guard esegue solo i controlli di policy e non ha alcun gate di self-test. La composizione di produzione passa attraverso FipsBootstrap, che cabla sempre il gate.
I nomi di hash e cifrario sono confrontati in minuscolo; gli OID di firma sono confrontati esattamente, senza alcuna normalizzazione.
Dopo FipsBootstrap::lazy(), il modulo resta PRE_OPERATIONAL finché il primo confine di assert non esegue la batteria. PRE_OPERATIONAL è trattato come non operational al momento dell’assertion.

Comportamento in modalità FIPS

Questo modulo è la superficie della modalità FIPS in sé. Mentre il modulo è nello stato di errore, e mentre girano i self-test pre-operational, l’output crittografico è inibito: ogni confine di assert lancia FipsModuleErrorStateException prima che venga prodotta qualsiasi firma o ciphertext (ISO/IEC 19790:2025 §7.3.3 b), AS03.07). FipsBootGuard::status() e FipsBootstrap::selfTestReport() espongono lo stato così che un operatore possa determinare che il modulo è entrato nello stato di errore (ISO/IEC 19790:2025 §7.10.3). Questi comportamenti sono dichiarazioni di capacità sul codice NextPDF, non una dichiarazione di validazione: il confine del modulo che FIPS 140 valida è il provider crittografico fornito dall’operatore, non NextPDF.

Conformità

Dichiarazione	Standard	Clausola
FIPS 140-3 si basa su ISO/IEC 19790 e ISO/IEC 24759; questa pagina cita pertanto le clausole ISO/IEC 19790.	FIPS 140-3	Introduction (fips_140_3#x26.x2)
L’output è inibito nello stato di errore e durante i self-test pre-operational.	ISO/IEC 19790:2025	§7.3.3 b) [AS03.07]
Un known-answer test confronta un risultato calcolato con un output atteso noto; la batteria implementa questa forma.	ISO/IEC 19790:2025	§7.10.4
L’operatore può determinare lo stato di errore tramite un output di stato.	ISO/IEC 19790:2025	§7.10.3 [AS10.10]
Gli operatori possono avviare i self-test on demand per test periodici; `rerun()` e `selfTestReport()` lo forniscono.	ISO/IEC 19790:2025	§7.10.5 [AS10.54]
SHA-1 è disallowed per la generazione di nuove firme digitali; il deny catalogue lo rifiuta.	NIST SP 800-131A Rev.2	§9
La generazione di firme sotto la robustezza di 112 bit (RSA < 2048, ordine ECDSA < 224) è disallowed; le soglie di chiave lo impongono.	NIST SP 800-131A Rev.2	§3 Table 2
La verifica di firme SHA-1 già generate è uso legacy; non passa attraverso il gate di generazione.	NIST SP 800-131A Rev.2	Change summary (9.x4.p12)

Tutte le clausole sono parafrasate; nessun testo normativo è riprodotto. NextPDF non avanza alcuna dichiarazione di certificazione FIPS 140. Il modulo allinea il proprio comportamento alle clausole citate come capacità di assistenza alla conformità. Se un deployment sia FIPS-compliant dipende dal provider validated dell’operatore, dalla definizione del confine del modulo e dal programma di conformità — non da NextPDF da solo.

Note di sviluppo

I test di fallimento deterministici iniettano provider difettosi attraverso il costruttore di FipsSelfTest, o attraverso i parametri $selfTest di FipsCryptoPolicy::strict(), standard() e i metodi di FipsBootstrap.
Il latch dello stato di errore process-sticky ha un hook di reset interno, solo per test. Non fa parte dell’API supportata e il codice di produzione non deve chiamarlo.
Ogni processo worker PHP esegue la propria batteria al power-on. Il report è messo in cache per istanza, così le assertion sul percorso hot sono controlli di stato a tempo costante.
Non catturare FipsModuleErrorStateException e proseguire. L’eccezione significa che il modulo rifiuta i servizi crittografici; la risposta corretta è fermarsi e riavviare il processo dopo la remediation.
FipsBootstrap::selfTestReport() serve esigenze di self-test on demand e periodici, come gli endpoint di health. Un’esecuzione on demand con esito positivo non cancella mai un errore latched.

Vedi anche

Policy crittografica e self-test FIPS 140-2/3 — la pagina della capacità con setup ed esempi.
Security — Riferimento approfondito — i controlli di sicurezza Enterprise combinati.
Signature — Riferimento approfondito — il producer PAdES long-term e la sua nota sulla modalità FIPS.
Security — NextPDF Core — la superficie di cifratura e firma del Core a cui la policy si lega.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.