Enterprise edizione

Ancoraggio di fiducia ASiC

In sintesi

Un contenitore ASiC raggruppa i file firmati con le firme che li proteggono. La domanda difficile non è «la firma è calcolabile?» ma «chi risponde del firmatario?». NextPDF\Enterprise\Security\Asic\AsicTrustBinder risponde esattamente a questa domanda. Gli si passano il certificato di firma estratto dalla firma del contenitore, una lista di fiducia e un tempo di validazione. Risponde con un AsicTrustBindingResult: un verdetto trusted/untrusted, la versione del bundle di àncore rispetto a cui ha deciso e motivi leggibili dalla macchina. Ogni rifiuto ne dichiara la causa, così l’evidenza di audit si scrive da sé.

Un confine è deliberato e vale la pena dichiararlo subito. Questa API non analizza i contenitori ASiC. I tuoi strumenti aprono il contenitore ed estraggono il certificato di firma; NextPDF possiede la decisione di fiducia.

Disponibilità e licenza

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

Installazione

composer require nextpdf/enterprise

L’attivazione richiede il tuo envelope di licenza Enterprise. Vedere Installazione e autenticazione. Le classi di questa pagina risiedono sotto NextPDF\Enterprise\Security\Asic e NextPDF\Enterprise\Security\Tsl.

Panoramica concettuale

ASiC (Associated Signature Containers, ETSI EN 319 162-1) impacchetta file di dati e firme in un unico archivio. Un contenitore ASiC baseline incorpora solo firme baseline CAdES o XAdES. Una firma baseline CAdES porta il proprio certificato di firma dentro SignedData.certificates, quindi ci si aspetta che un verificatore lo estragga quando la firma è ben formata e supportata dagli strumenti del contenitore dalla firma del contenitore. Quel certificato estratto è l’input di questa API.

La sorgente di fiducia è una lista di fiducia ETSI TS 119 612 (TSL): un documento XML firmato che enumera i prestatori di servizi fiduciari e i loro certificati di servizio. NextPDF\Enterprise\Security\Tsl\TslTrustAnchorProvider converte un TslDocument analizzato in un bundle di àncore. Solo i servizi che sono sia in stato granted sia di tipo di servizio CA/QC alimentano l’insieme di àncore. Il bundle porta una stringa di versione derivata dal numero di sequenza della TSL e dal territorio, più un digest di integrità SHA-256.

Due gate fail-closed vengono eseguiti prima di qualunque confronto tra àncore:

Freschezza della TSL. Una lista di fiducia il cui istante NextUpdate è trascorso deve essere scartata come scaduta. AsicTrustBinder::verify() verifica la freschezza al tempo di validazione fornito prima di derivare una singola àncora. Una lista obsoleta, o un valore NextUpdate privo di un designatore UTC esplicito, solleva TslParseException.
Periodo di validità del firmatario. La validazione del percorso RFC 5280 richiede che il periodo di validità del certificato includa il tempo di validazione. Una firma crittograficamente integra il cui certificato era scaduto, o non ancora valido, in quel momento viene rifiutata con un codice motivazionale preciso.

Solo allora il binder confronta il certificato di firma con ciascuna àncora. Una corrispondenza produce trusted: true con motivo anchor_signature_match. Nessuna corrispondenza produce trusted: false con motivo no_anchor_chain.

Perché funziona così

La decisione di progettazione portante è una separazione netta tra la meccanica del contenitore e la decisione di fiducia, con la decisione di fiducia obbligata a essere esplicita riguardo al tempo. I formati dei contenitori variano (ASiC-S, ASiC-E, payload CAdES o XAdES), ma la domanda di fiducia è un unico nucleo invariante: questo certificato risale a un’àncora di una lista di fiducia fresca in un istante dichiarato? Mantenere quel nucleo libero dall’analisi di ZIP e XML lo tiene abbastanza piccolo da poter essere testato esaustivamente e da poter fallire in modo chiuso a ogni gate. Lo stesso ragionamento vieta un default now silenzioso: il tempo di validazione cambia il verdetto, quindi deve possederlo il chiamante. La freschezza viene verificata dentro il percorso di derivazione delle àncore stesso, non in un collaboratore opzionale, così nessun percorso produttore può saltarla.

Contesto di progettazione: Come una firma digitale prova chi ha firmato.

Superficie dell’API

`AsicTrustBinder`

La costruzione richiede il provider di àncore che trasforma le liste di fiducia in bundle di àncore.

public function __construct(
    private readonly TslTrustAnchorProvider $anchorProvider,
) {}

Il punto di ingresso principale verifica un certificato di firmatario rispetto a una lista di fiducia:

