Certificate Transparency — 深入參考

一覽

本頁是 NextPDF Enterprise 中 Certificate Transparency（CT）介面的深入參考。這個介面就是一個不可變的值物件：NextPDF\Enterprise\Security\CertificateTransparency\CtValidationResult。它彙整一張 X.509 簽章憑證的 Signed Certificate Timestamp（SCT）狀態。它帶有 SCT 擴充旗標、SCT 的總數與有效數，以及發行紀錄的識別碼。它公開一個政策方法 meetsPolicy()，也就是一個最小 SCT 門檻檢查。這個型別代表的是一個結果；它不擷取 SCT、不驗證 SCT 簽章，也不與 CT 紀錄連線。工作流程層級的指南請見 簽章憑證的 Certificate Transparency 政策。

供應與授權

這項能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 級授權封套啟用。沒有該授權的部署不會載入這項能力的類別。比較各版本並取得授權。

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
CtValidationResult	—	彙整一張憑證 SCT 狀態的不可變值物件	—	不拋出	final readonly；四個由建構子提升的屬性皆為 public
CtValidationResult::__construct	bool $hasSctsExtension、int $totalScts、int $validScts、array<string> $logIds	依樣儲存所提供的值，不做驗證或協調	新的 CtValidationResult 實例	未宣告 @throws；在 strict_types 下，引數型別不符時 PHP 拋出 TypeError	提升的 public readonly 屬性
CtValidationResult::meetsPolicy	int $minimumScts = 2	將有效 SCT 數與門檻比較：validScts >= $minimumScts	bool	不拋出	只計算有效的 SCT；它不檢查紀錄的相異性或擴充是否存在

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

公開 readonly 屬性

屬性	型別	意義
$hasSctsExtension	bool	憑證是否含有 SCT 擴充
$totalScts	int	擴充中所發現的 SCT 總數
$validScts	int	具有有效簽章的 SCT 數量，由上游判定
$logIds	array<string>	發行這些 SCT 的 CT 紀錄的識別碼（SHA-256 雜湊值）

行為合約

• CtValidationResult 是一個結果值。它代表呼叫端環境所執行的 SCT 擷取與驗證的結果。它不解析憑證、不驗證 SCT 簽章、不查詢紀錄，也不將憑證提交到紀錄。
• 這裡所指的擴充是內嵌 SCT 的 X.509v3 憑證擴充，以 OID 1.3.6.1.4.1.11129.2.4.2 標識——RFC 6962 §3.3。一個 SCT 帶有一個版本、一個紀錄識別碼、一個時間戳、擴充，以及紀錄對該項目的簽章——RFC 6962 §3.2。
• $logIds 中的每一個項目都是 RFC 6962 §3.2 所定義的紀錄識別碼：紀錄公鑰針對其 DER 編碼的 SubjectPublicKeyInfo 所計算的 SHA-256 雜湊值。這個型別依樣儲存字串，不重新計算或驗證它們。
• meetsPolicy() 只實作一個比較：有效 SCT 數大於或等於門檻。預設門檻是 2。
• meetsPolicy() 不參照 $hasSctsExtension。若某項政策必須在擴充缺失時失敗，則要在門檻檢查之前或並行地另外針對該屬性設閘。
• meetsPolicy() 不對 $logIds 去重。若某項政策要求 SCT 來自互相獨立的紀錄，則要透過 $logIds 本身檢查相異性。
• 建構子逐字儲存輸入。它不做範圍檢查，也不做跨欄位一致性檢查。
• 實例是不可變的（final readonly）。所有讀取與門檻檢查皆為確定性且無副作用。
• 門檻值是營運者的政策選擇；NextPDF 不強加任何數字。套件原始碼註記了一個生態系參考點：截至 2024 年，Chrome 的 CT 政策對於效期不超過 180 天的憑證，預期至少要有來自不同紀錄的兩個 SCT，效期更長的憑證則要三個。那是瀏覽器方案的政策，不是 IETF 的要求。
• 預期的放置位置是一個簽章前的閘門：當檢查失敗時，簽章工作流程拒絕建構簽章器。其理據依循 CT 信任模型：SCT 是紀錄將該憑證納入的承諾，而依賴方會拒絕缺乏有效 SCT 的憑證——RFC 6962 §3。CT 2.0 版沿用相同模型：接受提交的紀錄會回傳一個 SCT，提交者在依賴它之前先加以驗證——RFC 9162 §3。

邊界情況與失敗模式

