Security — Riferimento approfondito

In breve

Questo è il riferimento approfondito per la superficie di sicurezza di NextPDF Pro: mascheramento in fase di generazione, rilevamento dei dati sensibili sul text layer, la sessione di firma remota e con KMS cloud, la firma sequenziale multi-parte, il percorso di ingest CAdES e XAdES, il livello baseline PAdES B-B e il supporto alla firma PAdES B-T (una firma B-B più una marca temporale di firma RFC 3161 sul valore della firma). Dichiara il contratto dell’API pubblica, il comportamento osservabile dall’esterno e il confine Enterprise B-LT/B-LTA. È a livello di comportamento; non cita alcun percorso di implementazione interno.

Disponibilità e licenza

Questa capability è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza.

Core distribuisce il signer CMS software, il client di timestamp RFC 3161, la validazione del percorso RFC 5280 e il controllo della revoca OCSP e CRL. Pro aggiunge il mascheramento, il rilevamento dei dati sensibili, la superficie di firma remota e con KMS cloud e il supporto alla firma PAdES B-T (compone lo stack RFC 3161 di Core per aggiungere una marca temporale di firma) qui descritti. Il flag di capability per questa superficie è pro: un deployment privo di un entitlement Pro attivo non carica queste classi, il contratto di firma di Core continua a funzionare invariato, e il codice che dipende dal contratto di Core non si interrompe quando l’entitlement è assente.

Installazione

composer require nextpdf/pro:^3

Contratto di comportamento

Il motore di mascheramento applica una lista ordinata di regole al testo prima che la pagina venga scritta. Una regola corrisponde a un pattern PCRE e sostituisce una corrispondenza in una di tre modalità:

• BlackBox — rimuove il testo corrispondente dal content stream e riserva una regione di riempimento. Questa modalità rimuove gli oggetti di testo sottostanti, come verificato dai test.
• Asterisks — sostituisce ogni carattere corrispondente con un asterisco, preservando il conteggio dei caratteri.
• FixedLabel — sostituisce l’intera corrispondenza con un’etichetta configurabile, [REDACTED] per impostazione predefinita.

Una regola si costruisce da un literal esatto tramite MaskingRule::exactMatch (il literal viene sottoposto a escape per le regex) oppure da un pattern PCRE personalizzato tramite MaskingRule::regex. MaskingConfig contiene la lista ordinata di regole, una modalità predefinita e il colore di riempimento. MaskingConfig::fromArray analizza una mappa di configurazione e scarta silenziosamente una voce di regola priva di un pattern stringa utilizzabile, anziché far fallire l’intera importazione.

La superficie PII estrae il text layer del PDF, quindi applica pattern integrati per indirizzi e-mail, numeri di telefono, numeri di previdenza sociale degli Stati Uniti e numeri di carta di credito. Restituisce un risultato strutturato: un valore booleano che indica se è stata trovata una corrispondenza, un conteggio delle corrispondenze, la vista mascherata del testo e la lista dei tipi analizzati. Il chiamante può restringere la scansione a un sottoinsieme dei quattro tipi. La superficie non sovrascrive i glifi della pagina renderizzata; una pagina scansionata priva di text layer non produce corrispondenze. Trattare il risultato come rilevamento di pattern sul text layer dei tipi configurati, non come rimozione completa dei dati personali e non come dichiarazione di conformità normativa.

La sessione di firma è in due fasi. RemoteSigningSession::create apre una sessione. prepare calcola il digest del documento sulle due regioni ByteRange, quindi costruisce gli attributi firmati CMS. complete invoca la strategia e incorpora il risultato; suspend serializza la sessione affinché un worker possa riprenderla più tardi con resume e completeWithRawSignature. La sessione assembla un CMS SignedData e lo archivia codificato in DER nella voce Contents del dizionario di firma — ISO 32000-2 §12.8.1. Quando viene fornito un certificato X.509 analizzabile, la sessione emette l’intero insieme obbligatorio di attributi firmati PAdES B-B: content-type, message-digest, signing-time, signing-certificate-v2 e un attributo di protezione dell’algoritmo — RFC 5652 §5.3 e RFC 5652 §5. Il verificatore ricalcola il digest del contenuto e lo confronta con l’attributo message-digest; il confronto deve corrispondere affinché la firma sia valida — RFC 5652 §5.4.