public function verify(
    string $signerCertPem,
    TslDocument $tsl,
    DateTimeInterface $validationTime,
): AsicTrustBindingResult

$signerCertPem — stringa PEM non vuota: il certificato di firma dalla firma ASiC.
$tsl — la lista di fiducia analizzata e autenticata.
$validationTime — l’istante che il periodo di validità del certificato del firmatario deve includere. Non esiste alcun default.

Solleva o fallisce con: NextPDF\Enterprise\Security\Tsl\TslParseException quando la TSL è obsoleta (NextUpdate trascorso), quando NextUpdate non è un valore UTC canonico, o quando la lista non contiene servizi CA/QC attivi. I firmatari non affidabili non sollevano eccezioni; restituiscono un risultato con trusted: false e un codice motivazionale.

Per carichi batch, verifica rispetto a un bundle pre-costruito:

public function verifyAgainstBundle(
    string $signerCertPem,
    EnterpriseCaTrustAnchorBundle $bundle,
    DateTimeInterface $validationTime,
): AsicTrustBindingResult

Solleva o fallisce con: nessuna eccezione propria; ogni esito è un AsicTrustBindingResult. Ottieni il bundle da TslTrustAnchorProvider::buildBundle() — non costruirlo a mano.

`TslTrustAnchorProvider`

public function buildBundle(TslDocument $tsl, DateTimeImmutable $now): EnterpriseCaTrustAnchorBundle

Solleva o fallisce con: TslParseException se la TSL è obsoleta, il suo NextUpdate non è un valore UTC canonico, o non ha servizi CA/QC attivi.

`AsicTrustBindingResult`

public function __construct(
    public bool $trusted,
    public string $anchorBundleVersion,
    public array $reasons,
) {}

$reasons è una list<non-empty-string> di codici leggibili dalla macchina. $anchorBundleVersion registra l’insieme di àncore utilizzato, nella forma tsl-<territory>-seq<N> (per esempio tsl-eu-seq42).

Codice motivazionale	Significato
`anchor_signature_match`	Il certificato di firma verifica rispetto a un’àncora derivata da TSL. Trusted.
`no_anchor_chain`	Nessuna àncora del bundle verifica il certificato di firma. Untrusted.
`signer_cert_expired`	Il tempo di validazione cade dopo il `notAfter` del certificato. Untrusted.
`signer_cert_not_yet_valid`	Il tempo di validazione cade prima del `notBefore` del certificato. Untrusted.
`cannot_parse_signer_cert`	Il PEM fornito non si analizza come certificato X.509. Untrusted.

Esempio di codice — Avvio rapido

I tuoi strumenti di contenitore hanno già estratto il certificato di firma. Vincolalo a una lista di fiducia di uno Stato membro che hai recuperato e autenticato (vedere Liste di fiducia).

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Security\Asic\AsicTrustBinder;
use NextPDF\Enterprise\Security\Tsl\TslParseException;
use NextPDF\Enterprise\Security\Tsl\TslTrustAnchorProvider;
use NextPDF\Enterprise\Security\Tsl\TslXmlParser;

// Extracted by YOUR tooling from META-INF/signature.p7s or signatures.xml.
$signerCertPem = (string) file_get_contents(__DIR__ . '/asic-signer.pem');

// A trusted list you have already fetched and authenticated.
$tslXml = (string) file_get_contents(__DIR__ . '/member-state-tsl.xml');

$binder = new AsicTrustBinder(new TslTrustAnchorProvider());

