Enterprise edizione

Security — HSM, PKCS#11 e modalità FIPS

In breve

NextPDF Enterprise aggiunge un percorso di firma con token hardware PKCS#11 e una policy crittografica in modalità FIPS sopra la superficie di sicurezza di Core e Pro. Questa pagina indica comportamento, confini e la postura esplicita sulla certificazione FIPS e sulla custodia delle chiavi.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Una distribuzione priva di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Panoramica concettuale

La superficie di sicurezza Enterprise ha tre parti: un firmatario con token hardware, una crypto-policy in modalità FIPS e una guardia di self-test all’accensione.

Il firmatario con token hardware adatta un token PKCS#11 — una smart card, un dispositivo USB o un HSM connesso in rete. Il firmatario localizza il certificato e la chiave privata sul token per label. Quindi chiede al token di calcolare la firma. La chiave privata non lascia il confine del token; l’operazione viene eseguita all’interno del token. L’operazione di firma del token, la sessione e il login dell’utente seguono PKCS#11 v3.1 §5. Il percorso HSM necessita dell’estensione PHP ext-pkcs11. Tale estensione non fa parte del PHP standard. Installarla separatamente. Usare il controllo di disponibilità prima di costruire il firmatario.

La crypto-policy in modalità FIPS limita le scelte crittografiche a un insieme approvato. Ha due preset. Il preset strict consente gli hash SHA-256, SHA-384 e SHA-512; gli OID di firma RSA ed ECDSA con tali hash; la cifratura AES-256-CBC; e dimensioni minime delle chiavi di RSA 2048 ed EC 256. Il preset standard è identico ma consente anche AES-128-CBC per l’interoperabilità con sistemi più datati. Una guardia a runtime avvolge la policy. La guardia verifica ogni hash, OID di firma, algoritmo di cifratura e robustezza della chiave prima che l’operazione venga eseguita. Una scelta non consentita solleva una violazione tipizzata e arresta l’operazione. Il percorso è fail-closed: la policy non si rilassa mai da sé e non sostituisce mai un algoritmo più debole. La lunghezza minima della chiave RSA segue NIST SP 800-131A Rev.2 §3. L’accoppiamento di curva e hash ECDSA segue FIPS 186-5 §6.1.1.

La guardia di self-test all’accensione esegue una batteria di test a risposta nota (known-answer-test) una volta all’avvio del processo. La batteria copre le funzioni approvate di hash, MAC, cifratura, firma e generazione di bit casuali. Se un test fallisce, la guardia FIPS di Enterprise entra in uno stato di errore e rifiuta i servizi crittografici fino al reset. Il risultato è memorizzato in cache per la durata del processo; è disponibile una riesecuzione on-demand. La categoria di self-test e il trigger del test condizionale seguono ISO/IEC 19790:2025 §7.10 e §7.10.3.

Perché funziona così

La decisione portante è mantenere la chiave privata all’interno del confine del token e rendere la crypto-policy fail-closed. Un firmatario che potesse esportare una chiave, o ripiegare silenziosamente su un algoritmo più debole, vanificherebbe la garanzia per la quale esiste un HSM. Perciò il firmatario chiede al token di calcolare la firma in loco, e la guardia in modalità FIPS rifiuta qualsiasi hash, OID o robustezza di chiave al di fuori del preset approvato prima che l’operazione venga eseguita. Il self-test all’accensione estende la stessa postura all’avvio: un modulo non verificato rifiuta il servizio invece di firmare su primitive non testate. Il risultato è un confine su cui è possibile ragionare, in cui la custodia della chiave è di proprietà dell’operatore e del token, non di questo software.

Sfondo di progettazione: Firma basata su HSM.

Superficie API

Superficie pubblica	Tipo	Scopo	Stabilità	Da
Firmatario con token PKCS#11	classe (implementa il Core `HsmSignerInterface`)	Firmare con un token PKCS#11; la chiave resta sul token	stable	1.0.0
Crypto-policy FIPS	classe (implementa il Core `CryptoPolicyInterface`)	Un preset di algoritmi consentiti e robustezza delle chiavi	stable	1.9.0
Guardia in modalità FIPS	classe	Asserire che un hash, OID di firma, algoritmo di cifratura o robustezza della chiave sia consentito	stable	1.9.0
Guardia di boot FIPS	classe	Eseguire e mettere in cache il self-test all’accensione; asserire che il modulo sia operativo	stable	3.2.0
Firmatario CLI / engine OpenSSL	classe (implementa `HsmSignerInterface`)	Firmare tramite un engine OpenSSL o la CLI OpenSSL per i token basati su engine	stable	1.0.0

Il costruttore del firmatario con token accetta il percorso della libreria PKCS#11, il numero dello slot, il PIN del token, la label del certificato e una label di chiave separata facoltativa. Il parametro PIN è contrassegnato come sensibile; non viene registrato né serializzato. Il firmatario espone inoltre il certificato del firmatario e la catena del certificato in forma DER. Il contratto autorevole di parametri e tipi è il riferimento API pubblicato per il pacchetto nextpdf/enterprise; trattare quel riferimento — non questa pagina — come il contratto.

