使用C#嵌入数字签名至PDF及iText7空异常问题排查

先解决你遇到的空指针异常问题 #

你代码里的空异常，核心原因是创建签名字段后没有关联对应的WidgetAnnotation——iText7要求签名表单字段必须绑定至少一个Widget才能正常初始化，否则会触发内部空引用。

修正后的基础代码（添加可视化签名域并填充内容）：

using iText.Kernel.Pdf;
using iText.Forms;
using iText.Forms.Fields;
using iText.Layout;
using iText.Layout.Element;
using iText.Kernel.Geom;
using System;

// 初始化PDF读写对象
PdfReader reader = new PdfReader("document.pdf");
PdfWriter writer = new PdfWriter("document-signed.pdf");
PdfDocument pdfDoc = new PdfDocument(reader, writer);

// 获取或创建AcroForm表单
PdfAcroForm form = PdfAcroForm.GetAcroForm(pdfDoc, true);
if (form == null)
{
    throw new InvalidOperationException("无法初始化PDF表单");
}

// 创建签名字段
PdfFormField signatureField = PdfFormField.CreateSignature(pdfDoc);
signatureField.SetFieldName("Signature");

// 关键步骤：创建WidgetAnnotation并关联到字段和页面
Rectangle signatureRect = new Rectangle(100, 100, 150, 50);
PdfWidgetAnnotation signatureWidget = new PdfWidgetAnnotation(signatureRect);
signatureWidget.SetHighlightMode(PdfAnnotation.HIGHLIGHT_INVERT); // 设置点击高亮效果
signatureField.AddKid(signatureWidget);
pdfDoc.GetFirstPage().AddAnnotation(signatureWidget);

// 将字段添加到表单
form.AddField(signatureField);

// 在签名区域添加可视化文本
Canvas canvas = new Canvas(new PdfCanvas(pdfDoc.GetFirstPage()), signatureRect);
canvas.Add(new Paragraph($"签名内容: {signature}").SetFontSize(12));

// 设置字段值
signatureField.SetValue("签名已验证");

// 关闭资源
pdfDoc.Close();
reader.Close();
writer.Close();

如果你要嵌入的是数字签名（PKCS#7格式） #

从你的API流程来看，签名服务返回的应该是基于PDF哈希生成的PKCS#7签名字节，这种场景下应该用iText7的PdfSigner类来完成标准数字签名嵌入，这是合规的PDF数字签名方式：

using iText.Kernel.Pdf;
using iText.Signatures;
using System.IO;

// 读取原始PDF
PdfReader reader = new PdfReader("document.pdf");
// 输出已签名的PDF文件
FileStream outputStream = new FileStream("document-signed.pdf", FileMode.Create);
PdfSigner signer = new PdfSigner(reader, outputStream, new StampingProperties());

// 配置签名外观
Rectangle signatureRect = new Rectangle(100, 100, 150, 50);
PdfSignatureAppearance appearance = signer.GetSignatureAppearance();
appearance.SetReason("业务文档签署")
         .SetLocation("签署地点")
         .SetRect(signatureRect)
         .SetPageNumber(1);

// 替换为你的签名服务返回的PKCS#7签名字节数组
byte[] signatureBytes = GetSignatureFromYourService();

// 嵌入签名
signer.SetSignatureContainer(new ExternalBlankSignatureContainer(PdfName.Adobe_PPKLite, PdfName.Adbe_pkcs7_detached));
signer.SignExternalContainer(new ExternalSignatureContainerImpl(signatureBytes), 8192);

// 关闭资源
reader.Close();
outputStream.Close();

// 辅助类：实现签名容器
public class ExternalSignatureContainerImpl : IExternalSignatureContainer
{
    private readonly byte[] _signatureBytes;

    public ExternalSignatureContainerImpl(byte[] signatureBytes)
    {
        _signatureBytes = signatureBytes;
    }

    public void ModifySigningDictionary(PdfDictionary signDic)
    {
        // 无需额外修改，保持默认配置即可
    }

    public byte[] Sign(Stream data)
    {
        // 直接返回签名服务提供的签名字节（因为你已经提前计算PDF哈希并获取了签名）
        return _signatureBytes;
    }
}

额外注意事项 #

1. 确保使用的是iText7的最新稳定版本（7.2.x及以上），旧版本可能存在API兼容性问题；
2. 如果你的PDF已经存在AcroForm，要确保表单结构没有损坏；
3. 数字签名嵌入后，PDF会被加密，无法再修改（除非移除签名），这是PDF数字签名的合规要求。

内容的提问来源于stack exchange，提问作者plexus