通过 C# 为 PDF 文档添加电子签名
电子签名在文档合规性与安全性保障中扮演着重要角色，基于 C# 开发 PDF 电子签名功能是企业级文档处理场景的常见需求。Free Spire.PDF for .NET 作为免费的 PDF 处理类库，无需依赖 Adobe Acrobat 等第三方软件，即可便捷实现 PDF 电子签名添加。本文将介绍该类库的使用方式、PDF 电子签名的实现流程、解析关键代码参数等。
一、前置准备
1. 安装免费库
通过 NuGet 包管理器快速安装：
Install-Package FreeSpire.PDF
2. 核心依赖说明
实现电子签名需依赖 .pfx 格式的数字证书（包含私钥）：
- 测试场景：可通过 OpenSSL、Windows 证书管理器生成自签名证书；
- 生产场景：需使用 CA 机构颁发的合规证书（符合《电子签名法》要求）；
- 证书加载：通过
System.Security.Cryptography.X509Certificates.X509Certificate2类解析 .pfx 文件，是本次实现的核心依赖。
二、核心实现逻辑
PdfOrdinarySignatureMaker 是 Free Spire.PDF 中面向普通电子签名的核心类，其核心流程为：
加载 PDF 文档 → 解析 X.509 证书→ 初始化签名器 → 执行签名 → 保存文档。
以下基于该类实现基础签名功能，并扩展添加可见签名等进阶示例。
1. 基础版：添加基础电子签名（默认不可见）
适用于仅需验签、无需视觉标识的场景，核心代码附带详细注释：
using Spire.Pdf;
using Spire.Pdf.Interactive.DigitalSignatures;
using System;
using System.Security.Cryptography.X509Certificates;namespace PdfDigitalSignature
{class BasicSignatureDemo{static void Main(string[] args){try{// 1. 加载待签名的 PDF 文档using (PdfDocument pdfDoc = new PdfDocument()){pdfDoc.LoadFromFile("Input.pdf"); // 替换为实际文件路径// 2. 加载数字证书（指定密钥存储策略，适配服务器/客户端环境）string certPath = "certificate.pfx"; // 替换为证书实际路径string certPassword = "abc123"; // 替换为证书密码X509Certificate2 cert = new X509Certificate2(certPath,certPassword,// 关键标志：适配服务器环境+避免密钥持久化，提升安全性X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.EphemeralKeySet);// 3. 初始化签名器并执行签名PdfOrdinarySignatureMaker signMaker = new PdfOrdinarySignatureMaker(pdfDoc, cert);// 签名名称：用于后续识别/验证签名，建议唯一signMaker.MakeSignature("Basic_Signature_001");// 4. 保存签名后的文档pdfDoc.SaveToFile("Signed_Basic.pdf");Console.WriteLine("不可见签名添加成功！");}}catch (Exception ex){Console.WriteLine($"签名失败：{ex.Message}");// 进阶：记录异常详情（如堆栈）便于排查Console.WriteLine($"异常详情：{ex.StackTrace}");}}}
}
2. 进阶版：添加可见签名
在基础签名上扩展视觉标识（含签名图片、文本信息），适用于需要直观展示签名的场景：
using Spire.Pdf;
using Spire.Pdf.Interactive.DigitalSignatures;
using System;
using System.Drawing;
using System.Security.Cryptography.X509Certificates;namespace PdfDigitalSignature
{class AdvancedSignatureDemo{static void Main(string[] args){try{// 1. 加载 PDF 文档（using 自动释放资源）using (PdfDocument pdfDoc = new PdfDocument()){pdfDoc.LoadFromFile("Input.pdf");// 2. 加载数字证书string certPath = "certificate.pfx";string certPassword = "abc123";X509Certificate2 cert = new X509Certificate2(certPath,certPassword,X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.EphemeralKeySet);// 3. 初始化签名器PdfOrdinarySignatureMaker signMaker = new PdfOrdinarySignatureMaker(pdfDoc, cert);PdfSignature signature = signMaker.Signature;// 4. 配置签名元信息（将显示在签名外观中）signature.Name = "XX科技有限公司"; // 签名者名称signature.ContactInfo = "010-12345678"; // 联系信息signature.Location = "中国·北京"; // 签名地点signature.Reason = "确认文档内容合规有效";// 签名原因// 5. 配置签名可视化外观PdfSignatureAppearance appearance = new PdfSignatureAppearance(signature);// 自定义标签文本appearance.NameLabel = "签名主体：";appearance.ContactInfoLabel = "联系电话：";appearance.LocationLabel = "签署地点：";appearance.ReasonLabel = "签署原因：";// 添加签名图片（支持 PNG/JPG 等格式）PdfImage signImage = PdfImage.FromFile("signature.png"); // 替换为签名图片路径appearance.SignatureImage = signImage;// 布局模式：图片 + 文本（可选：SignImageOnly/仅图片；SignDetailOnly/仅文本）appearance.GraphicMode = GraphicMode.SignImageAndSignDetail;// 6. 绑定外观并添加到指定位置signMaker.SignatureAppearance = appearance;// 获取目标页面（示例：最后一页）PdfPageBase targetPage = pdfDoc.Pages[pdfDoc.Pages.Count - 1];// MakeSignature 参数说明：签名名称、目标页面、X坐标、Y坐标、宽度、高度、外观signMaker.MakeSignature("Advanced_Signature_001", targetPage, 54.0f, 330.0f, 280.0f, 90.0f, appearance);// 7. 保存文档pdfDoc.SaveToFile("Signed_Advanced.pdf");Console.WriteLine("可视化签名添加成功！");}}catch (Exception ex){Console.WriteLine($"签名失败：{ex.Message}");Console.WriteLine($"异常详情：{ex.StackTrace}");}}}
}
三、关键参数与类说明
PdfOrdinarySignatureMaker：核心签名器类，关联PDF文档与 X.509 证书，执行签名操作。X509Certificate2：加载 .pfx 格式数字证书，解析私钥与公钥。X509KeyStorageFlags：密钥存储标志，控制证书加载的存储区与密钥生命周期MachineKeySet适配服务器环境EphemeralKeySet提升安全性
PdfSignatureAppearance：配置可见签名的外观，包括签名框位置、文本信息等。GraphicMode：可见签名布局样式 (参数:SignImageOnly(仅图片),SignDetailOnly（仅文本）,SignImageAndSignDetail（图片+文本）)MakeSignature：执行签名方法。
四、注意事项
- 证书安全：.pfx 证书包含私钥，需加密存储，避免硬编码密码，建议通过配置文件/密钥管理服务管理；
- 权限适配：服务器环境下加载证书需赋予应用程序足够的密钥访问权限，避免
CryptographicException； - 兼容性测试：签名后的 PDF 需在 Adobe Acrobat、WPS、浏览器等主流阅读器中验证显示与签名有效性；
五、总结
基于 Free Spire.PDF for .NET 的 C# 实现方案，以 “轻量化、低门槛、易集成” 为核心优势，仅需数十行代码即可完成 PDF 电子签名的基础与进阶功能。该方案适配 .NET Framework/.NET Core/.NET 5+ 全框架，能快速落地到企业级文档处理系统中。如需更高的安全性与合规性，可结合 CA 证书、时间戳服务进一步扩展。
相关新闻