Esempio di codice — Avvio rapido

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

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);

Esempio di codice — Produzione

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.

L’elenco completo degli argomenti del costruttore, i tipi di eccezione e la costruzione del firmatario con token PKCS#11 sono documentati nel riferimento approfondito di sicurezza Enterprise.

Casi limite e insidie

Il costruttore del firmatario con token PKCS#11 solleva un’eccezione di operazione tipizzata quando ext-pkcs11 non è caricata. Controllare prima la disponibilità.
Il firmatario con token mette in cache un modulo PKCS#11 per percorso di libreria per processo. Questo soddisfa la regola «inizializza una sola volta per modulo» dell’interfaccia del token.
I meccanismi ECDSA del token restituiscono una firma raw. Il firmatario la converte nella forma codificata DER per l’interoperabilità con PDF e OpenSSL.
La guardia FIPS rifiuta per impostazione predefinita un tipo di chiave sconosciuto. Un tipo di chiave non riconosciuto non è accettato silenziosamente.
Il percorso di firma post-quantistico è sperimentale, opt-in e disabilitato per impostazione predefinita. I profili PAdES standard per l’archiviazione a lungo termine non riconoscono ancora le suite post-quantistiche. Non abilitarlo per le firme AdES di produzione.

Prestazioni

I controlli della guardia FIPS sono lookup su hash-map a tempo costante. Il self-test all’accensione viene eseguito una sola volta per processo; il suo costo è ammortizzato sulla durata del processo, non per chiamata di firma. Un’operazione di firma PKCS#11 aggiunge un round trip al token. Un HSM connesso in rete aggiunge la latenza di rete di tale round trip.

Note di sicurezza

Il percorso di firma è fail-closed. Un fallimento di primitiva o una lacuna di policy solleva un’eccezione tipizzata. Il percorso non degrada mai silenziosamente a un algoritmo più debole.
Il parametro PIN del token è contrassegnato come sensibile. Non viene registrato né serializzato.
La chiave privata per un token PKCS#11 resta sul token. L’operazione di firma viene eseguita all’interno del confine del token.
Il self-test all’accensione porta la guardia FIPS di Enterprise in uno stato di errore in caso di mancata corrispondenza del known-answer-test e rifiuta i servizi crittografici fino al reset.
L’uso di AES-GCM richiede un vettore di inizializzazione univoco per chiave, secondo NIST SP 800-38D §5.

Residenza dei dati e mitigazioni dei dati personali (PII)

Il codice di firma e di policy FIPS viene eseguito in-process. Nessun contenuto del documento lascia l’host per il controllo della policy FIPS o per il self-test all’accensione. Un token PKCS#11 riceve i dati da firmare, non contenuto del documento non correlato. Un HSM connesso in rete riceve tali dati sul canale di rete configurato. Il materiale delle chiavi resta all’interno del confine del token o dell’HSM.

Telemetria sicura e sanificazione dei log

Il PIN del token è un parametro sensibile del costruttore ed è escluso dai log e dalla serializzazione. Non aggiungere il PIN, la label del token o il materiale delle chiavi ai log della propria applicazione. Trattare tutte le credenziali del token come secret nella propria policy di logging e tracing.

Modello di minaccia

Questo è un confine crittografico, quindi il modello di minaccia è esplicito. I dati da firmare vengono consegnati al token; il token detiene la chiave. Un errore del token o dell’HSM solleva un’eccezione tipizzata; il firmatario non produce un risultato non firmato o parzialmente firmato. La protezione delle chiavi dipende dal token o dall’HSM, dalla distribuzione e dall’operatore — non da questo software da solo. Vedere il confine di distribuzione.

Conformità

Il modello di self-test all’accensione e condizionale si allinea a ISO/IEC 19790:2025 §7.10 e §7.10.3.
La lunghezza minima della chiave di firma RSA si allinea a NIST SP 800-131A Rev.2 §3.
L’accoppiamento approvato di curva e hash ECDSA si allinea a FIPS 186-5 §6.1.1.
L’operazione di firma del token PKCS#11 e il login di sessione si allineano a PKCS#11 v3.1 §5.
La responsabilità della protezione delle chiavi si allinea a NIST SP 800-57 Part 1 Rev.5 §5.5.2.
L’unicità del vettore di inizializzazione AES-GCM si allinea a NIST SP 800-38D §5.

Ogni sorgente normativa è parafrasata. Nessun testo normativo è riprodotto in questa pagina. Questa pagina riguarda la firma crittografica.

Comportamento in modalità FIPS