Quando il livello PAdES configurato è B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T), oppure tramite SequentialSigner::withTimestamping) ed è collegato un timestamp provider, la sessione incorpora inoltre esattamente una signature-time-stamp RFC 3161 come attributo CMS non firmato sul primo SignerInfo. Una signature-time-stamp è un attributo non firmato che trasporta una marca temporale calcolata sul valore della firma digitale per un firmatario — ETSI EN 319 122-1 §5.3; il suo MessageImprint è l’hash del valore del campo di firma del SignerInfo escludendo il tag e la lunghezza ASN.1 — ETSI EN 319 122-1 §5.3 e RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Poiché la marca temporale è un attributo non firmato, gli attributi firmati B-B, il message-digest, il valore della firma del SignerInfo e il /ByteRange del PDF sono identici byte per byte all’output B-B; cresce soltanto il CMS per via dell’attributo non firmato, e lo spazio /Contents riservato per il B-T viene aumentato affinché vi rientri. La marca temporale viene richiesta al timestamp provider configurato (il client RFC 3161 di Core predefinito, oppure un provider fornito dal chiamante). Sul percorso del provider predefinito il digest dell’imprint è SHA-256; la forma legacy ESSCertID v1 vincolata a SHA-1 viene rifiutata ed è richiesto ESSCertIDv2 — RFC 5816 §1. Un guasto della TSA, una richiesta rifiutata, un nonce o un echo dell’imprint del messaggio errati, una marca temporale malformata o con algoritmo non supportato, oppure una marca temporale che fallisce la verifica crittografica, emergono come un’eccezione PadesBt tipizzata con l’eccezione Core originaria preservata come throwable precedente. NextPDF Pro implementa il supporto alla firma PAdES B-T secondo ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 e RFC 5816, ed è verificato con fixture; non asserisce una certificazione ETSI EN 319 142-1 indipendente e non asserisce la validità legale del documento.

SequentialSigner coordina la firma multi-parte. Ogni firmatario è una revisione di incremental update separata. Il primo firmatario può essere una firma di certificazione con una restrizione DocMDP impostata tramite certifyFirst. PadesWrapper esegue l’ingest di una firma esistente: fromCades incorpora direttamente una struttura CMS, fromXades analizza un documento XAdES e ne riutilizza il materiale di firma principale, e detect seleziona automaticamente in base al formato. Il percorso XAdES riutilizza il certificato, la catena, il valore della firma e l’algoritmo; non trasferisce le qualifying properties XAdES.

Superficie API pubblica

composer require nextpdf/pro:^3

Tipo	Genere	Ruolo	Stabilità	Da
RemoteSigningSession	classe	Sessione di firma remota o asincrona in due fasi	stable	1.9.0
RemoteSigningConfig	classe	Configurazione immutabile della sessione, incluso il livello PAdES e l’algoritmo	stable	1.9.0
SequentialSigner	classe	Firma sequenziale multi-parte con supporto DocMDP	stable	1.9.0
SequentialSigningResult	classe	Risultato di un’esecuzione sequenziale: byte del PDF, catena, conteggio, completezza	stable	1.9.0
SigningStrategy	interface	Il contratto del meccanismo di firma che una sessione invoca	stable	1.9.0
PadesWrapper	classe	Avvolge una firma CAdES o XAdES esistente per l’incorporamento PAdES	stable	1.9.0
KmsSignerInterface	interface (SPI)	Contratto di driver HSM e KMS di terze parti; estende il contratto del signer HSM di Core	stable	2.1.0
SignatureAlgorithm	enum	OID di algoritmo di firma Pro e nomi di digest	stable	2.1.0
GenerationTimeMasker	classe	Mascheramento basato su regole applicato prima che la pagina venga scritta	stable	1.9.0
MaskingConfig	classe	Configurazione di mascheramento immutabile	stable	1.9.0
MaskingRule	classe	Una singola regola di mascheramento (literal o PCRE)	stable	1.9.0
MaskingMode	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

Contratto SigningStrategy

