Enterprise edizione

Firma con modulo di sicurezza hardware (PKCS#11)

In sintesi

NextPDF Enterprise firma un PDF con una chiave custodita all’interno di un modulo di sicurezza hardware (HSM). Si indirizza il firmatario verso un token PKCS#11 — una smart card, un token Universal Serial Bus (USB) o un HSM collegato in rete — e l’operazione di firma viene eseguita sul dispositivo. La chiave privata non lascia mai il confine del token. Questa pagina è a livello di comportamento: indica ciò che il firmatario fa, ciò che si fornisce e dove la custodia delle chiavi cessa di essere responsabilità di NextPDF.

Il firmatario HSM viene risolto tramite il contratto del firmatario di Core, perciò la propria applicazione dipende dal contratto, non dal tipo concreto Enterprise. Estende lo stesso percorso di firma Cryptographic Message Syntax (CMS) che Core usa, con la differenza che l’operazione crittografica è delegata al token.

I prerequisiti sono indicati nel front matter e ripetuti in Prerequisiti, così da non essere colti di sorpresa a metà operazione.

Disponibilità e licenze

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

NextPDF Core include un firmatario CMS software che custodisce la chiave in-process o ne accetta una tramite il contratto di strategia di firma di Core; NextPDF Pro aggiunge strategie di firma remote e su key-management-service (KMS) cloud. La custodia delle chiavi su hardware tramite PKCS#11 è una capacità Enterprise, non fornita da Core o Pro.

Cosa fa questa capacità

Un token PKCS#11 espone oggetti crittografici — certificati e chiavi private — dietro una libreria condivisa del fornitore. Il firmatario Enterprise adatta tale libreria:

Apre la libreria condivisa del token una sola volta per processo e mette in cache l’handle del modulo, perché PKCS#11 richiede che il modulo sia inizializzato esattamente una volta per processo.
Apre una sessione sullo slot configurato ed effettua il login con il PIN fornito. Il login autentica l’utente prima di qualsiasi operazione sulla chiave privata, secondo PKCS#11 v3.1 §5.6.8.
Individua il certificato di firma sul token in base all’etichetta, legge il certificato in forma Distinguished Encoding Rules (DER) e rileva l’algoritmo della chiave pubblica.
Al momento della firma individua la chiave privata in base all’etichetta — che su alcuni token può differire dall’etichetta del certificato — e chiede al token di calcolare la firma. I dati da firmare vengono passati in ingresso; la chiave resta sul dispositivo.

Il firmatario supporta RSA con padding PKCS#1 v1.5 (SHA-256, SHA-384, SHA-512), RSA con padding Probabilistic Signature Scheme (PSS) in cui la lunghezza del salt è pari alla lunghezza del digest ed Elliptic Curve Digital Signature Algorithm (ECDSA) con SHA-256, SHA-384 e SHA-512. La curva e il digest ECDSA sono abbinati convenzionalmente — P-256 con SHA-256, P-384 con SHA-384, P-521 con SHA-512 — seguendo l’abbinamento raccomandato in RFC 5480. Un token restituisce una firma ECDSA come concatenazione grezza dei due interi; il firmatario la converte nella forma codificata in DER che il PDF e OpenSSL si aspettano.

Per la generazione delle firme, una chiave RSA di almeno 2048 bit e un ordine della curva ECDSA di almeno 224 bit sono i minimi accettabili secondo NIST SP 800-131A Rev.2 §3. Eseguire il provisioning della chiave del proprio token con tali dimensioni o superiori.

Esiste un percorso alternativo su OpenSSL-engine per i token supportati da engine. Su OpenSSL 3.x l’estensione PHP OpenSSL non espone l’application programming interface (API) dell’engine, perciò la classe dell’engine è deprecata; il percorso supportato per i token su engine esegue il binario da riga di comando di OpenSSL. Preferire il percorso PKCS#11 diretto quando il proprio token dispone di una libreria PKCS#11.

Perché funziona così

La decisione portante è che la chiave privata non lascia mai il token. Perciò il firmatario delega l’operazione crittografica al dispositivo e sposta soltanto i dati da firmare attraverso la giuntura PKCS#11. Non legge né ricostruisce mai il materiale di chiave nella memoria di PHP. Viene risolto tramite il contratto HsmSignerInterface di Core anziché tramite un tipo concreto Enterprise, perciò il codice di firma è identico che la chiave risieda in software, in un KMS cloud o in un token hardware. Mette in cache l’handle del modulo una sola volta per processo, perché PKCS#11 inizializza ciascun modulo esattamente una volta per processo, quindi converte l’output ECDSA grezzo del token in DER, così che i validatori vedano la codifica che si aspettano. È la custodia, non la comodità, a determinarne la forma: il confine di fiducia resta al margine del dispositivo.

Contesto di progettazione: firma supportata da HSM.

Prerequisiti

Prima di firmare con un HSM, confermare ciascun elemento:

Installare NextPDF Core e il pacchetto Enterprise: composer require nextpdf/core:^3 e composer require nextpdf/enterprise.
Disporre di una licenza NextPDF Enterprise attiva; risolvere il pacchetto con le credenziali della propria licenza su Private Packagist.
Installare la libreria condivisa PKCS#11 del fornitore del token sull’host (per esempio un .so su Linux o una .dll su Windows) e annotarne il percorso assoluto, il numero di slot e le etichette degli oggetti.
Caricare l’estensione PHP ext-pkcs11. Non è inclusa nel PHP standard e deve essere installata separatamente. Il costruttore del firmatario solleva un errore di operazione tipizzato quando l’estensione è assente.

Configurazione

Fornire questi input al firmatario:

Percorso della libreria — il percorso assoluto alla libreria condivisa PKCS#11 del fornitore.
Identificatore di slot — il numero di slot del token, in genere 0.
PIN — il PIN del token. Trattarlo come un segreto: fornirlo dal proprio gestore di segreti, mai dal codice sorgente o dai log. Il firmatario contrassegna il parametro PIN come sensibile, così da escluderlo dagli stack trace e dalla serializzazione.
Etichetta del certificato — l’etichetta dell’oggetto certificato sul token.
Etichetta della chiave — l’etichetta dell’oggetto chiave privata, quando differisce dall’etichetta del certificato.
Catena — certificati intermedi facoltativi in forma DER, quando il token non li detiene.

Verificare la disponibilità del token prima di costruire il firmatario. La costruzione legge il certificato dal token, perciò uno slot o un’etichetta configurati in modo errato falliscono rapidamente con un errore tipizzato anziché al momento della firma.

Passo per passo

Confermare che il runtime supporti PKCS#11 verificando la disponibilità dell’estensione. Non costruire il firmatario quando l’estensione è assente.
Leggere il PIN dal proprio gestore di segreti in una variabile che non viene mai registrata.
Costruire il firmatario HSM con il percorso della libreria, lo slot, il PIN e le etichette. La costruzione effettua il login e legge il certificato.
Passare il firmatario all’orchestratore di firma di Core tramite HsmSignerInterface. L’orchestratore calcola il byte range, costruisce gli attributi firmati CMS, consegna i dati al token e assembla il PDF firmato.
Catturare il fallimento più specifico, registrare un messaggio strutturale senza il PIN e rilanciare.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

Il cablaggio di produzione — l’esatto elenco di argomenti del costruttore e i tipi di eccezione tipizzati — è documentato nel riferimento approfondito HSM.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

Verifica

Confermare il risultato come farebbe un verificatore:

Rileggere dal firmatario il certificato del firmatario e la catena in forma DER e confermare che corrispondano al certificato di cui è stato eseguito il provisioning sul token.
Aprire il PDF firmato in un validatore configurato con i propri trust anchor e confermare che la firma sia riportata come crittograficamente intatta. Una firma prodotta non è una firma verificata; la decisione di fiducia spetta al verificatore e ai suoi trust anchor, non al produttore.
Per una firma ECDSA, confermare che la firma incorporata sia codificata in DER — il firmatario converte per conto dell’utente l’output grezzo del token, perciò un validatore che rifiuta la forma concatenata grezza dovrebbe comunque accettare la firma incorporata.
Confermare che nessun PIN, etichetta del token o materiale di chiave compaia nei log della propria applicazione.

Sicurezza e conformità

La chiave resta sul token. I dati da firmare vengono consegnati al token; l’operazione di firma viene eseguita all’interno del confine del token. La chiave privata non viene mai caricata nella memoria di PHP.
Il PIN è un segreto. È un parametro sensibile del costruttore, escluso dai log e dalla serializzazione. Fornirlo da un gestore di segreti. Ripetuti tentativi falliti di riautenticazione possono bloccare il PIN sul token; è il token, non NextPDF, a imporre tale politica.
Fail-closed. Un errore del token o dell’HSM solleva un’eccezione tipizzata. Il firmatario non produce un risultato non firmato o parzialmente firmato e non sostituisce mai un algoritmo più debole.
Robustezza dell’algoritmo. Eseguire il provisioning di chiavi RSA di almeno 2048 bit e di curve ECDSA con ordine di almeno 224 bit, i minimi accettabili per la generazione delle firme secondo NIST SP 800-131A Rev.2 §3.
La firma post-quantistica è sperimentale e disattivata per impostazione predefinita. Esiste un percorso post-quantistico dietro un flag di attivazione esplicito (opt-in). I profili standard PDF Advanced Electronic Signatures (PAdES) per l’archiviazione a lungo termine non riconoscono ancora le suite post-quantistiche, e la maggior parte dei visualizzatori le rifiuta in fase di convalida. Non abilitarlo per le firme PAdES di produzione.

Questa pagina riguarda la firma crittografica e l’integrazione con il modulo di sicurezza hardware. Ogni fonte normativa è parafrasata; nessun testo normativo è riprodotto. ### Confine di custodia delle chiavi

NextPDF Enterprise si integra con un token o un HSM PKCS#11. Non memorizza, genera né garantisce la sicurezza della chiave di firma. La sicurezza della chiave dipende dal token o dall’HSM, dalla distribuzione e dall’operatore — non da NextPDF Enterprise da solo. L’utente è responsabile del provisioning del token, della gestione del PIN, della configurazione dello slot e della protezione di rete di un HSM collegato in rete.

Gestione degli errori

Estensione assente. La costruzione del firmatario PKCS#11 solleva un’eccezione di operazione tipizzata quando ext-pkcs11 non è caricata. Verificare prima la disponibilità.
Certificato o chiave non trovati in base all’etichetta. La costruzione o la firma solleva un’eccezione tipizzata che nomina l’oggetto mancante. Confermare l’etichetta e lo slot.
Già autenticato. Quando più istanze del firmatario condividono un modulo in cache per lo stesso slot, il firmatario effettua il logout e di nuovo il login per fornire una verifica del PIN aggiornata — richiesta dai token personal-identity-verification con una politica «PIN ogni volta».
Algoritmo non supportato. La richiesta di un algoritmo che il firmatario non mappa solleva un errore di argomento anziché firmare con un sostituto.
HSM di rete irraggiungibile. Un errore di rete o del dispositivo solleva un’eccezione tipizzata; il firmatario non produce mai silenziosamente un documento non firmato.

Confine di pubblicazione

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

Vedere anche

Firma HSM — riferimento — il riferimento approfondito per il firmatario PKCS#11.
Security — NextPDF Enterprise — la superficie di sicurezza Enterprise combinata.
Signature — NextPDF Enterprise — il produttore a lungo termine PAdES B-LT e B-LTA.
FIPS 140 cryptographic policy — la policy in modalità FIPS e la protezione tramite self-test.
Cloud KMS signing — NextPDF Pro — strategie su key-management-service AWS, Azure e GCP.
Security / Signing (Core) — il firmatario CMS di Core e il contratto di strategia di firma.
HSM · PKCS#11 · CMS · ECDSA — termini del glossario.