Evidenze

In sintesi

NextPDF Enterprise assembla i finding di convalida per ciascun documento in un pacchetto sigillato e immutabile con una forma JSON deterministica e un digest SHA-256 stabile, che trasporta facoltativamente un token di marca temporale RFC 3161. L’acquisizione delle evidenze supporta i flussi di lavoro di audit. Non è un’attestazione legale, una certificazione di audit né una prova che un documento sia conforme.

Disponibilità e licenze

Questa capacità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Un deployment privo di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

EvidencePortal è il punto di ingresso. generateEvidence($documentHash, $records, $tsaTimestamp) assembla un elenco di istanze EvidenceRecord in un EvidencePackage, calcola le statistiche di esito positivo/negativo, persiste il pacchetto tramite un EvidenceStoreInterface e restituisce il pacchetto sigillato. Un EvidenceRecord cattura un singolo controllo di policy: nome della policy, flag di esito positivo, dettagli, la versione del validatore che lo ha prodotto e una marca temporale.

EvidencePackage è immutabile una volta costruito. Trasporta un id di pacchetto, lo SHA-256 del documento convalidato, i record, i conteggi aggregati, un istante di generazione e un token di marca temporale RFC 3161 facoltativo. allPassed() e passRate() lo riassumono. La sua immutabilità rende un pacchetto idoneo all’archiviazione write-once-read-many (WORM).

EvidenceExporter serializza un pacchetto in una stringa JSON deterministica — ordine delle chiavi fisso, riproducibile — così che exportHash() restituisca un digest SHA-256 stabile di 64 caratteri per la verifica dell’integrità. Lo stesso pacchetto produce sempre lo stesso digest, indipendentemente da quando o dove viene calcolato.

ContinuousMonitor riconvalida un documento e confronta le evidenze correnti con le evidenze precedenti memorizzate in base al nome della policy fallita, categorizzando i problemi come nuovi, risolti o invariati, ed espone un controllo di pianificazione (isDue() / MonitorSchedule / MonitorFrequency). Ciò supporta il rilevamento della deriva nel tempo; riporta ciò che è cambiato, non asserisce alcuno stato legale in alcun momento.

Cosa significa qui «evidence»

Questo modulo impacchetta e marca temporalmente i finding di convalida per i flussi di lavoro di audit. Non certifica nulla.

• Un token di marca temporale RFC 3161 lega il dato del pacchetto a un valore temporale: fornisce evidenza che i dati esistevano prima di quell’istante. Non è un’attestazione legale e non asserisce che il contenuto marcato temporalmente sia conforme o valido.
• Un pacchetto sigillato con allPassed() === true registra che i controlli inclusi hanno avuto esito positivo rispetto alle regole che implementano. Non è una certificazione di audit.
• Il digest deterministico dimostra l’integrità dei byte del pacchetto. Non dimostra la sufficienza normativa del documento.

L’acquisizione delle evidenze supporta i flussi di lavoro di audit; non è un’attestazione legale né una certificazione di audit. La validità e la conformità restano proprietà del file finale insieme a un validatore.

Confine di livello

Il packaging delle evidenze è una superficie esclusiva di Enterprise. Core e Pro producono finding e report; Enterprise Evidence sigilla tali finding in un pacchetto immutabile, deterministico e, facoltativamente, con marca temporale, e traccia le regressioni. Dipende da finding prodotti altrove (le superfici Validation o Compliance); non esegue di per sé controlli di conformità.

Perché funziona così

Le evidenze sono utili solo se non possono essere riscritte silenziosamente in seguito, perciò EvidencePackage è un valore readonly sigillato senza mutatori — sicuro per l’archiviazione write-once-read-many. L’output toJson() dell’exporter segue un ordine di inserimento delle chiavi fisso, non un ordinamento in fase di esecuzione, così che lo stesso pacchetto si serializzi sempre in byte identici. Questa stabilità dei byte consente a un exportHash() memorizzato di verificare in seguito l’integrità: qualsiasi modifica al pacchetto cambia il digest. Il token RFC 3161 è mantenuto come evidenza incorporata del tempo, mai un verdetto, così che un pacchetto dimostri quando un controllo è stato eseguito senza asserire che il documento sia conforme. Il tracciamento delle regressioni confronta quindi in base al nome della policy fallita rispetto al pacchetto precedente, così che il rilevamento della deriva resti indipendente dall’ordinamento o dal conteggio dei controlli.

Contesto di progettazione: Conformità da consegnare a un auditor.

Superficie API

Classe	Responsabilità
EvidencePortal	Assemblare, persistere e recuperare i pacchetti di evidenze.
EvidencePackage	Insieme sigillato e immutabile di record con statistiche aggregate.
EvidenceRecord	Risultato di un singolo controllo di policy con versione del validatore e marca temporale.
EvidenceExporter	Serializzazione JSON deterministica; digest SHA-256 stabile.
EvidenceStoreInterface	Contratto di persistenza.
InMemoryEvidenceStore	Implementazione di riferimento dell’archivio in memoria.
ContinuousMonitor	Riconvalidare e confrontare con le evidenze precedenti.
MonitorResult	Categorizzazione dei problemi in nuovi / risolti / invariati.
MonitorSchedule / MonitorFrequency	Polling basato su pianificazione.

Esempio di codice — Avvio rapido

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

Esempio di codice — Produzione

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

Casi limite e insidie

