Applicare una firma digitale PAdES in NextPDF Connect (Pro)

In sintesi

Applicare a un PDF, in NextPDF Connect, una firma digitale PAdES baseline. Lo strumento è sign_pdf, verificato di nuovo rispetto al tool provider Pro: questo provider registra new SignPdfTool(), il cui nome di protocollo è sign_pdf. sign_pdf è uno strumento di livello Pro. Il server lo rileva con class_exists() all’avvio e lo registra solo quando il pacchetto Pro è installato.

Per impostazione predefinita, lo strumento produce PAdES B-B. Può produrre PAdES B-T (B-B più una RFC 3161 signature-time-stamp) solo quando l’host ha collegato un provider di marca temporale allo strumento; la richiesta non può indicare una TSA. I livelli a lungo termine (B-LT, B-LTA) e il relativo materiale di validazione (DSS, VRI, LTV) non fanno parte di questo strumento e qui sono fuori ambito.

Avvertenza U-1. NextPDF non rivendica alcuna certificazione indipendente ETSI EN 319 142-1 per PAdES B-T. EN 319 142-1 non è nel corpus di verifica. Il requisito B-T signature-time-stamp è verificato rispetto a ETSI EN 319 122-1 §5.3 (la base CAdES che EN 319 142-1/-2 importano per riferimento), insieme a RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8. Il supporto al profilo B-T non è una certificazione di conformità o di validità legale; è un validatore indipendente a stabilirlo.

Installazione

composer require nextpdf/server
composer require nextpdf/pro

Collegare un trasporto. Verificare che sign_pdf esista con diagnostic.capabilities. Per B-T, l’host deve costruire lo strumento con un provider di marca temporale. In sua assenza, una richiesta pades_b_t: true fallisce con un errore tipizzato invece di effettuare un downgrade silenzioso.

Panoramica concettuale

sign_pdf calcola un digest byte-range sul file, escludendo il segnaposto del valore di firma (ISO 32000-2 §12.8.1). Scrive quindi i dati CMS SignedData codificati in DER nel dizionario di firma Contents (ISO 32000-2 §12.8.1). Algoritmi supportati: RSA-SHA256 (predefinito), RSA + SHA-3 (256/384/512) ed Ed25519. Un envelope AES-GCM opzionale può incapsulare il payload private_key in ingresso per i trasporti non confidenziali end-to-end.

Upgrade a B-T. Con pades_b_t: true e un provider di marca temporale collegato dall’host, la firma viene portata a PAdES B-T: l’hash byte-range viene inviato a una TSA e viene incorporato un TimeStampToken (ISO 32000-2 §12.8.5). B-T è esattamente B-B più una RFC 3161 signature-time-stamp trasportata come attributo non firmato sul CMS SignerInfo (RFC 5652 §5.3). Gli attributi non firmati non sono coperti dalla firma, quindi il digest firmato B-B e la sua validità restano invariati (RFC 5652 §5.3). Il valore dell’attributo è un SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T non aggiunge alcun dizionario DSS, alcun VRI, alcun materiale di validazione e alcun ciclo di archive-timestamp — quel materiale rientra nel delta Enterprise B-LT/B-LTA ed è fuori dall’ambito di questo strumento.

Avvertenza U-1 (ripetuta alla rivendicazione B-T). Il supporto B-T qui non è una certificazione di conformità EN 319 142-1 o di validità legale; è un validatore indipendente a deciderlo. EN 319 142-1 non è nel corpus di verifica. B-T è basato su ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8.

Il flusso dello strumento — incluso il punto di integrazione TSA gestito dall’host (la richiesta non può indicare una TSA) e il ramo B-T fail-closed (mai un downgrade silenzioso) — è mostrato di seguito.

Diagram

Superficie API

Strumento	Livello	Ruolo	Livello di rischio
`create_pdf`, `add_text`	Core	Creare il contenuto	Sicuro / Attenzione
`sign_pdf`	Pro	Applicare PAdES B-B (o B-T gestito dall’host)	Approvazione richiesta
`output_pdf`	Core	Eseguire il rendering e restituire il PDF	Approvazione richiesta / Revisione (base64)

I nomi degli strumenti sono i nomi di protocollo del registry; il catalogo degli strumenti è il catalogo di riferimento. Gli strumenti disponibili dipendono dal livello installato; gli strumenti dei livelli a lungo termine non sono presenti in Pro.

Esempio di codice — Avvio rapido

