跳转到内容
NextPDF
getnextpdf.com

TSA 配置

概览

标题为“概览”的章节

只有当你在 PAdES B-T 或更高等级签章时，NextPDF 才会联系时间戳记机构 （TSA）。在 B-B 下既没有时间戳记，也没有网络调用，因此本页不适用于 B-B 签章。

为了让 B-T 开箱即用，NextPDF 随附了一个内置默认 TSA。该默认值是一项便利设施：它让带时间戳记的签章无需任何额外配置即可成功完成。它并非公开受信任，也并非 eIDAS 合格，因此在没有做出审慎选择之前，并不适合用于生产或合规用途。本页将准确说明该默认值究竟是什么、如何把 NextPDF 指向你自己的 TSA、 如何关闭时间戳记，以及那两条升级路径。

以下三项属性彼此独立，绝不能混为一谈：

  • 自托管——由谁运营该服务器，以及其证书链向哪个根；
  • 公开受信任——你的验证端所使用的验证生态（它们的信任库或信任清单）是否无需任何手动配置便已信任该根，而不是需要手动安装一个私有根。这关乎的是验证端的信任锚点，而非某一个特定程序（例如 Web PKI）；
  • eIDAS 合格——该时间戳记是否在欧盟具有合格法律效力。

随附的默认值仅是自托管的。公开受信任的 TSA 增加了第二项属性。eIDAS 合格的 TSA 还额外具备合格法律地位，并经由欧盟信任清单验证，且可由第三方 QTSP 运营。 这三项属性彼此独立——其中一项并不意味着另一项。

内置默认 TSA

标题为“内置默认 TSA”的章节

默认端点是 https://timestamp.pateon.com.tw，即 NextPDF 自有的 RFC 3161 时间戳记服务器。它是自托管的：其时间戳记单元证书链向一个私有 PATEON 根， 而非某个公共信任程序。因此，除非验证端已在带外安装并信任了该 PATEON 根，否则它无法验证由该默认值签发的时间戳记。

由于 RFC 3161 令牌并不携带任何外部证据来证明所断言的时间是正确的，对任何此类时间戳记的信任完全取决于对签发 TSA 的信任（ISO/IEC 18014-2 §7.3）。对于随附的默认值，该信任锚点是私有的，这正是为什么该默认值是一个便利与开发默认值，而非合规级别的默认值。

当正在使用默认端点且你的框架已配置了日志记录器时，NextPDF 会在进程启动时发出一条一次性警告，指出该默认值并非公开受信任，并指向本配置说明。该警告仅作信息提示之用；签章仍会成功。

覆盖默认值

标题为“覆盖默认值”的章节

在你的框架适配器配置中设置 TSA 端点。具体的键因适配器而异（参见 各框架配置表）：在 Laravel 中是 NEXTPDF_TSA_URL 环境变量，在 Symfony 中是 nextpdf.tsa.url bundle 节点， 而在 CodeIgniter 中是 nextPdf.tsa.url env 键。

实际生效的 TSA 按以下优先级解析，最高者在前：

  1. 由你自行构造并注入的显式 TsaClient——它始终胜出。
  2. 在你的适配器中配置的 URL——在你未注入客户端时采用。
  3. 内置默认值——仅在以上两者都未设置时采用。
Terminal window
# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

停用时间戳记

标题为“停用时间戳记”的章节

将适配器的 TSA url 保留为其默认状态（未配置）会沿用内置的默认端点。把该 url 设置为一个空值则是另一回事：它会停用时间戳记。在没有配置任何 TSA 的情况下，在 B-T 或更高等级请求的签章会以 fail closed（失败即关闭）的方式失败，并报出一条 “TSA required”（需要 TSA）的错误，而不会静默降级到 B-B。

Terminal window
# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

选择 messageImprint 摘要算法

标题为“选择 messageImprint 摘要算法”的章节

一个 RFC 3161 时间戳记请求会携带一个 messageImprint——即被加时间戳记的数据的一个哈希——而 NextPDF 默认对该 imprint 使用 SHA-256。这个默认值是一个审慎的、可互操作的选择；你很少需要更改它。

当你手动构造一个 TsaClient 时，你可以通过 imprintHashAlgorithm 构造函数参数选择一个不同的 imprint 摘要，该参数接受一个 TsaImprintHashAlgorithm 枚举成员： Sha256（默认值）、Sha384、Sha512、Sha3_256、Sha3_384 或 Sha3_512。该默认值使每个发出的请求都与早前的版本保持字节完全一致，因此除非你主动选择启用， 否则升级不会改变任何内容。

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;


// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');


// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

在偏离默认值之前，有两项约束值得了解：

  • 目前生态系统仅支持 SHA-256。 非 SHA-256 的 imprint 能与 Core 令牌验证器互操作，但 nextpdf-server 的 PAdES B-T 证明关卡以及 Premium 验证摘要映射目前仅识别 SHA-256 的 imprint。因此，用不同 imprint 摘要构建的签章时间戳记，暂时还无法在那些环节上证明 B-T。除非你确知你的时间戳记的每一个消费方都接受你所选择的摘要，否则请沿用默认值。
  • 预先计算的摘要必须与算法匹配。 getDocumentTimestamp() 接受一个已经计算好的文档哈希；当该哈希的长度与所配置的 imprint 算法不匹配时，它会在任何网络调用之前以 fail closed（失败即关闭）的方式失败，而不会发送一个不匹配的请求。

升级路径

标题为“升级路径”的章节

对于开发或内部用途以外的任何情形，请用以下两个更强选项之一替换默认值。

公开受信任的 TSA

标题为“公开受信任的 TSA”的章节

把适配器的 TSA url 指向一个其证书链向你的验证端已经信任的公共根的 TSA——例如 http://timestamp.digicert.com。无需分发任何私有根。生产级别的 TSA 通常会声明其符合某个时间戳记策略（例如 ETSI EN 319 421 §5），并遵循 ETSI EN 319 422 §7 中描述的 RFC 3161 协议配置文件；请对照运营方公布的策略来确认这一点，而不要仅凭公共信任就假定其如此。

eIDAS 合格的 TSA

标题为“eIDAS 合格的 TSA”的章节

对于必须在欧盟具有合格法律效力的时间戳记，请使用某个合格信任服务提供方 （QTSP）所提供、并列入欧盟信任清单的合格时间戳记服务。一份合格电子时间戳记会将时间绑定到数据，以合理防止无法察觉的篡改，且基于一个与协调世界时（UTC）关联的精确时间源，并由该 QTSP 的高级电子签名或高级电子印章，或由一种等效方法加以保护（Regulation (EU) 910/2014, Art 42）。这是最强的选项，也是在某项法规明确指名合格时间戳记时应选择的选项。

各框架配置

标题为“各框架配置”的章节

默认值位于每个框架适配器的配置之中，而非核心引擎之中。Core 绝不会凭空生成 URL：由你手动构建的 TsaClient 需要一个显式端点，若端点为空则会抛出异常。长期等级（B-LT 与 B-LTA）会复用与 B-T 相同的已配置 TSA。

集成方式默认值所在位置如何覆盖
Laravelconfig/nextpdf.php -> tsa.url在 .env 中设置 NEXTPDF_TSA_URL
Symfonybundle 配置 nextpdf.tsa.url设置该节点，或将其绑定到一个 env 变量
CodeIgniterConfig\NextPdf::$tsa['url']通过 nextPdf.tsa.url env 键覆盖
Plain core没有隐式默认值用一个显式 URL 加一个经过加固的 PSR-18 客户端构造一个 TsaClient

在每个适配器中，B-B 绝不会构建 TSA 客户端，因此一份未加时间戳记的签章不会受到上述任何配置的影响。

信任模型与标准

标题为“信任模型与标准”的章节

一个时间戳记的价值在于其背后的信任链，而不在于字节本身。RFC 3161 令牌只断言一个时间；该断言是否可信，是签发它的那个 TSA 的属性（RFC 3161 §2； ISO/IEC 18014-2 §7.3）。当你沿用随附的默认值时，你所选择的是一个自托管的、私有信任的锚点——对于每个验证端都能安装 PATEON 根的开发与内部工作流而言尚可，但不适用于由第三方验证的文档。对于那些情形，请改用公开受信任的 TSA，或在需要合格法律效力时改用 eIDAS 合格的 TSA。

如果你自行运营该默认值，可以在你自己注入的 PSR-18 客户端中固定（pin）该 TSA 的公钥。请勿在共享代码中固定随附的默认值：运营方一侧的一次密钥轮换将会同时让每一位默认用户都中断。时间戳记的信任在于证书链以及 PATEON 根，而不在于一个传输层的固定。

另请参阅

标题为“另请参阅”的章节