iTextSharp 5 PDF签名添加自定义字典项后无法检测怎么办？

我之前在使用iTextSharp 5处理PDF签名时，也碰到过类似的自定义属性找不到的问题——要么RUPS里查不到，要么代码读不出来。后来才发现是属性加错了位置，下面是亲测有效的实现步骤：

一、正确添加自定义字典属性 #

你需要把自定义属性添加到**签名字典（Signature Dictionary）或者签名域字段字典（Field Dictionary）**中，而不是外观或其他无关字典里。

1. 添加到签名字典（推荐） #

签名字典是签名域值（V键）对应的字典，这是存储签名相关自定义数据的标准位置：

// 初始化PdfStamper和签名外观
using (PdfStamper stamper = PdfStamper.CreateSignature(reader, new FileStream(outputPath, FileMode.Create), '\0'))
{
    PdfSignatureAppearance sap = stamper.SignatureAppearance;
    // 设置签名的基本信息（位置、原因等）
    sap.SetVisibleSignature(new Rectangle(100, 100, 300, 150), 1, "MySignatureField");
    sap.Reason = "Document verification";
    sap.Location = "Office";

    // 创建签名字典对象
    PdfSignature signature = new PdfSignature(PdfName.ADOBE_PPKLITE, PdfName.ADBE_PKCS7_DETACHED);
    // 添加自定义键值对——这里用自定义命名空间前缀避免和标准键冲突
    signature.Put(new PdfName("MyApp:CustomID"), new PdfString("USER-12345"));
    signature.Put(new PdfName("MyApp:SignTime"), new PdfDate(DateTime.Now));

    // 将签名字典绑定到签名外观
    sap.Signature = signature;

    // 执行签名逻辑（这里替换成你的签名实现）
    IExternalSignature externalSignature = new PrivateKeySignature(privateKey, DigestAlgorithms.SHA256);
    MakeSignature.SignDetached(sap, externalSignature, chain, null, null, null, 0, CryptoStandard.CMS);
}

2. 添加到签名域字段字典 #

如果你想把属性和签名域本身绑定（而非签名内容），可以加到字段字典：

// 在设置签名外观后，直接操作FieldDictionary
sap.FieldDictionary.Put(new PdfName("MyApp:FieldProp"), new PdfNumber(999));

二、用RUPS验证自定义属性 #

打开签名后的PDF，按以下路径查找：

1. 展开左侧面板的 AcroForm > Fields，找到你的签名域（比如MySignatureField）
2. 如果是加在签名字典里：点击签名域的 V 键（Value），右侧属性面板就能看到你添加的自定义键值对
3. 如果是加在字段字典里：直接查看签名域的根字典，就能找到自定义属性

三、用代码读取自定义属性 #

要确认属性是否存在，可以通过以下代码读取：

using (PdfReader reader = new PdfReader(signedPdfPath))
{
    AcroFields fields = reader.AcroFields;
    // 获取签名域的签名字典
    PdfDictionary sigDict = fields.GetSignatureDictionary("MySignatureField");
    if (sigDict != null)
    {
        // 读取签名字典里的自定义属性
        PdfString customId = sigDict.GetAsString(new PdfName("MyApp:CustomID"));
        if (customId != null)
        {
            Console.WriteLine($"自定义ID：{customId.ToString()}");
        }

        // 读取字段字典里的自定义属性（如果有的话）
        PdfDictionary fieldDict = fields.GetFieldItem("MySignatureField").GetMerged(0);
        PdfNumber fieldProp = fieldDict.GetAsNumber(new PdfName("MyApp:FieldProp"));
        if (fieldProp != null)
        {
            Console.WriteLine($"字段属性：{fieldProp.IntValue}");
        }
    }
}

常见坑点提醒 #

• 不要把自定义属性加到签名外观（Appearance）字典里，这些只会和签名可视化内容相关，不会被视为签名的元数据
• 自定义键名最好加上自己的应用前缀（比如MyApp:），避免和PDF标准字典键冲突
• 如果用MakeSignature.SignDetached，确保在调用该方法前完成所有字典属性的添加，否则签名生成后无法修改

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