create_pdf → creare il contenuto con add_text.
sign_pdf con certificate (PEM), private_key (PKCS#8 PEM), signer_name opzionale, reason e algorithm. Omettere pades_b_t (o impostarlo a false) per B-B.
output_pdf.

Lo strumento restituisce questo envelope di risultato:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Per richiedere una firma B-T gestita dall’host, inviare pades_b_t: true; level diventa "PAdES-B-T" e timestamped diventa true.

Esempio di codice — Produzione

Firmare come ultima operazione sul contenuto. Qualsiasi add_text/add_image dopo sign_pdf invalida la firma. Su un trasporto non confidenziale, incapsulare private_key nell’envelope AES-GCM transport_encryption (nonce di 12 byte; chiave di 16/24/32 byte). Verificare che il level del risultato corrisponda a quanto richiesto. Una richiesta pades_b_t: true su uno strumento senza provider fallisce esplicitamente: gestire tale errore e non riprovare in silenzio come B-B.

Casi limite e insidie

Mancata corrispondenza certificato/chiave. Respinta con un errore chiaro; la chiave privata deve corrispondere alla chiave pubblica del certificato.
PEM malformato / certificato scaduto. Respinto; per impostazione predefinita, lo strumento non firma con un certificato non analizzabile o scaduto.
Contenuto dopo la firma. Respinto — firmare per ultimo.
B-T richiesto, nessun provider. Errore tipizzato: la firma non viene prodotta e non viene declassata silenziosamente a B-B.
Certificato autofirmato. La firma viene applicata, ma i lettori mostrano un livello di trust sconosciuto — è previsto, non un difetto dello strumento.
Pro assente. Con il solo Core, sign_pdf non è registrato.

Prestazioni

La firma aggiunge la costruzione del CMS e, per B-T, un round-trip TSA; il budget copre tutto questo. Il profilo è semantic: un token RFC 3161 è intrinsecamente non riproducibile e il digest byte-range §12.8.1 esclude il valore di firma, quindi solo un confronto di AST + metadati di firma è corretto.

Note di sicurezza

Una firma fornisce integrità e autenticazione rispetto alla chiave di firma. Di per sé non rende un documento “sicuro” o “legalmente valido”, né garantisce il non ripudio — ciò dipende dal certificato, dal suo trust anchor, dalla custodia della chiave e dalla policy del verificatore, tutti fattori esterni a questo strumento. La cifratura del payload della chiave (envelope AES-GCM) protegge la riservatezza in transito, non l’integrità. Trattare la chiave privata come un segreto e preferire l’envelope di cifratura del trasporto su qualsiasi canale non confidenziale.

Conformità

Dichiarazione	Specifica	Clausola
Il digest byte-range copre il file ed esclude il valore di firma.	ISO 32000-2	§12.8.1
`Contents` contiene i dati CMS SignedData codificati in DER.	ISO 32000-2	§12.8.1
Per una marca temporale, l’hash byte-range va a una TSA e il token viene inserito in `Contents`.	ISO 32000-2	§12.8.5
La marca temporale B-T è un attributo non firmato su SignerInfo.	RFC 5652	§5.3
Gli attributi non firmati non modificano il digest/validity firmato B-B.	RFC 5652	§5.3
Il valore signature-time-stamp è un SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF produce la struttura di firma. Non asserisce che una firma risultante sia conforme o legalmente valida — è un validatore indipendente a deciderlo. B-LT/B-LTA non sono prodotti da questo strumento.

Contesto commerciale

sign_pdf è uno strumento di livello Pro, registrato solo quando il pacchetto Pro viene risolto all’avvio del server. I livelli PAdES a lungo termine (B-LT, B-LTA) e il relativo materiale di validazione (DSS, VRI, LTV) sono solo Enterprise e non sono esposti da questo strumento o da questa ricetta.

Residenza dei dati e mitigazioni PII

Il certificato e la chiave privata transitano nella richiesta. Usare l’envelope AES-GCM transport_encryption su qualsiasi canale che non sia confidenziale end-to-end. Il PDF firmato e l’identità del firmatario (signer_name, reason) fanno parte del contenuto del documento, quindi mantenerli entro i confini di residenza dei dati. La residenza a livello di deployment è responsabilità dell’integratore.

Telemetria sicura e scrubbing dei log

Non registrare mai il payload private_key, la key/nonce AES-GCM o il token di conferma. Registrare l’algoritmo, il level risultante e signature_count — non il materiale della chiave. Lo strumento non emette byte della chiave nel risultato.

Modello di minaccia

Minacce considerate: divulgazione della chiave in transito (mitigata dall’envelope AES-GCM e dal provider TSA iniettato dall’host e non configurabile dalla richiesta); un chiamante MCP che indirizza la marca temporale a un endpoint arbitrario (impedito — il provider è iniettato dall’host, non configurabile dalla richiesta); e manomissione post-firma (il digest byte-range rileva la modifica). Un modello di minaccia documenta le minacce considerate e le mitigazioni; non asserisce l’assenza di vulnerabilità.

Comportamento in modalità FIPS

La selezione dell’algoritmo (RSA-SHA256, RSA + SHA-3, Ed25519) è guidata dalla richiesta; l’OpenSSL dell’host fornisce le primitive crittografiche. In un deployment vincolato a FIPS, limitare l’algoritmo a livello di policy e affidarsi al modulo validato dell’host. Questo strumento, di per sé, non asserisce la validazione FIPS.

Disponibilità del trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì (Pro)	Usare l’envelope di chiave AES-GCM su stdio.
REST	Sì (Pro)	Preferire TLS più l’envelope di chiave.
gRPC	Sì (Pro)	Preferire TLS più l’envelope di chiave.

Livello di rischio HITL

sign_pdf è Approvazione richiesta (un’operazione distruttiva e irreversibile — lo strumento espone un hint distruttivo). Il gate di conferma si applica come per qualsiasi strumento Approvazione richiesta. Anche output_pdf su file è Approvazione richiesta; la modalità base64 è Revisione (livelli di rischio HITL).

Envelope JSON del gate di conferma

sign_pdf senza un token valido restituisce l’envelope di sfida:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Richiamare con _confirmation_token impostato sul token → { "allowed": true }. Flusso completo: output-approval.