Una strategia opera sugli attributi firmati codificati in DER e restituisce i byte della firma grezza. È la sessione, non la strategia, ad assemblare il CMS SignedData. Una strategia espone il certificato del firmatario in DER, la catena in DER ordinata da foglia a radice, l’OID dell’algoritmo di firma, il nome dell’algoritmo di digest e un flag isAsync che contrassegna una strategia la cui sessione può essere serializzata e ripresa.

SPI KmsSignerInterface

KmsSignerInterface estende il contratto del signer HSM di Core. Aggiunge un providerId stabile per la ricerca nel registro, un metodo signWithVersion con un parametro esplicito di versione della chiave per ogni chiamata, e supportsAlgorithm e supportedAlgorithms, così che un chiamante scopra la compatibilità dell’algoritmo prima della chiamata di firma. Gli identificatori di provider integrati riservati sono aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli e openssl-engine. Un driver di terze parti deve assegnare al proprio identificatore un namespace per evitare una collisione. La semantica predefinita della versione della chiave varia per provider: un provider che risolve gli alias risolve la chiave attiva dall’alias quando la versione è null; un provider che seleziona l’ultima versione abilitata lo fa tramite il proprio transport; un provider privo del concetto lato server di versione attiva deve usare una versione fissata nella propria configurazione e deve sollevare un errore di gestione delle chiavi quando né la chiamata né la configurazione fissano una versione. Una versione non vuota fissa quella versione, e il provider deve sollevare un errore di gestione delle chiavi quando la versione è sconosciuta, disabilitata o revocata.

Casi limite e accorgimenti

• Una firma prodotta non è una firma verificata. La validazione del percorso viene eseguita presso il verificatore con i trust anchor e i controlli di basic-constraint di quel verificatore — RFC 5280 §6.1. Il produttore non può asserirne il risultato.
• La sessione dispone di un fallback legacy a tre attributi per byte di certificato sintetico non X.509. Le strategie di produzione forniscono sempre DER X.509 reale, pertanto l’insieme completo di attributi B-B è il percorso di produzione. Il fallback esiste unicamente per la storica superficie di test della meccanica DER.
• La struttura CMS deve rientrare nello spazio Contents riservato. Il SignedData B-B con una catena di certificati completa ha una dimensione; la sessione solleva un errore di overflow quando il CMS assemblato supera lo spazio esadecimale riservato. Dimensionare di conseguenza lo spazio riservato. Per il B-T la marca temporale RFC 3161 incorporata (dominata dalla catena di certificati della TSA) ingrandisce il CMS; lo spazio riservato per il B-T viene aumentato automaticamente, e uno spazio configurato sottodimensionato fallisce in modo fail-closed con un errore di configurazione tipizzato anziché troncare.
• MaskingConfig::fromArray scarta una voce priva di un pattern stringa utilizzabile anziché far fallire l’importazione. Validare la fonte di configurazione se uno scarto silenzioso è inaccettabile.
• La modalità black-box del mascheramento emette una sostituzione vuota per la sequenza corrispondente e rimuove il testo sottostante. Una regola che non corrisponde a un valore non lo maschera; il motore non asserisce che tutti i contenuti sensibili vengano trovati.
• Il B-T richiede un timestamp provider collegato. Sul percorso del provider RFC 3161 di Core predefinito il digest dell’imprint è SHA-256; un digest dell’imprint diverso da SHA-256 su quel percorso viene rifiutato con un errore di configurazione tipizzato anziché essere silenziosamente declassato, e un provider personalizzato fornito dal chiamante può legittimamente usare un altro digest approvato. Un serialNumber di marca temporale è univoco per token da una determinata Time-Stamping Authority, e genTime è l’istante UTC in cui il token è stato creato — RFC 3161 §2.4.1, §2.4.2. Il materiale di validazione a lungo termine B-LT/B-LTA rimane una questione di confine Enterprise; Pro non produce alcun DSS, alcun VRI e alcuna marca temporale di documento.
• L’OCSP unknown non equivale a good, e la freschezza dello stato è delimitata da thisUpdate e nextUpdate — RFC 6960 §2.2, §4.2.

Comportamento in modalità FIPS

