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 面

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
CtValidationResult	—	汇总证书 SCT 状态的不可变值对象	—	不抛出异常	final readonly；全部四个构造器提升属性均为公共属性
CtValidationResult::__construct	bool $hasSctsExtension、int $totalScts、int $validScts、array<string> $logIds	按原样存储所提供的值，不做校验或调和	新的 CtValidationResult 实例	无声明的 @throws；在 strict_types 下参数类型不匹配时 PHP 抛出 TypeError	提升的公共 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 属性

Property	Type	Meaning
$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。

边缘情形与失败模式

• 零或负阈值。 对任何非负的 $validScts，meetsPolicy(0) 返回 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 加密策略配置文件不会改变此类型的行为。

合规性

Claim	Standard	Clause
一个 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。
• 该类带有 1.0.0 的包 @since 标注，并在其源码文档中引用 RFC 6962 与 RFC 9162。
• $logIds 参数被记录为 array<string>；静态分析将该属性视为字符串数组。构造结果时请保持这一形态。
• 请将你的上游 CT 验证与这道阈值关卡置于签名器构造之前，从而使一张记录不足的证书永不会到达签名操作。能力页记录了该工作流以及一个完整的关卡示例。

另请参阅

• 面向签名证书的 Certificate Transparency 策略 — 能力页：工作流、配置，以及一个完整的策略关卡。
• 安全 — NextPDF Enterprise — 合并的 Enterprise 安全能力面。
• 签名 — 深度参考 — PAdES B-LT 与 B-LTA 长期产出器。
• 安全 / 签名（Core） — Core CMS 签名器与签名策略契约。
• Certificate Transparency · SCT — 术语表条目。

发布边界

本页仅记录外部可观测的行为以及受支持的公共 API 面。内部命名空间路径、辅助类、机制表、运维手册文件名以及工单前缀均不在范围之内。