Firma con HSM

Spec PKCS#11 v3.1 Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 Spec Spec: FIPS 140-3 FIPS 140-3 Evidence § Standard-backed Evidence: Standard-backed

In sintesi

Un modulo di sicurezza hardware (HSM) sposta la chiave di firma fuori dal processo, dietro un dispositivo che firma su richiesta ma non restituisce mai la chiave. Questa pagina illustra la giunzione PKCS#11 attraverso cui NextPDF firma, dove si colloca esattamente il confine della chiave e quali parti del risultato sono responsabilità del motore, non del dispositivo o dell’operatore.

Perché è importante

Una chiave di firma nella memoria del processo può essere letta da qualunque elemento in grado di leggere il processo: un dump dell’heap, un debugger, un errore di logging, una dipendenza affetta da una vulnerabilità. Una volta copiata una chiave privata, ogni firma prodotta con quella chiave diventa dubbia e non se ne può annullare la fuoriuscita. La ragione d’essere di un HSM è proprio evitare che esista una copia da sottrarre.

Sbagliare il confine ha un costo alto e silenzioso. Un flusso che sembra basato su hardware ma porta la chiave in memoria per firmare ha il costo operativo di un HSM e il profilo di rischio di una chiave software. La distinzione non è visibile nel PDF finito, quindi va progettata e verificata, non presunta.

In breve

• Lo standard PKCS#11 definisce un oggetto chiave contrassegnato come sensibile e non estraibile. Il suo valore privato non può essere rivelato in chiaro al di fuori del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9
• NextPDF costruisce la struttura della firma PDF e il contenitore CMS. Passa i byte da firmare attraverso la giunzione PKCS#11 e riceve in cambio la firma. La chiave non attraversa mai quella giunzione.
• La giunzione è un contratto stabile. Lo stesso contratto è soddisfatto da un token smart-card, un HSM USB, un HSM di rete e un KMS cloud. Il codice del motore non cambia tra di essi.
• NextPDF è un motore software di firma. La garanzia hardware del dispositivo, il suo stato di convalida, la policy del PIN e il deployment non sono elementi che il motore certifica. Usa il dispositivo; non garantisce per esso.

Come lo affronta NextPDF

La giunzione, in dettaglio

NextPDF separa l’assemblaggio di una firma dal calcolo del valore della firma. L’assemblaggio è compito del motore: posizionare il campo firma, riservare spazio nel file, calcolare l’intervallo di byte e costruire il CMS SignedData con i suoi attributi firmati. Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8

Il calcolo del valore della firma è delegato. Il motore definisce un piccolo contratto di provider di firma: riceve una stringa di byte opaca (di fatto gli attributi firmati codificati in DER) e restituisce gli ottetti di firma grezzi. Quel contratto è la giunzione. Da un lato c’è la conoscenza di PDF e CMS; dall’altro c’è una chiave. Un provider può custodire quella chiave nel processo nel caso di una chiave software locale, in un KMS cloud o su un token hardware tramite PKCS#11. Il codice del motore al di sopra della giunzione è identico in ogni caso. Cambia solo il provider che vi sta dietro.

Dove si colloca effettivamente il confine

PKCS#11 — l’OASIS Cryptographic Token Interface, storicamente «Cryptoki» — è l’interfaccia C standard per i token hardware. Il percorso hardware di NextPDF comunica via PKCS#11 (direttamente o tramite un bridge a riga di comando OpenSSL per deployment con engine o provider in cui il binding in-processo non riesce a caricare un token).

L’oggetto chiave sul token viene creato con due attributi che definiscono il confine. Quando la chiave è contrassegnata come sensibile o non estraibile, determinati attributi privati non possono essere rivelati in chiaro al di fuori del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 L’operazione di firma stessa è una singola chiamata al token — C_SignInit seguita da C_Sign — eseguita dal dispositivo. Spec Spec: PKCS#11, v3.1 §5.10 PKCS#11 v3.1 §5.10 Il testo in chiaro che entra in NextPDF è costituito dai byte da firmare. Ciò che torna indietro sono la firma e il certificato. La chiave privata non si trova su nessuno dei due percorsi. Questo è il confine, e a imporlo è il token, non la libreria.

1. Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
2. Step 2 of 4: RFC 5652 CMS SignedData — the signature container RFC 5652 CMS SignedData — the signature container
3. PKCS#11 v3.1 — token interface; sensitive, non-extractable key
4. Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent) FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Dove una firma PDF basata su hardware trova fondamento, in ordine: il vettore PDF (ISO 32000-2 §12.8), il contenitore CMS che esso racchiude, l'interfaccia del token attraverso cui firma NextPDF (PKCS#11) e gli standard di garanzia del modulo che descrivono — ma non garantiscono di per sé — il dispositivo che vi sta dietro.

Un PIN, una riautenticazione

PKCS#11 consente a una chiave di richiedere la ri-autenticazione a ogni uso: quando l’attributo CKA_ALWAYS_AUTHENTICATE è impostato, l’utente deve presentare il PIN di nuovo per ciascuna operazione crittografica, non una volta per sessione. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 Il percorso PKCS#11 di NextPDF è progettato per questo. Il PIN è un parametro sensibile. Non viene registrato né serializzato. Quando una sessione segnala un login esistente, NextPDF la riporta a uno stato pulito, così che la firma successiva sia sottoposta a un nuovo controllo del PIN. Questo è importante per i token in stile PIV la cui policy richiede un PIN per ogni firma. È un comportamento del motore che rispetta la policy del dispositivo; non la allenta.

Cosa dicono le evidenze

Evidence § Standard-backed Evidence: Standard-backed La proprietà di non estraibilità della chiave non è un’affermazione di NextPDF. È il modello PKCS#11: un oggetto chiave il cui CKA_SENSITIVE è vero o il cui CKA_EXTRACTABLE è falso non rivela il suo valore privato in chiaro al di fuori del token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 Il contributo di NextPDF è il fatto di non aver mai bisogno di quel valore: firma attraverso l’operazione C_Sign del token anziché chiedere il materiale della chiave.

Evidence § Standard-backed Evidence: Standard-backed Il lato PDF è ancorato a Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . Il digest dell’intervallo di byte è calcolato sul file escludendo il valore della firma. Il valore della firma inserito nella voce Contents è un oggetto CMS SignedData codificato in DER per le firme a chiave pubblica. L’HSM produce solo gli ottetti di firma più interni. NextPDF costruisce tutto attorno ad essi e li scrive nella struttura definita dallo standard.

Evidence § Standard-backed Evidence: Standard-backed La garanzia del dispositivo è descritta da Spec Spec: FIPS 140-3 FIPS 140-3 e dal suo standard di base ISO/IEC 19790, che definiscono quattro livelli di sicurezza qualitativi crescenti, articolati in undici aree di requisiti — dalla specifica dell’algoritmo all’evidenza fisica di manomissione. Questi standard descrivono ciò che un modulo deve soddisfare per dichiarare un livello. Sono una proprietà del dispositivo e della sua convalida, non di NextPDF e — secondo le parole dello stesso ISO/IEC 19790 — la conformità non è di per sé sufficiente a garantire che un modulo sia sicuro in un dato deployment.

Human-factors note: Human-factors note

Questa pagina enuncia deliberatamente il confine prima del meccanismo e colloca il costo di sbagliarlo vicino all’inizio. In un dominio critico per la sicurezza, l’ordine corretto è prima l’avvertenza, poi il come. Un flusso che carica silenziosamente una chiave in memoria fallisce in un modo che non si vede nell’output, perciò la trappola viene nominata prima della ricetta. La riga dei badge indica già che la pagina è basata su standard prima ancora di leggere una frase del corpo del testo.

Esempio pratico