Pro seleziona l’algoritmo dall’algoritmo di firma configurato e dalla strategia. Quando configurato contro un KMS o un HSM convalidato FIPS, l’operazione crittografica viene eseguita all’interno di quel confine convalidato, e l’insieme di algoritmi è quello che il confine consente. NextPDF Pro esegue l’assemblaggio strutturale del CMS e il calcolo del digest; non è esso stesso un modulo crittografico convalidato FIPS e non avanza alcuna pretesa di certificazione FIPS. Un deployment che richiede una postura FIPS deve configurare un KMS o un HSM convalidato FIPS, e il profilo di crypto-policy FIPS 140-3 è una capability Enterprise.

Postura di controllo delle esportazioni

Questo modulo riguarda funzionalità crittografiche; trattarlo come sensibile dal punto di vista della sicurezza nella propria revisione.

Confine Enterprise

NextPDF Pro produce la baseline B-B e il livello B-T. Per il B-B la sessione assembla un CMS SignedData con l’insieme di attributi firmati B-B e non applica alcuna marca temporale. Per il B-T aggiunge esattamente una signature-time-stamp RFC 3161 come attributo CMS non firmato calcolato sul valore della firma digitale per un firmatario — ETSI EN 319 122-1 §5.3. NextPDF Pro implementa ciò secondo ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 e RFC 5816, ed è verificato con fixture; non asserisce una certificazione, conformità o compliance ETSI EN 319 142-1 indipendente, e non asserisce la validità legale del documento.

I livelli B-LT e B-LTA sono capability Enterprise e non sono prodotti da Pro. Il B-LT e il B-LTA aggiungono un Document Security Store e marche temporali di documento per la validazione di archiviazione a lungo termine — ETSI EN 319 142-2 §5.5. Un signature handler che produce quei livelli supporta voci DSS e marche temporali di documento — ETSI EN 319 142-2 §6.3.3.3. Il RemoteSigningConfig di Pro può trasportare un livello superiore al B-T (B-LT o B-LTA) che richiede un Document Security Store, ma Pro non distribuisce quel produttore e non vi agisce; un tale livello è un valore dichiarato in anticipo. Il flusso di firma di Core risolve il produttore a lungo termine in fase di esecuzione tramite il contratto di Core, e quel produttore è distribuito nel pacchetto nextpdf/enterprise. In un deployment solo-Pro, una richiesta di B-LT o B-LTA fallisce in modo fail-closed con un messaggio che nomina il componente Enterprise mancante. Pro non produce alcun DSS, alcun dizionario VRI, alcuna marca temporale di documento e alcun ciclo di archiviazione, e non avanza alcuna pretesa di validazione a lungo termine (LTV). Anche la custodia delle chiavi su hardware tramite PKCS#11 e il profilo di crypto-policy FIPS 140-3 sono capability Enterprise. Questa pagina non documenta l’implementazione Enterprise della validazione a lungo termine; ne dichiara solo il confine e il nome pubblico del pacchetto.

Livello PAdES	Aggiunge	Edizione produttrice
B-B	Firma CMS con attributi firmati	Core, Pro
B-T	Una marca temporale di firma RFC 3161 come attributo non firmato sul valore della firma	Core, Pro
B-LT	Document Security Store con materiale di validazione	Enterprise (nextpdf/enterprise)
B-LTA	Marche temporali di documento per la validità di archiviazione	Enterprise (nextpdf/enterprise)

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie dell’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.

Fallback di Core

Un deployment privo dell’entitlement Pro conserva il contratto di firma di Core. Il codice che dipende dal contratto Core SignerInterface continua a firmare con il signer CMS software al livello baseline B-B. Il mascheramento, il rilevamento dei dati sensibili e le strategie di firma remota e con KMS cloud non sono presenti senza il pacchetto Pro, e una chiamata a quei tipi è un errore di dipendenza grave, non un no-op silenzioso.

Residenza dei dati e mitigazioni PII

Le superfici di mascheramento e PII vengono eseguite in-process. Nessun contenuto del documento lascia l’host per il mascheramento o il rilevamento dei dati sensibili. Una strategia con KMS cloud invia al provider il digest degli attributi firmati, non il documento, per l’operazione di firma. Il rilevamento dei dati sensibili è basato su pattern sui tipi configurati e rimuove gli oggetti di testo sottostanti per la modalità black-box, come verificato dai test. Non è una garanzia di rimozione completa dei dati personali e non è una dichiarazione di conformità normativa.

