Enterprise edizione

Certificate Transparency — Riferimento approfondito

In sintesi

Questa pagina è il riferimento approfondito per la superficie Certificate Transparency (CT) in NextPDF Enterprise. La superficie è un unico oggetto valore immutabile: NextPDF\Enterprise\Security\CertificateTransparency\CtValidationResult. Riassume la postura Signed Certificate Timestamp (SCT) di un certificato di firma X.509. Trasporta il flag dell’estensione SCT, i conteggi totali e validi degli SCT e gli identificatori dei log emittenti. Espone un unico metodo di politica, meetsPolicy(), che è un controllo della soglia minima di SCT. Il tipo rappresenta un risultato; non estrae gli SCT, non verifica le firme degli SCT e non contatta i log CT. Per la guida a livello di flusso di lavoro, vedere Politica Certificate Transparency per i certificati di firma.

Disponibilità e licenza

Questa funzionalità è 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 funzionalità. Confronta le edizioni e ottieni una licenza.

Superficie dell’API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`CtValidationResult`	—	Oggetto valore immutabile che riassume la postura SCT di un certificato	—	Non solleva eccezioni	`final readonly`; tutte e quattro le proprietà promosse dal costruttore sono pubbliche
`CtValidationResult::__construct`	`bool $hasSctsExtension`, `int $totalScts`, `int $validScts`, `array<string> $logIds`	Memorizza i valori forniti così come sono, senza validazione né riconciliazione	Nuova istanza di `CtValidationResult`	Nessun `@throws` dichiarato; PHP solleva `TypeError` in caso di tipi di argomento non corrispondenti sotto `strict_types`	Proprietà `readonly` pubbliche promosse
`CtValidationResult::meetsPolicy`	`int $minimumScts = 2`	Confronta il conteggio degli SCT validi con la soglia: `validScts >= $minimumScts`	`bool`	Non solleva eccezioni	Conta solo gli SCT validi; non controlla la distinzione dei log né la presenza dell’estensione

final readonly class CtValidationResult

public function __construct(
    public bool $hasSctsExtension,
    public int $totalScts,
    public int $validScts,
    public array $logIds,
) {}

public function meetsPolicy(int $minimumScts = 2): bool

Proprietà pubbliche readonly

Proprietà	Tipo	Significato
`$hasSctsExtension`	`bool`	Se il certificato contiene l’estensione SCT
`$totalScts`	`int`	Numero totale di SCT trovati nell’estensione
`$validScts`	`int`	Numero di SCT con firme valide, come determinato a monte
`$logIds`	`array<string>`	Identificatori dei log (hash SHA-256) dei log CT che hanno emesso gli SCT

Contratto comportamentale

CtValidationResult è un valore di risultato. Rappresenta l’esito dell’estrazione e della verifica degli SCT che l’ambiente del chiamante ha eseguito. Non analizza i certificati, non verifica le firme degli SCT, non interroga i log e non invia certificati ai log.
L’estensione in questione è l’estensione di certificato X.509v3 con SCT incorporati, identificata dall’OID 1.3.6.1.4.1.11129.2.4.2 — RFC 6962 §3.3. Un SCT trasporta una versione, un identificatore di log, un timestamp, delle estensioni e la firma del log sulla voce — RFC 6962 §3.2.
Ogni voce in $logIds è un identificatore di log come definito da RFC 6962 §3.2: l’hash SHA-256 della chiave pubblica del log sul suo SubjectPublicKeyInfo codificato in DER. Il tipo memorizza le stringhe così come fornite e non le ricalcola né le valida.
meetsPolicy() implementa esattamente un confronto: il conteggio degli SCT validi è maggiore o uguale alla soglia. La soglia predefinita è 2.
meetsPolicy() non consulta $hasSctsExtension. Una politica che deve fallire in caso di estensione mancante controlla la proprietà separatamente, prima del controllo di soglia o insieme a esso.
meetsPolicy() non deduplica $logIds. Una politica che richiede SCT da log indipendenti controlla la distinzione tramite $logIds stesso.
Il costruttore memorizza gli input verbatim. Non esegue controlli di intervallo né controlli di coerenza tra campi.
Le istanze sono immutabili (final readonly). Tutte le letture e il controllo di soglia sono deterministici e privi di effetti collaterali.
Il valore di soglia è la scelta di politica dell’operatore; NextPDF non impone alcun numero. Il codice sorgente del pacchetto annota un punto di riferimento dell’ecosistema: la politica CT di Chrome, al 2024, si aspetta almeno due SCT da log diversi per i certificati con durata fino a 180 giorni, e tre per i certificati a vita più lunga. Si tratta di una politica di programma di browser, non di un requisito IETF.
Il posizionamento previsto è un gate pre-firma: un flusso di lavoro di firma rifiuta di costruire un firmatario quando il controllo fallisce. La motivazione segue il modello di fiducia CT: un SCT è la promessa del log di incorporare il certificato, e le relying party rifiutano un certificato privo di un SCT valido — RFC 6962 §3. La versione CT 2.0 mantiene lo stesso modello: un log che accetta un invio restituisce un SCT, che l’inviante valida prima di farvi affidamento — RFC 9162 §3.