L’esempio riportato di seguito è illustrativo. Mostra la giunzione, non un deployment da copiare e incollare. Il punto è che al motore viene consegnato un signer e che il motore non vede mai una chiave: il metodo sign() del signer è una chiamata al dispositivo.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Due precisazioni su questa forma. Il binding PKCS#11 in-processo è un’estensione PHP separata che le build PHP standard non includono. Un deployment hardware lo installa e lo verifica (oppure usa il bridge a riga di comando OpenSSL) come parte della piattaforma, non come un’aggiunta a posteriori. E l’algoritmo richiesto al dispositivo deve essere un algoritmo che la chiave è effettivamente in grado di eseguire. Il motore rifiuta immediatamente quando l’algoritmo configurato non ha alcuna corrispondenza per il provider scelto, anziché fallire più avanti dentro una chiamata al token.

Equivoco comune

«Usare un HSM significa che la firma è convalidata FIPS.»

Non è così, e confondere le due cose è il punto insidioso. Un HSM è il luogo in cui risiede la chiave e in cui viene eseguita l’operazione. La convalida FIPS 140-3 / ISO/IEC 19790 è una proprietà che il dispositivo (o una specifica configurazione del modulo) può possedere, stabilita da un programma di convalida — non qualcosa che una libreria chiamante conferisce né qualcosa che NextPDF afferma per conto di un dispositivo. NextPDF è compatibile con la firma attraverso un dispositivo PKCS#11 e il suo percorso di firma è stato testato con token rappresentativi della categoria. Che un dato deployment sia convalidato a livello di modulo FIPS dipende interamente dall’hardware, dal suo certificato e dal modo in cui è configurato e gestito. Va usata la parola precisa per ciò che esiste effettivamente.

Limiti e confini

Questa pagina descrive la giunzione e gli standard su cui poggia. Non è una garanzia di deployment, e il confine merita di essere enunciato con chiarezza:

• Responsabilità del motore. Costruire il campo firma, riservare spazio, calcolare l’intervallo di byte, assemblare il CMS SignedData, chiamare il provider di firma e scrivere una firma strutturalmente corretta secondo Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . Il percorso hardware di NextPDF è **conforme all’**interfaccia di firma PKCS#11 per questo scopo.
• Responsabilità del dispositivo e dell’operatore. La resistenza alla manomissione dell’hardware, il suo stato di convalida FIPS 140-3 / ISO/IEC 19790, la generazione e la custodia delle chiavi, la policy del PIN, la configurazione degli slot, il firmware e la sicurezza fisica. Nessuno di questi aspetti è certificato dal motore.
• Testato con non significa certificato. Il fatto che NextPDF disponga di un percorso verificato rispetto a categorie di token rappresentative — forme smart-card, USB, di rete e cloud-KMS raggiunte attraverso lo stesso contratto PKCS#11 — è una dichiarazione di compatibilità. Non è una certificazione, un conteggio di moduli convalidati o un’affermazione sul dispositivo specifico in uso. Le categorie hardware riportate di seguito sono forme di integrazione attraverso un’unica interfaccia standard. Vanno trattate come «dove la giunzione è stata esercitata», mai come una garanzia per un modello non testato direttamente.
• La firma post-quantistica è sperimentale. Quando il motore espone la firma post-quantistica attraverso un token, è opt-in, soggetta a gate e convalidata su mock anziché su firmware HSM post-quantistico. I cataloghi di suite crittografiche PAdES e AdES non riconoscono ancora quelle suite per l’archiviazione a lungo termine. Non va trattata come pronta per la produzione.

HSM-backed signing via PKCS#11 — edition availability

Edition	Availability
Core	○ Non in questa edizione. Core fornisce il motore di firma e la giunzione del provider di firma, con un provider locale di chiave software.
Pro	○ La gestione delle chiavi cloud — firmare attraverso chiavi KMS gestite — è una funzionalità Pro, descritta solo a livello di comportamento.
Enterprise	○ Disponibile. La firma con token hardware attraverso l’interfaccia PKCS#11 (e un bridge a riga di comando OpenSSL per i deployment con engine/provider) è una funzionalità Enterprise. La disponibilità è una dichiarazione funzionale, non una certificazione di un qualsiasi dispositivo o deployment.

