如何用LibPDF对PDF电子签名：PKCS12证书快速上手教程

LibPDF是一款面向 TypeScript 的现代 PDF 库，只需几行代码加一个PKCS#12（.p12/.pfx）证书文件，即可完成符合 PAdES 国际标准的PDF 电子签名——具备身份认证、完整性保护与不可抵赖三大法律效力。本教程带你从零走完完整流程：安装库、加载证书、签名文档、附加时间戳，10 分钟内上手。

为什么用 LibPDF 做 PDF 电子签名 🖋️

LibPDF 的数字签名模块遵循PAdES（PDF 高级电子签名）标准，通过pdf.sign()一个方法即可产出可在 Adobe Reader 等主流阅读器中验证的签名文档。签名强度由 PAdES 等级决定：

第一步：安装 LibPDF 并准备 P12 证书

使用任意包管理器安装（要求 Node.js 18+，仅支持 ESM）：

npm install @libpdf/core

P12 文件是什么？它把三样东西打包在一起：

• 你的签名证书
• 签名所用的私钥（受密码保护）
• 可选的中间证书

大多数 CA（证书颁发机构）都会提供 .p12 或 .pfx 格式的证书文件，向 CA 购买数字证书时即可获得。

第二步：用 PKCS#12 证书 3 步签署 PDF

核心代码只有 3 步：加载文档 → 创建签名器 → 调用sign()：

import { PDF, P12Signer } from "@libpdf/core"; import { readFile, writeFile } from "fs/promises"; // 1. 加载要签署的文档 const pdf = await PDF.load(await readFile("document.pdf")); // 2. 用 .p12 文件 + 证书密码创建签名器 const signer = await P12Signer.create(await readFile("certificate.p12"), "证书密码"); // 3. 签署文档（可附签署原因、地点等元信息） const signed = await pdf.sign({ signer, reason: "I approve this document", location: "New York, NY", contactInfo: "signer@example.com", }); await writeFile("signed.pdf", signed.bytes);

💡P12Signer的完整实现位于 p12.ts，支持 RSA 与 EC（椭圆曲线）密钥，可选buildChain: true自动通过 AIA 扩展补齐证书链。

第三步：添加时间戳，让签名具备时间证明 🕐

基本签名（B-B）中的时间只是签名者本机时钟的"声明"。要让时间具备密码学证明，接入一个时间戳权威机构（TSA）即可升级到 B-T 等级：

import { HttpTimestampAuthority } from "@libpdf/core"; const tsa = new HttpTimestampAuthority("http://timestamp.digicert.com"); const signed = await pdf.sign({ signer, level: "B-T", timestampAuthority: tsa, });

常用免费时间戳服务器：

生产环境建议使用与你证书同一家 CA 提供的时间戳服务。若需证书过期后仍可验证，把level改为B-LT，LibPDF 会自动嵌入证书链、CRL 与 OCSP 响应等全部验证数据。

签名字段：复用已有字段或自动创建 📝

• 文档里已有空白签名字段时，用fieldName指定即可填入；
• 指定的字段不存在时，LibPDF 会自动创建；
• 不指定fieldName时，自动寻找第一个空字段，否则创建Signature_N。

await pdf.sign({ signer, fieldName: "ApprovalSignature", // 存在则复用，不存在则创建 });

多人签署的工作流也很简单：每次签署都用增量保存，后一个签名不会破坏前一个：

const firstSigned = await pdf.sign({ signer: signer1 }); const pdf2 = await PDF.load(firstSigned.bytes); const fullySigned = await pdf2.sign({ signer: signer2 });

可直接运行的示例与源码路径

想跑起来看效果？仓库examples/07-signatures/目录提供了全套官方示例（用npx tsx直接运行）：

• P12 基础签名：sign-with-p12.ts
• 带时间戳签名（B-T）：sign-with-timestamp.ts
• 仅创建空白签名字段：add-signature-field.ts
• 多人连续签署：multiple-signatures.ts
• B-LTA 归档级签名：sign-archival.ts

更多源码与资料：

• 测试用证书文件（密码test123）：test-signer-aes256.p12
• 官方签名完整指南（含 KMS、排错表）：signatures/index.mdx
• 签名器类型定义（SignOptions 全参数）：signatures/types.ts
• 项目特性总览：README.md

常见问题与排错速查表 ⚠️

安全最佳实践清单 ✅

1. 守护私钥：绝不外传 .p12 文件或暴露密码；
2. 使用受信证书：自签名证书会在阅读器中产生信任警告；
3. 包含时间戳：B-T 及以上等级对法律效力更友好；
4. 坚持增量保存：多签名场景下保护所有历史签名；
5. 签后必验证：用 Adobe Reader 打开确认签名面板与证书详情无误。

📌 小提示：LibPDF 专注于签名能力，签名验证由 PDF 阅读器完成；B-LT/B-LTA 等级需要网络访问 OCSP/CRL 服务器，离线环境请提前规划。

掌握以上步骤，你就已经可以安全地为合同、发票等关键文档签署具有法律效力的 PDF 电子签名了。