Configurazione della TSA

In breve

NextPDF contatta una Time Stamp Authority (TSA) solo quando si firma a livello PAdES B-T o superiore. A B-B non c’è alcuna marca temporale né alcuna chiamata di rete, perciò questa pagina non si applica a una firma B-B.

Per far funzionare B-T senza configurazione, NextPDF include una TSA predefinita integrata. Tale valore predefinito è una comodità: consente a una firma con marca temporale di riuscire senza configurazione aggiuntiva. Non è pubblicamente attendibile e non è qualificato eIDAS, quindi non è appropriato per l’uso in produzione o per la conformità senza una scelta deliberata. Questa pagina spiega esattamente che cos’è il valore predefinito, come puntare NextPDF alla propria TSA, come disattivare la marcatura temporale e i due percorsi di upgrade.

Tre proprietà sono indipendenti e non vanno confuse:

self-hosted — chi gestisce il server e a quale radice il relativo certificato si concatena;
pubblicamente attendibile — se l’ecosistema di convalida usato dalle parti facenti affidamento (il loro archivio di attendibilità o elenco di attendibilità) considera già attendibile quella radice senza configurazione manuale, anziché richiedere l’installazione manuale di una radice privata. Questo riguarda gli anchor di attendibilità della parte facente affidamento, non un singolo programma come la Web PKI;
qualificato eIDAS — se la marca temporale porta un effetto giuridico qualificato nell’UE.

Il valore predefinito incluso è solo self-hosted. Una TSA pubblicamente attendibile aggiunge la seconda proprietà. Una TSA qualificata eIDAS porta inoltre uno stato giuridico qualificato, convalidato attraverso gli Elenchi di fiducia dell’UE, e può essere gestita da un QTSP di terze parti. Le tre proprietà sono indipendenti — una non implica l’altra.

La TSA predefinita integrata

L’endpoint predefinito è https://timestamp.pateon.com.tw, il server di marcatura temporale RFC 3161 di NextPDF stesso. È self-hosted: il certificato della relativa unità di marcatura temporale si concatena a una radice PATEON privata, non a un programma di attendibilità pubblico. Una parte facente affidamento non può quindi convalidare una marca temporale emessa dal valore predefinito a meno che non abbia installato e considerato attendibile quella radice PATEON fuori banda.

Poiché un token RFC 3161 non porta alcuna prova esterna che l’istante asserito sia corretto, l’attendibilità di una qualsiasi marca temporale di questo tipo si fonda interamente sull’attendibilità della TSA emittente (ISO/IEC 18014-2 §7.3). Per il valore predefinito incluso, tale anchor di attendibilità è privato, ed è per questo che il valore predefinito è un valore di comodità e sviluppo, non un valore di livello di conformità.

Quando l’endpoint predefinito è in uso e il framework ha un logger configurato, NextPDF emette un avviso una tantum all’avvio del processo, segnalando che il valore predefinito non è pubblicamente attendibile e rimandando a questa configurazione. L’avviso è informativo; la firma riesce comunque.

Override del valore predefinito

Imposta l’endpoint della TSA nella configurazione dell’adattatore del framework. La chiave esatta differisce per adattatore (vedi la tabella per framework): in Laravel è la variabile d’ambiente NEXTPDF_TSA_URL, in Symfony il nodo del bundle nextpdf.tsa.url e in CodeIgniter la chiave d’ambiente nextPdf.tsa.url.

La TSA effettiva viene risolta con questa precedenza, dalla più alta:

Un TsaClient esplicito che costruisci e inietti tu stesso — questo vince sempre.
L’URL configurato nell’adattatore — usato quando non inietti un client.
Il valore predefinito integrato — usato solo quando nessuno dei precedenti è impostato.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Disabilitazione della marca temporale

Lasciare l’url della TSA dell’adattatore al suo valore predefinito (non configurato) mantiene l’endpoint predefinito integrato. Impostare quell’url su un valore vuoto è diverso: disabilita la marcatura temporale. Senza alcuna TSA configurata, una firma richiesta a livello B-T o superiore fallisce in modo fail-closed con un errore “TSA required” anziché ripiegare silenziosamente su B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Scelta dell’algoritmo di digest del messageImprint

Una richiesta di marca temporale RFC 3161 trasporta un messageImprint — un hash dei dati di cui si crea la marca temporale — e NextPDF usa per impostazione predefinita SHA-256 per tale imprint. Il valore predefinito è una scelta deliberata e interoperabile; raramente è necessario cambiarlo.

Quando costruisci un TsaClient a mano puoi selezionare un digest dell’imprint diverso tramite il parametro del costruttore imprintHashAlgorithm, che accetta un case di TsaImprintHashAlgorithm: Sha256 (il predefinito), Sha384, Sha512, Sha3_256, Sha3_384 o Sha3_512. Il valore predefinito mantiene ogni richiesta emessa byte-identica alle release precedenti, perciò l’aggiornamento non cambia nulla a meno che tu non aderisca esplicitamente.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Prima di abbandonare il valore predefinito vale la pena conoscere due vincoli:

