Flutter Guides Timestamps and ltv

时间戳与长期验证

ComPDF Flutter SDK 自 3.2.0 起支持签名时间戳及长期验证（LTV）材料管理。签名时间戳由时间戳机构（TSA）提供；LTV 材料包括证书链与 OCSP、CRL 等吊销信息。

import 'package:compdfkit_flutter/compdfkit.dart';

为签名添加时间戳

在 CPDFDigitalSignatureConfig 中指定 timestampServerUrl，然后按创建数字签名签署。将下例地址替换为应用实际使用的 TSA 地址。

final config = CPDFDigitalSignatureConfig(
  certificatePath: certificatePath,
  password: certificatePassword,
  timestampServerUrl: 'https://tsa.example.com/timestamp',
);
final success = await document.writeSignature(
  signatureWidget,
  '/path/to/signed_timestamp.pdf',
  config,
);

签署需要网络连接；TSA 无法访问或拒绝请求时，接口不会降级为不带时间戳的签署。优先使用 HTTPS。iOS 使用 HTTP TSA 时，宿主应用需配置相应的网络访问策略。

通过 verifyDigitalSignature() 的 timestampSource、embeddedTimestampValid、timestampTrusted 分别读取来源、内嵌时间戳有效性和机构信任状态。可空结果不应按验证成功处理。

区分时间来源

CPDFSignatureTimestampSource 表示签名时间信息的来源：

值	说明
none	没有签署时间信息
localClock	时间来自签署方本地时钟
embedded	签名包含内嵌 RFC 3161 时间戳
document	当前签名本身为文档时间戳

本地时钟记录不能作为 TSA 时间戳使用。来源为 embedded 时，仍需结合 embeddedTimestampValid 与 timestampTrusted 分别判断时间戳有效性和机构信任状态。

检查长期验证材料

final readiness = await document.getLtvReadiness();
print(readiness.ltvReady);
print(readiness.missingMaterials);

此操作检查文档 DSS/VRI 中的证书和吊销材料，不需要网络。success 表示检查是否完成，ltvReady 表示材料准备状态。该结果不能单独证明证书可信或每个签名均满足 PAdES-LT。

补充 LTV 材料

打开已保存的签名 PDF，提供包含信任根证书的 PEM 文件，并为输出副本指定不同于源文件的路径。

final result = await document.addSignatureLtv(
  '/path/to/signed_ltv.pdf',
  const CPDFSignatureLtvOptions(
    trustedCertificatePath: '/path/to/trusted-root.pem',
  ),
);
if (result.success) {
  await document.open(result.finalPath);
} else {
  for (final issue in result.errors) {
    print('${issue.code}: ${issue.message}');
  }
}

SDK 从已保存文件读取签名，验证证书链，并通过网络收集 OCSP/CRL 材料。需要指定响应服务时，使用 ocspUrls、crlUrls。当前打开文档不会被自动替换或重新加载。

追加文档时间戳

在补充 LTV 材料后，可继续生成带文档时间戳的副本：

final result = await document.addSignatureLtv(
  '/path/to/signed_ltv.pdf',
  const CPDFSignatureLtvOptions(
    trustedCertificatePath: '/path/to/trusted-root.pem',
    appendDocumentTimestamp: true,
    timestampServerUrl: 'https://tsa.example.com/timestamp',
    timestampOutputPath: '/path/to/signed_lta.pdf',
  ),
);
if (result.success) {
  await document.open(result.finalPath);
}

源文件、LTV 输出和时间戳输出使用不同路径。ltvPath 指向补充验证材料的文件，ltaPath 指向追加文档时间戳的文件；finalPath 优先返回后者。

应用应检查 success、errors 和 warnings。证书链不可信或网络不可达等失败通过结果返回；参数无效或文档不可用还可能抛出异常，不能仅根据输出文件是否存在判断成功。