Sicurezza e operatività di NextPDF con Symfony

In breve

Gli helper di risposta applicano un set fisso di intestazioni di sicurezza. Il DTO del messaggio asincrono convalida due volte il proprio percorso di output. La firma è facoltativa e, con il tier Pro, resta limitata al profilo baseline documentato qui.

Intestazioni di sicurezza della risposta HTTP

NextPDF\Symfony\Http\PdfResponse applica lo stesso set di intestazioni a ogni risposta generata (inline, download ed entrambe le varianti in streaming). Le intestazioni esatte, verificate rispetto alla costante sorgente, sono:

Intestazione	Valore
Cache-Control	private, max-age=0, must-revalidate
Pragma	public
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Content-Security-Policy	default-src 'none'
X-Robots-Tag	noindex, nofollow
Referrer-Policy	no-referrer

Queste intestazioni riducono lo sniffing del content-type, il framing, l’indicizzazione e l’esposizione del referrer dei documenti generati. Le varianti con buffer impostano inoltre Content-Type: application/pdf e Content-Length. Le varianti in streaming impostano il content type ma omettono Content-Length per scelta progettuale.

Il set di intestazioni è definito dal bundle. Per aggiungere o modificare intestazioni (ad esempio un Cache-Control più rigoroso per i download autenticati), intervenire sulla Response restituita dal controller prima di restituirla.

Content-Disposition e gestione del nome file

PdfResponse costruisce l’intestazione Content-Disposition in modo difensivo, come verificato da PdfResponseTest:

• Il nome file viene sanificato; i separatori di percorso e le sequenze di traversal vengono rimossi (un nome file come ../../../etc/passwd.pdf non può uscire dal confine previsto).
• Un’estensione .pdf viene aggiunta quando assente; un’estensione già presente non viene duplicata, inclusa un’estensione .PDF in maiuscolo.
• Le virgolette doppie e i backslash vengono sottoposti a escape nella forma quoted-string.
• Per i nomi file non ASCII viene generato un fallback ASCII e una variante RFC-5987 filename*=UTF-8''.
• Un nome file vuoto ricade su document.pdf.

Passare un nome file influenzato dall’utente solo dopo avere eseguito il controllo di autorizzazione a livello applicativo; il bundle sanifica ai fini della sicurezza delle intestazioni, non del controllo degli accessi.

Convalida asincrona del percorso di output

NextPDF\Symfony\Message\GeneratePdfMessage convalida il percorso di output nel costruttore e NextPDF\Symfony\Message\GeneratePdfHandler lo riconvalida in fase di esecuzione prima della scrittura. Regole di rifiuto verificate alla costruzione:

• un percorso vuoto o contenente un byte null;
• uno schema di stream-wrapper come php://...;
• un segmento di traversal .. che usa separatori / oppure \;
• un percorso che non termina con .pdf (senza distinzione tra maiuscole e minuscole);
• un builderClass che non sia un nome di classe sintatticamente valido.

La seconda convalida nell’handler è importante perché un messaggio può restare in una coda tra l’invio e il consumo. L’handler non si fida del percorso accodato e riapplica il guard del percorso prima di salvare. Eseguire i worker con un account a privilegi minimi sul filesystem, limitato alla directory di output prevista.

Confine di risoluzione dei builder

GeneratePdfHandler risolve i builder da un service locator PSR-11 indicizzato per nome di classe e rifiuta tutto ciò che non è un PdfBuilderInterface. Poiché il locator espone solo i builder registrati, un builderClass controllato da un attaccante all’interno di un payload di trasporto manomesso non può istanziare una classe arbitraria. In base a PSR-11, quando un container segnala un id come assente, la risoluzione fallisce anziché restituire silenziosamente qualcosa di inatteso (PSR-11 §1.1.2). Registrare nel locator solo classi builder attendibili.

Configurazione facoltativa della firma digitale

La firma digitale non fa parte del bundle core. Si attiva solo quando nextpdf/premium (che installa il tier Pro) è presente e il compiler pass rileva le classi di firma Pro. Quando il bundle e il tier Pro sono installati, la configurazione di firma supportata e documentata è il profilo baseline B-B.

Il nodo di configurazione signature.level accetta valori stringa aggiuntivi per la compatibilità dello schema all’interno della famiglia di configurazioni NextPDF. La capacità di firma fornita e supportata da questo bundle è B-B. I profili di firma oltre B-B, i loro requisiti e le relative considerazioni operative sono documentati nella documentazione NextPDF Premium e non vengono intenzionalmente descritti qui.

Note operative relative al percorso di firma B-B:

• Il signer viene registrato solo quando signature.enabled vale true e signature.certificate è impostato; altrimenti la sezione è inerte.
• Fornire il certificato, la chiave privata e la password tramite Symfony secrets o variabili d’ambiente, senza mai eseguirne il commit nel repository.
• Limitare i permessi di lettura sul materiale della chiave all’account dell’applicazione.

Logging facoltativo

I registry dei font e delle immagini accettano un Psr\Log\LoggerInterface facoltativo associato tramite nullOnInvalid(). Quando è presente, è un collaboratore sostituibile secondo il contratto del logger PSR-3 (PSR-3). Rimuovere i dati identificativi dell’utente da qualsiasi contesto di log aggiunto attorno alla generazione dei documenti; il bundle non registra nel log il contenuto dei documenti.

Checklist di rafforzamento operativo

• Mantenere fisse le intestazioni di risposta; aggiungere un caching più rigoroso per i download autenticati a livello di controller.
• Autorizzare la richiesta prima di generare o restituire un documento; il bundle non esegue il controllo degli accessi.
• Conservare il materiale della chiave di firma in Symfony secrets / variabili d’ambiente con permessi sui file a privilegi minimi.
• Eseguire i worker Messenger con un account a privilegi minimi, con accesso in scrittura limitato alla directory di output.
• Mantenere abilitate ext-mbstring e ext-zlib (in caso contrario il bundle fallisce immediatamente).
• Bloccare una singola major nextpdf/core nell’applicazione per rendere deterministica la versione del motore tra i diversi deploy.

Conformità

Ogni riga è un’affermazione normativa formulata in questa pagina, ancorata a un reference_id completo a 64 cifre esadecimali dal corpus SDO gated. La provenienza (manifest del corpus, trasporto di retrieval) si trova in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Affermazione
PSR-11	psr_11_container#1.1.2.p5		has() false implica che get() lanci NotFoundException
PSR-3	psr_3_logger#x3.p17		Collaboratore logger facoltativo

Contesto commerciale

La firma digitale è disponibile solo quando nextpdf/premium (Pro) è installato; il profilo fornito da questo bundle è baseline B-B. È una capacità Pro facoltativa; il bundle Core documentato qui non richiede alcuna modifica al codice per adottarla. Vedere </get-license/?intent=symfony-pro>.

Vedere anche

• /integrations/symfony/production-usage/ — sicurezza dei worker e dello streaming.
• /integrations/symfony/configuration/ — le tabelle signature, tsa e service.
• /integrations/symfony/troubleshooting/ — diagnosi dei problemi di firma e Messenger.
• /integrations/symfony/integration/ — riferimento per il cablaggio end-to-end.