Il supporto dell’ecosistema è oggi SHA-256. Un imprint diverso da SHA-256 interopera con il verificatore di token di Core, ma il gate di prova PAdES B-T di nextpdf-server e la mappa dei digest di convalida di Premium riconoscono al momento solo gli imprint SHA-256. Una marca temporale di firma costruita con un digest dell’imprint diverso non dimostrerà quindi ancora B-T su tali superfici. Mantieni il valore predefinito a meno che ogni consumatore delle tue marche temporali sia noto per accettare il digest che scegli.
I digest pre-calcolati devono corrispondere all’algoritmo. getDocumentTimestamp() accetta un hash del documento già calcolato; fallisce in modo fail-closed, prima di qualsiasi chiamata di rete, quando la lunghezza di tale hash non corrisponde all’algoritmo dell’imprint configurato, anziché inviare una richiesta non corrispondente.

Percorsi di upgrade

Per qualsiasi cosa che vada oltre lo sviluppo o l’uso interno, sostituisci il valore predefinito con una delle due opzioni più robuste.

TSA pubblicamente attendibile

Punta l’url della TSA dell’adattatore verso una TSA il cui certificato si concatena a una radice pubblica che le tue parti facenti affidamento considerano già attendibile — per esempio http://timestamp.digicert.com. Non è necessario distribuire alcuna radice privata. Una TSA di livello di produzione di norma dichiara la conformità a una politica di marcatura temporale come ETSI EN 319 421 §5 e segue il profilo di protocollo RFC 3161 descritto in ETSI EN 319 422 §7; verificalo rispetto alla politica pubblicata dell’operatore anziché presumerlo dalla sola attendibilità pubblica.

TSA qualificata eIDAS

Per marche temporali che devono portare un effetto giuridico qualificato nell’Unione europea, usa un servizio di marcatura temporale qualificato di un prestatore di servizi fiduciari qualificato (QTSP) presente in un Elenco di fiducia dell’UE. Una marca temporale elettronica qualificata collega l’istante ai dati in modo da prevenire ragionevolmente un’alterazione non rilevabile, si basa su una fonte oraria accurata collegata al Tempo coordinato universale ed è protetta da una firma elettronica avanzata o da un sigillo elettronico avanzato del QTSP, o da un metodo equivalente (Regulation (EU) 910/2014, Art 42). Questa è l’opzione più robusta e quella da scegliere quando una normativa nomina esplicitamente le marche temporali qualificate.

Configurazione per framework

Il valore predefinito risiede nella configurazione di ciascun adattatore del framework, non nel motore core. Core non inventa mai un URL: un TsaClient che costruisci a mano richiede un endpoint esplicito e solleva un’eccezione se è vuoto. I livelli a lungo termine (B-LT e B-LTA) riutilizzano la stessa TSA configurata di B-T.

Integrazione	Dove risiede il valore predefinito	Come fare l’override
Laravel	`config/nextpdf.php` -> `tsa.url`	imposta `NEXTPDF_TSA_URL` nel `.env`
Symfony	config del bundle `nextpdf.tsa.url`	imposta il nodo, oppure associalo a una variabile d’ambiente
CodeIgniter	`Config\NextPdf::$tsa['url']`	esegui l’override tramite la chiave d’ambiente `nextPdf.tsa.url`
Plain core	nessun valore predefinito implicito	costruisci un `TsaClient` con un URL esplicito + un client PSR-18 irrobustito

In ogni adattatore, B-B non costruisce mai un client TSA, perciò una firma senza marca temporale non è influenzata da nessuna di queste configurazioni.

Modello di attendibilità e standard

Il valore di una marca temporale è la catena di attendibilità che vi sta dietro, non i byte stessi. Il token RFC 3161 asserisce solo un istante; se quell’asserzione sia credibile è una proprietà della TSA che l’ha firmata (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Quando mantieni il valore predefinito incluso stai scegliendo un anchor di attendibilità self-hosted, a fiducia privata — adatto allo sviluppo e ai flussi di lavoro interni in cui ogni parte facente affidamento può installare la radice PATEON, ma non per documenti convalidati da terze parti. Per questi, passa a una TSA pubblicamente attendibile, oppure a una TSA qualificata eIDAS quando è richiesto un effetto giuridico qualificato.

Se gestisci tu stesso il valore predefinito, puoi fissare (pin) la chiave pubblica della TSA nel tuo client PSR-18 iniettato. Non fissare il valore predefinito incluso in codice condiviso: una rotazione della chiave dal lato dell’operatore interromperebbe allora tutti gli utenti del valore predefinito in una sola volta. L’attendibilità di una marca temporale è la catena di certificati e la radice PATEON, non un pin di trasporto.