try {
    $tsl = (new TslXmlParser())->parse($tslXml);

    $result = $binder->verify(
        signerCertPem: $signerCertPem,
        tsl: $tsl,
        validationTime: new DateTimeImmutable('2026-07-03T12:00:00Z'),
    );
} catch (TslParseException $e) {
    // Fail closed: stale TSL, malformed NextUpdate, or no active CA/QC services.
    fwrite(STDERR, 'Trusted list rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

echo $result->trusted ? "TRUSTED\n" : "NOT TRUSTED\n";
echo 'Anchors: ' . $result->anchorBundleVersion . "\n";
echo 'Reasons: ' . implode(', ', $result->reasons) . "\n";

Output atteso per un firmatario emesso da un servizio CA/QC elencato:

TRUSTED
Anchors: tsl-eu-seq42
Reasons: anchor_signature_match

Esempio di codice — Produzione

Deriva il bundle di àncore una volta per lista di fiducia, poi verifica molti firmatari di contenitori rispetto ad esso. Una singola TSL obsoleta o inutilizzabile fa fallire in modo chiuso l’intero batch; i problemi dei singoli firmatari emergono per contenitore.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Security\Asic\AsicTrustBinder;
use NextPDF\Enterprise\Security\Asic\AsicTrustBindingResult;
use NextPDF\Enterprise\Security\Tsl\TslDocument;
use NextPDF\Enterprise\Security\Tsl\TslParseException;
use NextPDF\Enterprise\Security\Tsl\TslTrustAnchorProvider;
use NextPDF\Enterprise\Security\Tsl\TslXmlParser;

/**
 * @param array<string, non-empty-string> $signerPemsByContainer PEM per container path.
 * @return array<string, AsicTrustBindingResult>
 * @throws TslParseException When no anchor set can be derived from the TSL.
 */
function bindBatch(
    TslDocument $tsl,
    array $signerPemsByContainer,
    DateTimeImmutable $validationTime,
): array {
    $provider = new TslTrustAnchorProvider();

    // Derive the anchor set ONCE; a throw here means the trusted list itself
    // is unusable at this validation time.
    $bundle = $provider->buildBundle($tsl, $validationTime);

    $binder = new AsicTrustBinder($provider);

    $results = [];
    foreach ($signerPemsByContainer as $container => $signerPem) {
        $results[$container] = $binder->verifyAgainstBundle(
            signerCertPem: $signerPem,
            bundle: $bundle,
            validationTime: $validationTime,
        );
    }

    return $results;
}

$tsl = (new TslXmlParser())->parse(
    (string) file_get_contents(__DIR__ . '/member-state-tsl.xml'),
);

$signerPems = [
    'invoice-2026-06.asice' => (string) file_get_contents(__DIR__ . '/signer-a.pem'),
    'tender-2019.asice'     => (string) file_get_contents(__DIR__ . '/signer-b.pem'),
];

try {
    $results = bindBatch(
        tsl: $tsl,
        signerPemsByContainer: $signerPems,
        validationTime: new DateTimeImmutable('now', new DateTimeZone('UTC')),
    );
} catch (TslParseException $e) {
    // Fail closed for the WHOLE batch: no trustworthy anchor set exists.
    fwrite(STDERR, 'Anchor derivation failed: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

foreach ($results as $container => $result) {
    printf(
        "%s => %s (%s; anchors %s)\n",
        $container,
        $result->trusted ? 'trusted' : 'rejected',
        implode(',', $result->reasons),
        $result->anchorBundleVersion,
    );
}

Output atteso quando un certificato di firmatario è scaduto:

invoice-2026-06.asice => trusted (anchor_signature_match; anchors tsl-eu-seq42)
tender-2019.asice => rejected (signer_cert_expired; anchors tsl-eu-seq42)

Casi limite e insidie

Il tempo di validazione è obbligatorio e decisivo. Non esiste un default now silenzioso. Una firma che verificava nel 2019 riporta signer_cert_expired quando la validi a un istante del 2026 successivo al notAfter. Per il materiale storico, passa il tempo che le tue evidenze supportano (per esempio un tempo di prova di esistenza), non l’orologio di parete.
Una TSL obsoleta solleva un’eccezione; non è un verdetto «untrusted». Una TslParseException da verify() o buildBundle() significa che la sorgente di fiducia è inutilizzabile. Trattala come un guasto operativo: aggiorna la lista, non registrarla come rifiuto di un firmatario.
Le àncore sono verificate come emittenti diretti. Ogni àncora viene provata come il certificato che ha firmato il certificato del firmatario. Le TSL degli Stati membri UE elencano i certificati di servizio CA/QC emittenti, quindi i certificati qualificati di entità finale tipicamente corrispondono direttamente. Un firmatario emesso da una CA intermedia che non è essa stessa un servizio CA/QC attivo elencato produce no_anchor_chain.
La derivazione delle àncore filtra in modo rigoroso. I servizi ritirati, o di qualunque tipo diverso da CA/QC, non diventano mai àncore. Una lista il cui insieme CA/QC attivo è vuoto solleva un’eccezione anziché produrre un bundle vuoto.
NextUpdate deve essere UTC canonico. Un valore privo di un designatore Z esplicito o di un offset numerico viene rifiutato fail-closed, mai reinterpretato nel fuso orario locale del server.
L’input malformato degrada in modo preciso. Un PEM che non si analizza restituisce cannot_parse_signer_cert; un certificato non ancora valido è distinto da uno scaduto.
Registra anchorBundleVersion. Nomina l’insieme esatto di àncore (tsl-<territory>-seq<N>) dietro ciascun verdetto, che è ciò che un auditor chiederà.

Note di sicurezza

Fail-closed per costruzione. La freschezza viene verificata prima che qualunque àncora sia derivata. Il gate di validità del firmatario viene eseguito prima di qualunque confronto tra àncore. Il materiale di fiducia inutilizzabile solleva un’eccezione; i firmatari dubbi vengono rifiutati con motivi. Nessun percorso degrada a un passaggio silenzioso.
L’ancoraggio di fiducia è un solo strato, non l’intera validazione. Questa API non verifica il valore della firma CAdES sul contenuto del contenitore, non controlla la revoca (nessuna ricerca CRL o OCSP) e non autentica il documento TSL stesso. Autentica prima la lista attraverso la pipeline delle liste di fiducia (vedere Liste di fiducia), verifica la firma crittograficamente con i tuoi strumenti di firma e aggiungi il controllo di revoca secondo la tua policy.
Scegli il tempo di validazione deliberatamente. Il verdetto è funzione del tempo che passi. Derivalo da evidenze affidabili (una marca temporale qualificata, un record d’archivio), non da un orologio influenzabile da un attaccante.
Gli output di evidenza sono deterministici. trusted, anchorBundleVersion e reasons sono valori stabili, leggibili dalla macchina, adatti a log di audit firmati.

Conformità

AsicTrustBinder supporta flussi di lavoro allineati a ETSI EN 319 162-1 (contenitori ASiC baseline), ETSI EN 319 122-1 (firme baseline CAdES) ed ETSI TS 119 612 (liste di fiducia), e applica il gate del periodo di validità RFC 5280 al tempo di validazione fornito.

Il supporto non è conformità, e la conformità non è certificazione. NextPDF implementa i controlli descritti in questa pagina; non è stato certificato rispetto a questi standard da alcun organismo, e l’uso di questa API di per sé non rende il tuo output «qualificato» o giuridicamente efficace ai sensi di eIDAS o di qualsiasi altro regime. NextPDF non detiene alcuna certificazione e non ne concede alcuna. Se un processo di validazione completo soddisfi un determinato requisito legale o di appalto è una determinazione che spetta ai tuoi valutatori.

Comportamento in modalità FIPS

L’ancoraggio di fiducia esegue i controlli di firma dei certificati X.509 in-process; non è instradato attraverso la guardia runtime della modalità FIPS Enterprise, e abilitare la modalità FIPS non ne modifica il comportamento. Non è un servizio crittografico validato FIPS, e non si rivendica alcuna certificazione FIPS 140. I deployment con obblighi FIPS dovrebbero delimitare questa API di conseguenza e consultare Policy crittografica FIPS 140-2/3.

Contratto di comportamento

verify() deriva le àncore solo da una TSL che è fresca al tempo di validazione fornito; una lista obsoleta o malformata solleva TslParseException prima che esista alcuna àncora.
Le àncore derivano esclusivamente da servizi TSL in stato granted con il tipo di servizio CA/QC; un insieme attivo vuoto solleva un’eccezione.
Il periodo di validità del certificato del firmatario deve includere il tempo di validazione; le violazioni restituiscono signer_cert_expired o signer_cert_not_yet_valid.
Ogni esito è un AsicTrustBindingResult che porta trusted, anchorBundleVersion e almeno un codice motivazionale; non esiste alcun verdetto privo di motivo.
I firmatari non affidabili vengono restituiti, mai sollevati come eccezione; il materiale di fiducia inutilizzabile viene sollevato come eccezione, mai restituito come verdetto.
L’analisi del contenitore non avviene mai dentro questa API; gli input sono il PEM estratto, la lista di fiducia e il tempo di validazione.

Ripiego su Core

NextPDF Core valida le firme PDF (CMS/PAdES) rispetto ad àncore di fiducia che appunti esplicitamente attraverso il suo contratto CaTrustAnchorBundle — vedere Sicurezza di Core. Core non ha ingestione di liste di fiducia (TSL) né ancoraggio di fiducia specifico per ASiC. Con Core da solo, puoi mantenere il tuo insieme di àncore per la validazione delle firme PDF; derivare le àncore da una lista di fiducia ETSI TS 119 612 e vincolare ad esse i firmatari dei contenitori ASiC richiede NextPDF Enterprise.

Confine di pubblicazione

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

Vedere anche

Liste di fiducia — recupera, autentica e analizza la TSL che alimenta il provider di àncore.
Verifica delle firme — la superficie di verifica Enterprise per le firme PDF.
Policy crittografica FIPS 140-2/3 — la postura della modalità FIPS Enterprise.
Come una firma digitale prova chi ha firmato — contesto dai primi principi.
Validazione a lungo termine — perché il tempo di validazione e le evidenze conservate contano.