Forme di integrazione attraverso un’unica interfaccia

Queste sono le forme rispetto alle quali la giunzione PKCS#11 è stata esercitata. La colonna indica «che aspetto ha l’integrazione», non «un elenco di dispositivi convalidati, certificati o conteggiati».

Forma di integrazione	Come si raggiunge	Confine della chiave	La garanzia è una proprietà di
Token smart-card / PIV	Modulo PKCS#11; PIN per l’uso ordinario	Sulla card; non estraibile	La card e il suo operatore
HSM USB	Modulo PKCS#11	Sul dispositivo; non estraibile	Il dispositivo e il suo operatore
HSM di rete / appliance	Modulo PKCS#11 verso un dispositivo di rete	Sull’appliance; non estraibile	L’appliance, la sua configurazione, l’operatore
KMS cloud	Provider di chiavi gestite (Pro)	Nel servizio cloud; mai restituita	Il provider cloud e le sue attestazioni
Bridge provider OpenSSL	PKCS#11 tramite un bridge OpenSSL	Sul token; non estraibile	Il token e il suo operatore

Mini-FAQ

La chiave entra mai nel processo PHP? No. Per una chiave PKCS#11 non estraibile, il valore privato non può essere rivelato in chiaro al di fuori del token. NextPDF firma attraverso l’operazione del token e vede sempre e solo i byte da firmare e la firma restituita.

Una firma basata su HSM ha una struttura diversa all’interno del PDF? No. La struttura della firma è lo stesso CMS SignedData nella stessa voce Contents sullo stesso intervallo di byte. L’HSM cambia dove avviene la firma, non la forma su disco.

Posso rivendicare la conformità FIPS perché ho usato un HSM attraverso NextPDF? Solo con cautela. NextPDF non afferma nulla sullo stato FIPS di un dispositivo. Qualsiasi rivendicazione di questo tipo deve derivare dalla convalida propria del dispositivo e dal modo in cui è gestito, non dal fatto che NextPDF lo abbia invocato.

E se il binding PKCS#11 in-processo non è disponibile? Il motore segnala che la firma hardware non è disponibile anziché ripiegare silenziosamente su una chiave software. Esiste un percorso bridge a riga di comando OpenSSL per i deployment in cui il binding in-processo non riesce a caricare un token.

Documenti correlati

• Firme qualificate, spiegate — perché una chiave hardware è necessaria ma non sufficiente, e quali ruoli NextPDF non ricopre.
• Come le firme si collocano in un PDF — il meccanismo dell’intervallo di byte e del dizionario di firma in cui viene scritto il risultato dell’HSM.
• Gestire NextPDF in produzione — la superficie operativa a carico di un deployment di firma hardware.

Glossario

• HSM (modulo di sicurezza hardware) — un dispositivo rafforzato che custodisce le chiavi ed esegue operazioni crittografiche in modo che il materiale della chiave non lasci mai il dispositivo.
• PKCS#11 — lo standard OASIS Cryptographic Token Interface (storicamente «Cryptoki»); l’interfaccia C che NextPDF usa per comunicare con i token hardware.
• Chiave non estraibile — un oggetto chiave PKCS#11 il cui valore privato non può essere rivelato in chiaro al di fuori del token (CKA_SENSITIVE vero o CKA_EXTRACTABLE falso).
• La giunzione — il confine del provider di firma in NextPDF: byte opachi in ingresso, ottetti di firma in uscita. La conoscenza di PDF e CMS sta al di sopra di quel confine; la chiave sta dietro di esso.
• CMS SignedData — la struttura Cryptographic Message Syntax (RFC 5652) che trasporta la firma e i certificati all’interno del PDF.
• FIPS 140-3 / ISO/IEC 19790 — standard di sicurezza per moduli crittografici che definiscono quattro livelli qualitativi; una proprietà di un dispositivo e della sua convalida, non di una libreria chiamante.