Casi limite e modalità di guasto

Soglia zero o negativa. meetsPolicy(0) restituisce true per qualsiasi $validScts non negativo. Il metodo non rifiuta il valore. Scegliere una soglia di almeno 1.
Estensione assente, conteggi positivi. Quando $hasSctsExtension è false ma $validScts soddisfa la soglia, meetsPolicy() restituisce comunque true. Il gate deve controllare esplicitamente $hasSctsExtension quando l’assenza deve fallire; la pagina della funzionalità mostra questo pattern.
Identificatori di log duplicati. N SCT validi da un singolo log soddisfano una soglia di N. Il controllo di soglia non fa alcuna affermazione di indipendenza. Le politiche di distinzione dei log ispezionano $logIds.
Conteggi incoerenti. Un $validScts maggiore di $totalScts, o un conteggio negativo, viene memorizzato così come fornito. Nessuna eccezione viene sollevata. Il passo di estrazione a monte è responsabile della coerenza degli input.
Stringhe di identificatore di log non validate. Il tipo non impone una forma di 32 byte o esadecimale sulle voci di $logIds. Gli identificatori malformati passano invariati.
Nessun percorso di eccezione. Nessun metodo di questa superficie solleva eccezioni sotto tipi PHP validi. La modalità di guasto del controllo di politica è il rifiuto (false), non un’eccezione. Tipi di argomento non corrispondenti sollevano un TypeError PHP sotto strict_types, come per qualsiasi API PHP tipizzata.

Comportamento in modalità FIPS

CtValidationResult non esegue alcun calcolo crittografico. Non calcola alcun digest e non verifica alcuna firma. Se la firma di un SCT sia stata conteggiata come valida viene deciso a monte, dal componente che ha eseguito la verifica prima di costruire il risultato. Il profilo di crypto-policy FIPS 140-3 di Enterprise, documentato con il modulo di sicurezza, non altera pertanto il comportamento di questo tipo.

Conformità

Affermazione	Standard	Clausola
Un SCT è la promessa del log di incorporare il certificato; le relying party rifiutano un certificato privo di un SCT valido.	RFC 6962	§3
Un SCT trasporta una versione, un identificatore di log, un timestamp, delle estensioni e la firma del log sulla voce.	RFC 6962	§3.2
L’identificatore di log è l’hash SHA-256 della chiave pubblica del log sul suo `SubjectPublicKeyInfo` codificato in DER.	RFC 6962	§3.2
Gli SCT incorporati viaggiano in un’estensione di certificato X.509v3 identificata dall’OID `1.3.6.1.4.1.11129.2.4.2`.	RFC 6962	§3.3
Nella versione CT 2.0, un log che accetta un invio restituisce un SCT, che l’inviante valida prima di farvi affidamento.	RFC 9162	§3

Tutte le clausole sono parafrasate; NextPDF non riproduce testo normativo. NextPDF non avanza alcuna affermazione di conformità o certificazione Certificate Transparency. NextPDF Enterprise non è un log CT, un auditor o un monitor. Non invia certificati ai log e non asserisce un esito di verifica CT. Il tipo rappresenta conteggi e identificatori prodotti dall’ambiente del chiamante e valuta una soglia scelta dal chiamante. I programmi CT dei browser, come quello di Chrome, sono politiche di ecosistema piuttosto che requisiti normativi IETF; selezionare e soddisfare una tale politica è responsabilità dell’operatore.

Note di sviluppo

L’oggetto valore non ha dipendenze né I/O. Costruire le istanze direttamente negli unit test.
Test di confine consigliati: conteggio valido esattamente alla soglia, uno sotto la soglia, estensione assente con conteggi alla soglia e identificatori di log duplicati contro una politica di distinzione.
La classe è dichiarata sotto strict_types=1 con proprietà promosse tipizzate. Tipi di argomento errati sollevano un TypeError PHP nel chiamante.
La classe reca un’annotazione @since di pacchetto pari a 1.0.0 e fa riferimento a RFC 6962 e RFC 9162 nella propria documentazione sorgente.
Il parametro $logIds è documentato come array<string>; l’analisi statica tratta la proprietà come un array di stringhe. Preservare questa forma quando si costruiscono i risultati.
Collocare la verifica CT a monte e questo gate di soglia prima della costruzione del firmatario, in modo che un certificato sotto-loggato non raggiunga mai un’operazione di firma. La pagina della funzionalità documenta il flusso di lavoro e un esempio di gate elaborato.

Vedere anche

Politica Certificate Transparency per i certificati di firma — la pagina della funzionalità: flusso di lavoro, configurazione e un gate di politica elaborato.
Sicurezza — NextPDF Enterprise — la superficie di sicurezza Enterprise combinata.
Firma — Riferimento approfondito — il produttore PAdES B-LT e B-LTA a lungo termine.
Sicurezza / Firma (Core) — il firmatario CMS Core e il contratto di strategia di firma.
Certificate Transparency · SCT — termini del glossario.

Confine di pubblicazione

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