基于两步签名实现PDF全页单修订签名的iText7问题排查

核心问题分析 #

报错“字段不存在”但工具能检测到字段，大概率是字段名称匹配不严格、签名时文档上下文未正确加载AcroForm，或是两步签名的文档处理逻辑不一致导致的。以下是针对性解决方案：

解决方案步骤 #

1. 严格匹配签名字段名称

iText7对字段名称的匹配是大小写、特殊字符敏感的，生成字段时的名称（如"sig_page_1"）和注入签名时指定的名称必须完全一致，不能出现拼写、大小写差异。

2. 注入签名前校验字段存在性

在执行签名注入逻辑前，先主动校验字段是否存在于AcroForm中，避免无效调用：

PdfAcroForm acroForm = PdfAcroForm.getAcroForm(pdfDoc, false);
if (acroForm == null || !acroForm.getFields().containsKey(targetFieldName)) {
    throw new IllegalArgumentException("目标签名字段不存在: " + targetFieldName);
}

3. 采用追加模式加载文档

两步签名必须以追加模式打开生成的带字段PDF，不能覆盖原文档，否则会丢失已创建的签名字段：

PdfReader reader = new PdfReader(sourceSignedFieldPdfPath);
// 开启追加模式，保留原文档的签名字段
PdfWriter writer = new PdfWriter(outputSignedPdfPath, new WriterProperties().setAppendMode());
PdfDocument pdfDoc = new PdfDocument(reader, writer);

4. 批量处理全页签名字段的签名注入

如果每个页面都有独立的签名字段，需要遍历所有签名字段逐个注入签名，确保每个字段都关联到对应的签名哈希：

PdfAcroForm acroForm = PdfAcroForm.getAcroForm(pdfDoc, false);
SignatureUtil signatureUtil = new SignatureUtil(pdfDoc);

// 遍历所有签名字段
for (Map.Entry<String, PdfFormField> fieldEntry : acroForm.getFields().entrySet()) {
    String fieldName = fieldEntry.getKey();
    PdfFormField field = fieldEntry.getValue();
    
    // 确认当前字段是签名字段
    if (PdfName.Sig.equals(field.getFieldType())) {
        // 绑定签名外观到对应页面的字段位置
        PdfSignatureAppearance appearance = pdfDoc.getSignatureAppearance();
        appearance.setFieldName(fieldName);
        PdfWidgetAnnotation widget = field.getWidgets().get(0);
        appearance.setPageRect(widget.getRectangle().toRectangle());
        appearance.setPageNumber(widget.getPageNumber());
        
        // 注入客户端返回的签名哈希
        IExternalSignatureContainer container = new PreSignedContainer(clientSignatureHash);
        signatureUtil.signDeferred(pdfDoc, fieldName, writer, container);
    }
}

pdfDoc.close();

5. 自定义签名容器实现

实现IExternalSignatureContainer类，直接返回客户端已完成签名的哈希值：

private static class PreSignedContainer implements IExternalSignatureContainer {
    private final byte[] signedHash;

    public PreSignedContainer(byte[] signedHash) {
        this.signedHash = signedHash;
    }

    @Override
    public byte[] sign(InputStream data) {
        // 客户端已完成签名，直接返回签名结果
        return signedHash;
    }

    @Override
    public void modifySigningDictionary(PdfDictionary signDic) {
        // 设置签名标准属性
        signDic.put(PdfName.Filter, PdfName.Adobe_PPKLite);
        signDic.put(PdfName.SubFilter, PdfName.Adbe_pkcs7_detached);
    }
}

6. 排查字段名称差异

如果仍报错，可打印所有字段名称确认匹配情况：

if (acroForm != null) {
    System.out.println("当前文档的签名字段列表: " + acroForm.getFields().keySet());
}

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