• passRate() restituisce 0.0 quando non vi sono finding; un pacchetto vuoto non è un esito positivo.
• L’esportazione è deterministica solo tramite EvidenceExporter; calcolare l’hash di serializzazioni arbitrarie infrange la garanzia di digest stabile.
• Un pacchetto privo di un token TSA è comunque un’evidenza valida; il token aggiunge un legame temporale, non un verdetto.

Prestazioni

Il packaging e la serializzazione deterministica crescono linearmente con il numero di record. Il calcolo del digest è una singola passata SHA-256 sul JSON serializzato.

Note di sicurezza

Il digest del pacchetto fornisce la rilevabilità delle manomissioni per i byte del pacchetto. Il token RFC 3161 facoltativo deve provenire da una TSA attendibile; questo modulo incorpora il token, non garantisce per la TSA. Trattare i dettagli dei record come potenzialmente sensibili (vedere di seguito).

Residenza dei dati e mitigazioni dei dati personali (PII)

I record di evidenze e gli hash dei documenti possono fare riferimento a contenuto regolamentato. Il packaging è in-process; la persistenza è delegata alla propria implementazione di EvidenceStoreInterface, perciò la residenza segue il proprio archivio. Applicare controlli di conservazione e minimizzazione ai pacchetti memorizzati.

Telemetria sicura e sanificazione dei log

I metadati del pacchetto (id, digest, conteggi) sono sicuri da registrare. I dettagli dei record possono riportare messaggi di finding che contengono stringhe estratte dal documento; sanificarle prima di inoltrarle a sink condivisi.

Conformità

Comportamento	Riferimento	Stato
Il token di marca temporale lega un dato a un istante	IETF RFC 3161 §2	Token incorporato (fornito dalla TSA)
Contesto DSS / convalida a lungo termine	ISO 32000-2:2020 §12.8	Riferito (consumato, non prodotto qui)

Questa tabella registra le specifiche in base alle quali questo modulo è costruito. Un token di marca temporale è evidenza del tempo, non una certificazione né un’attestazione legale.

Comportamento in modalità FIPS

Questo modulo calcola SHA-256 sui byte del pacchetto e incorpora un token RFC 3161 fornito dal chiamante. Non esegue alcuna firma né alcuna custodia delle chiavi; le operazioni crittografiche e il comportamento in modalità FIPS sono gestiti dai moduli Security e Signature.

Modello di minaccia

Gli input sono finding e un token TSA facoltativo. Mitigazioni: pacchetti immutabili, serializzazione deterministica con un digest di integrità stabile e persistenza delegata, così che l’archivio imponga WORM e controllo degli accessi.

Contratto di comportamento

• Il portale assembla i finding in un pacchetto immutabile e sigillato con un id di pacchetto, lo SHA-256 del documento convalidato, i record, i conteggi aggregati, l’istante di generazione e un token di marca temporale RFC 3161 facoltativo.
• L’exporter serializza un pacchetto in una stringa JSON deterministica con un ordine delle chiavi fisso, così che il digest sia uno SHA-256 stabile di 64 caratteri, identico indipendentemente da quando o dove viene calcolato.
• Il monitor continuo riconvalida e confronta le evidenze correnti con le evidenze precedenti memorizzate in base al nome della policy fallita, categorizzando i problemi come nuovi, risolti o invariati.
• passRate() restituisce 0.0 quando non vi sono finding — un pacchetto vuoto non è un esito positivo; un pacchetto privo di un token TSA è comunque un’evidenza valida.
• Un token di marca temporale è evidenza che i dati esistevano prima di un istante; non è un’attestazione legale e non avanza alcuna affermazione sulla conformità o validità del contenuto.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Fallback di Core

Core e Pro producono finding e report; sigillare tali finding in un pacchetto immutabile, deterministico e, facoltativamente, con marca temporale, con tracciamento delle regressioni, non ha un equivalente a livello Core. La superficie Enterprise dipende da finding prodotti altrove; non esegue di per sé controlli di conformità.

Fallback di Pro

Fallback di Pro — nessuno; questa capacità non ha un equivalente a livello Pro. Il pacchetto di evidenze sigillato, l’exporter deterministico e il monitor continuo sono inclusi esclusivamente nel pacchetto nextpdf/enterprise; la superficie consuma i finding dalle superfici Validation o Compliance.

Nota sul confine Enterprise

Il portale, il pacchetto, l’exporter e il monitor sono descritti a livello di comportamento. L’archivio in memoria di riferimento è documentato; la persistenza durevole è fornita dall’host, ed eventuali dettagli interni dell’archivio sono fuori ambito per la superficie pubblica. Questo modulo incorpora un token TSA fornito dal chiamante; non garantisce per la TSA.

Confine di distribuzione

Il packaging e la serializzazione sono in-process. L’operatore fornisce un’implementazione durevole dell’archivio, è responsabile dell’applicazione WORM e del controllo degli accessi, e fornisce un token TSA da una TSA attendibile. I record di evidenze e gli hash dei documenti possono fare riferimento a contenuto regolamentato; la residenza segue l’archivio dell’operatore, e i controlli di conservazione e minimizzazione sono responsabilità dell’operatore.

Confine di conformità legale

L’acquisizione delle evidenze supporta i flussi di lavoro di audit; non è un’attestazione legale né una certificazione di audit, e la validità e la conformità restano proprietà del file finale insieme a un validatore. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.

Vedere anche

• Validation — produce i finding qui impacchettati.
• Compliance — risultati dei validatori esterni.
• AST audit trail — cronologia delle mutazioni in sola aggiunta.
• Specifiche: PAdES — contesto della convalida a lungo termine.
• Evidence — Deep Reference — riferimento API completo a livello di classe.