La policy in modalità FIPS limita le scelte crittografiche all’insieme approvato descritto sopra. Quando è configurata con un provider OpenSSL convalidato FIPS, la primitiva sottostante viene eseguita all’interno di quel confine convalidato. NextPDF Enterprise esegue di per sé l’assemblaggio strutturale, il calcolo del digest e l’applicazione della policy.

NextPDF Enterprise non è un modulo crittografico convalidato FIPS e non avanza alcuna rivendicazione di certificazione FIPS. NextPDF Enterprise opera in modalità FIPS-compatibile solo quando è configurato con un provider crittografico convalidato FIPS — per esempio un provider OpenSSL convalidato FIPS — o con un HSM convalidato FIPS. La policy in modalità FIPS assiste la conformità; non è una certificazione.

Confine di edizione

NextPDF Core include il firmatario software, il consumo delle marche temporali RFC 3161, la convalida del percorso RFC 5280 e il controllo della revoca OCSP e CRL. Core produce i livelli PAdES B-B e B-T. NextPDF Pro aggiunge il mascheramento, il rilevamento dei dati sensibili nel text-layer, la firma sequenziale multi-parte e le strategie di firma remote e cloud-KMS (AWS KMS, GCP Cloud KMS, Azure Key Vault). NextPDF Pro non fornisce un percorso con token hardware PKCS#11 e non fornisce un profilo di crypto-policy in modalità FIPS. Il firmatario con token hardware PKCS#11, il profilo di crypto-policy in modalità FIPS, la guardia di self-test all’accensione e il produttore PAdES B-LT e B-LTA sono inclusi esclusivamente nel pacchetto nextpdf/enterprise. Una distribuzione priva dell’entitlement Enterprise non carica le classi Enterprise.

Fallback Pro

In una distribuzione solo-Pro, il percorso di firma basato su hardware e su cloud supportato è la strategia cloud-KMS di Pro: un KMS cloud o un KMS basato su HSM detiene la chiave, e Pro invia il digest degli attributi firmati, non il documento, al provider. Pro fornisce l’integrazione KMS, non la factory di token PKCS#11 di Enterprise né il profilo in modalità FIPS. Una configurazione che richiede B-LT, B-LTA, un token PKCS#11 o il profilo in modalità FIPS in una distribuzione solo-Pro fallisce in modo chiuso con un messaggio che nomina il componente Enterprise mancante. Vedere Security — NextPDF Pro per la superficie di firma di Pro.

Fallback Core

In una distribuzione solo-Core, il firmatario software produce PAdES B-B e B-T con una chiave locale o una chiave fornita tramite il contratto di strategia di firma di Core. Core non ha alcun percorso con token hardware né profilo in modalità FIPS. Vedere Security — NextPDF Core.

Nota sul confine Enterprise

L’integrazione con il token PKCS#11, la sua mappatura dei meccanismi e la sua gestione delle sessioni sono descritte solo a livello di comportamento. La tabella interna di mappatura dei meccanismi, la logica interna di ripristino della sessione e il materiale di migrazione post-quantistica sono fuori ambito per la superficie pubblica e non sono qui riprodotti.

Confine di distribuzione

NextPDF Enterprise si integra con un token PKCS#11, un HSM o un KMS. Non archivia, genera né garantisce esso stesso la sicurezza della chiave di firma. La sicurezza della chiave dipende dal token, dall’HSM o dal KMS, dalla distribuzione e dall’operatore — non da NextPDF Enterprise da solo. L’operatore è responsabile del provisioning del token, della gestione del PIN, della configurazione dello slot, della protezione di rete di un HSM connesso in rete e della configurazione di fiducia. La responsabilità della protezione delle chiavi segue NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise non espone in questa documentazione la gestione del PIN del token, i dettagli interni di configurazione dello slot né il materiale di credenziali del fornitore.

Confine di conformità legale

Questa pagina riguarda la firma crittografica e l’integrazione con moduli di sicurezza hardware. La policy in modalità FIPS è una funzionalità di assistenza alla conformità. Non è un parere legale e non una certificazione. Consultare i propri consulenti legali e di conformità per i propri obblighi normativi.

Confine di pubblicazione

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

Contratto di comportamento

La guardia FIPS asserisce ogni hash, OID di firma, algoritmo di cifratura e robustezza della chiave rispetto al preset attivo e solleva una violazione tipizzata su una scelta non consentita.
Il self-test all’accensione viene eseguito una sola volta per processo e rifiuta i servizi crittografici in caso di fallimento del known-answer-test fino al reset.
Il firmatario con token PKCS#11 richiede ext-pkcs11; solleva un’eccezione di operazione tipizzata quando l’estensione è assente.
Il percorso di firma è fail-closed e non sostituisce mai un algoritmo più debole.

Vedere anche

Security — NextPDF Enterprise (riferimento approfondito)
Security — NextPDF Pro
Signature — NextPDF Enterprise
Accelerator — NextPDF Enterprise
Security — NextPDF Core
PAdES · HSM · PKCS#11 · FIPS mode · KMS — termini del glossario.