Telemetria sicura e scrubbing dei log

La libreria solleva eccezioni tipizzate con messaggi strutturali. Non scrive contenuti del documento o valori PII rilevati nei messaggi delle eccezioni o nei log. Un deployment che effettua logging attorno al percorso di firma dovrebbe registrare campi strutturali, non byte del documento.

Conformità

Asserzione	Standard	Clausola
La firma CMS è archiviata codificata in DER nella voce Contents del dizionario di firma.	ISO 32000-2	§12.8.1
Il processo di calcolo del message digest; gli attributi firmati trasportano content-type e message-digest.	RFC 5652	§5.4
Il verificatore non deve fare affidamento sui digest calcolati dall’originatore; li ricalcola e li confronta in modo indipendente (processo di verifica della firma).	RFC 5652	§5.6
Il SignerInfo trasporta l’identificatore dell’algoritmo di digest e il blocco degli attributi firmati.	RFC 5652	§5
Una richiesta di marca temporale restituisce una struttura TSTInfo.	RFC 3161	§2.4.1
Un serialNumber di marca temporale è univoco per token da una determinata TSA.	RFC 3161	§2.4.2
Il genTime della marca temporale è l’istante UTC in cui il token è stato creato.	RFC 3161	§2.4.2
Una signature-time-stamp PAdES B-T è un attributo non firmato che trasporta una marca temporale calcolata sul valore della firma digitale per un firmatario (Pro produce il B-T).	ETSI EN 319 122-1	§5.3
L’imprint della signature-time-stamp è l’hash del valore del campo di firma del SignerInfo escludendo il tag e la lunghezza ASN.1.	ETSI EN 319 122-1	§5.3
La marca temporale della signature-time-stamp usa l’OID id-aa-timeStampToken; il suo MessageImprint è un hash del valore del campo di firma del SignerInfo.	RFC 3161	Appendix A
Sul lato di verifica, NextPDF vincola il MessageImprint di una signature-time-stamp al valore della firma del SignerInfo e fallisce in modo fail-closed in caso di mancata corrispondenza, token mancante/duplicato o imprint SHA-1 (verifica strict, non una certificazione).	RFC 3161	Appendix A
ESSCertIDv2 sostituisce il legacy ESSCertID vincolato a SHA-1; il percorso B-T strict richiede ESSCertIDv2.	RFC 5816	§1
La validazione del percorso di certificazione verifica i basic constraint e gli input del percorso verso un trust anchor.	RFC 5280	§6.1
L’OCSP riporta certStatus come good, revoked o unknown.	RFC 6960	§2.2
La freschezza dello stato OCSP è delimitata da thisUpdate e nextUpdate.	RFC 6960	§4.2
Il B-LT e il B-LTA aggiungono un Document Security Store e marche temporali di documento per la validazione a lungo termine (confine Enterprise).	ETSI EN 319 142-2	§5.5
Un signature handler che produce livelli a lungo termine supporta voci DSS e marche temporali di documento (confine Enterprise).	ETSI EN 319 142-2	§6.3.3.3

Tutte le clausole sono parafrasate. NextPDF non riproduce il testo normativo. Consultare gli standard pubblicati per la formulazione autorevole. NextPDF Pro implementa il supporto alla firma PAdES B-T secondo ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 e RFC 5816, ed è verificato con fixture. ETSI EN 319 142-1 (la parte sui livelli baseline PAdES) è al di fuori dell’insieme di evidenze citato; NextPDF Pro pertanto non asserisce una certificazione, conformità o compliance ETSI EN 319 142-1 indipendente, e non asserisce la validità legale del documento. Questa pagina dichiara la struttura prodotta, gli standard che il supporto B-T implementa e il confine Enterprise B-LT/B-LTA, non un livello di conformità certificato.

Vedere anche

• Core signing — il signer CMS, il timestamp RFC 3161, la validazione del percorso RFC 5280, OCSP e CRL.
• Mappatura baseline PAdES — B-B, B-T, B-LT, B-LTA tra le edizioni.
• Security (panoramica della capability) — la pagina pubblica della capability di sicurezza di Pro.
• CMS · PAdES · RFC 3161 timestamp · KMS · DSS — voci di glossario.