• 零或負門檻。 meetsPolicy(0) 對任何非負的 $validScts 都回傳 true。這個方法不會拒絕該值。請選擇至少為 1 的門檻。
• 擴充缺失、計數為正。 當 $hasSctsExtension 為 false 但 $validScts 達到門檻時，meetsPolicy() 仍回傳 true。若缺失時必須失敗，閘門就要明確檢查 $hasSctsExtension；能力頁展示了這個模式。
• 重複的紀錄識別碼。 來自單一紀錄的 N 個有效 SCT 就能滿足 N 的門檻。門檻檢查不做任何獨立性的主張。紀錄相異性政策要檢視 $logIds。
• 不一致的計數。 $validScts 大於 $totalScts，或計數為負，都會依樣儲存。不會拋出例外。上游的擷取步驟負責輸入的一致性。
• 未驗證的紀錄識別碼字串。 這個型別不對 $logIds 項目強制 32 位元組或十六進位的形態。畸形的識別碼會原封不動地通過。
• 無例外路徑。 在有效的 PHP 型別下，這個介面上的任何方法都不拋出。政策檢查的失敗模式是拒絕（false），而非例外。與任何具型別的 PHP API 一樣，在 strict_types 下引數型別不符會引發 PHP TypeError。

FIPS 模式行為

CtValidationResult 不執行任何密碼計算。它不計算摘要，也不驗證簽章。某個 SCT 簽章是否算作有效，是由上游在建構結果之前執行驗證的元件所決定。因此，隨安全模組記載的 Enterprise FIPS 140-3 密碼政策設定檔，並不改變這個型別的行為。

符合性

主張	標準	條款
SCT 是紀錄將該憑證納入的承諾；依賴方會拒絕缺乏有效 SCT 的憑證。	RFC 6962	§3
一個 SCT 帶有一個版本、一個紀錄識別碼、一個時間戳、擴充，以及紀錄對該項目的簽章。	RFC 6962	§3.2
紀錄識別碼是紀錄公鑰針對其 DER 編碼的 SubjectPublicKeyInfo 所計算的 SHA-256 雜湊值。	RFC 6962	§3.2
內嵌的 SCT 搭載於以 OID 1.3.6.1.4.1.11129.2.4.2 標識的 X.509v3 憑證擴充。	RFC 6962	§3.3
在 CT 2.0 版，接受提交的紀錄會回傳一個 SCT，提交者在依賴它之前先加以驗證。	RFC 9162	§3

所有條款皆為改寫；NextPDF 不重製規範性文字。NextPDF 不做任何 Certificate Transparency 符合性或認證主張。 NextPDF Enterprise 不是 CT 紀錄、稽核者或監控者。它不將憑證提交到紀錄，也不斷言任何 CT 驗證結果。這個型別代表的是呼叫端環境所產生的計數與識別碼，並評估一個由呼叫端選擇的門檻。瀏覽器 CT 方案（例如 Chrome 的）是生態系政策，而非 IETF 規範性的要求；選擇並滿足這類政策是營運者的責任。

開發注意事項

• 這個值物件沒有相依項，也沒有 I/O。在單元測試中直接建構實例。
• 建議的邊界測試：有效計數恰好等於門檻、比門檻少一、擴充缺失但計數達門檻，以及重複的紀錄識別碼對上相異性政策。
• 這個類別宣告於 strict_types=1，具有型別化的提升屬性。錯誤的引數型別會在呼叫端引發 PHP TypeError。
• 這個類別帶有套件的 @since 註記 1.0.0，並在其原始碼文件中引用 RFC 6962 與 RFC 9162。
• $logIds 參數記載為 array<string>；靜態分析將該屬性視為字串陣列。建構結果時請保留這個形態。
• 將你的上游 CT 驗證與這個門檻閘置於簽章器建構之前，讓一張紀錄不足的憑證永遠不會抵達簽章操作。能力頁記載了工作流程與一個完整的閘門範例。

另請參閱

• 簽章憑證的 Certificate Transparency 政策 — 能力頁：工作流程、設定，以及一個完整的政策閘門。
• Security — NextPDF Enterprise — 整合的 Enterprise 安全介面。
• Signature — 深入參考 — PAdES B-LT 與 B-LTA 長效產生器。
• Security / Signing（Core） — Core CMS 簽章器與簽章策略合約。
• Certificate Transparency · SCT — 詞彙表條目。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名，以及工單前綴皆不在範圍內。