简介：这份资料包面向需要在Java项目中落地OFD电子签章的开发者，围绕国标OFD文档格式，提供签章功能的可运行示例与使用说明。内容涵盖数字证书生成、文档哈希计算、签章生成与插入、签章验证等关键环节，并借助ofdrw开源库演示文档解析、对象操作、签章服务与证书管理等能力，适合具备一定Java基础、希望理解OFD签章机制并动手实践的中级开发者参考。压缩包为rar格式，共606个文件，以462个java源码为主体，辅以31个ofd样例文档、40张jpg与9张png图示、21个xml配置及esl、p12、der等证书签章数据文件，整体约76.61MB，目录结构便于按模块检索。已有331人学习，读者可结合示例代码与说明文档，快速理清签章调用流程与验证思路，为自建OFD电子签章方案提供可复用的参考。

1. 拿到一份 OFD 签章 Demo，先别急着跑：它到底能解决什么

OFD 签章这件事，很多人第一次接触是在项目验收前两周：业务方甩过来一批版式文件，要求“盖上章、能验签、别被篡改”，而团队里没人真正拆过 OFD 的容器结构。这份「实现 OFD 签章的 demo 及 OFD 使用说明」就是为这种场景准备的——它把 OFD 版式文档的签章流程做成可运行的最小闭环，同时附上 OFD 本身的使用说明，让你既能看懂文件里有什么，也能动手把章盖进去、把签名验出来。

它适合三类人：一是需要在业务系统里集成电子签章能力、但不想从零啃标准的后端工程师；二是要判断“这个文件到底有没有被改过”的交付与运维人员；三是想搞清楚 OFD 与常见版式格式差异、需要做格式转换与归档的技术负责人。读完你至少能回答四个问题：OFD 包结构长什么样、签章数据放在哪、签名值怎么算、验签失败该从哪查。下面按“先立结构、再跑流程、最后排坑”的顺序拆。

2. OFD 包结构与签章数据落点：先看懂文件再谈盖章

OFD 本质上是一个 ZIP 容器，里面按约定目录存放版式描述、资源、签名等条目。签章不是“往页面上贴一张图”，而是把印章外观、签名值、证书信息、保护范围一起写进特定条目，并让这些条目被摘要覆盖。搞不清落点，后面所有调试都是盲人摸象。

2.1 容器目录与关键条目

一个典型 OFD 解压后能看到这些层级（不同生成工具会有细微差异，但主干一致）：

用命令行解包看一眼最直观：

# 把 ofd 当 zip 解开，先看目录骨架 mkdir -p ofd_unpacked && cd ofd_unpacked unzip -o ../sample.ofd # 列出所有条目，重点找 Signs 目录 find . -type f | sort

这段命令没有玄学，关键是unzip能成功——如果解不开，说明文件不是标准 ZIP 封装或已损坏，后面签章无从谈起。find的输出用来确认Signs目录是否存在：没有它，说明这份文件从未签过章，你面对的是“首次签章”而不是“验签”场景，两者排查路径完全不同。

2.2 签名描述文件里到底写了什么

Signs.xml是理解签章行为的黑匣子入口。它通常包含签名节点列表，每个节点引用一个签名目录，并声明保护范围（哪些条目被摘要覆盖）、签名方法、印章引用。常见做法是：保护范围用条目路径列表表达，签名方法标明算法标识，印章通过Seal.esl关联外观。

读这个文件时我一般关注三件事：保护范围是否覆盖了Content.xml和Document.xml（只盖图片不盖内容等于没盖）、签名方法标识是否与证书公钥算法匹配、印章引用路径是否真实存在。任何一项对不上，验签阶段就会以“摘要不一致”或“引用缺失”的形式爆出来。demo 里通常会给一份带注释的示例，照着改比凭空猜快得多。

提示：不要用文本编辑器直接改Signs.xml后重新打包，ZIP 条目顺序和压缩方式变化都可能影响摘要计算，改完必须走完整签章流程重签。

3. 跑通签章 Demo：从证书准备到签名值写入

这一章是动手部分。签章 demo 的价值在于把“摘要计算 → 签名 → 写回容器”这条链路摊开给你看，而不是调一个封装好的黑盒接口。下面按依赖、证书、签章、验签四步走，每步都给可抄的命令或代码骨架。

3.1 环境与依赖准备

demo 一般以某种语言实现，常见是 Java 或 Python 调用密码库。以 Python 为例，需要能处理 ZIP、能做摘要与公钥签名。先确认基础环境：

python3 --version pip install pycryptodome lxml # 确认 openssl 可用，后面生成测试证书要用 openssl version

pycryptodome提供摘要与签名原语，lxml用于解析和回写 XML 且保留命名空间——OFD 的 XML 对命名空间敏感，用标准库xml.etree回写容易丢前缀导致结构非法，这是很多人第一次跑 demo 就翻车的地方。openssl用来造自签测试证书，生产环境当然换成合规证书，但调试阶段自签足够。

3.2 生成测试证书与密钥对

签章离不开证书。调试阶段用自签证书即可，重点是理解“私钥签名、证书带公钥、验签方用证书验”的闭环：

# 生成私钥与自签证书，有效期 365 天 openssl req -x509 -newkey rsa:2048 -keyout test_key.pem -out test_cert.pem \ -days 365 -nodes -subj "/CN=OFD-Test-Seal/O=Demo" # 导出公钥，验签时用 openssl x509 -in test_cert.pem -pubkey -noout > test_pub.pem

-nodes表示私钥不加密，方便脚本读取，生产环境应加密保管。-subj里的字段只是占位，真实签发由证书机构完成。生成后要确认私钥与证书匹配：用私钥签一段数据、用证书公钥验，能过才继续，否则后面所有失败都会指向错误方向。

3.3 签章主流程：摘要、签名、写回

签章的核心逻辑可以浓缩成一段伪代码式的真实代码。下面这段演示“对保护范围内的条目计算摘要并签名，再把签名值写入签名目录”：

import hashlib, zipfile, os from Crypto.Signature import pkcs1_15 from Crypto.Hash import SHA256 from Crypto.PublicKey import RSA def collect_protected_entries(zip_path, protected_paths): """按保护范围收集条目内容，顺序必须稳定""" digests = {} with zipfile.ZipFile(zip_path, 'r') as zf: for p in protected_paths: data = zf.read(p) # 原始字节，不做任何转换 digests[p] = hashlib.sha256(data).hexdigest() return digests def sign_digest_map(digests, key_path): """把条目摘要按固定顺序拼接后再摘要，最后用私钥签名""" ordered = "".join(f"{k}:{digests[k]}" for k in sorted(digests)) h = SHA256.new(ordered.encode('utf-8')) key = RSA.import_key(open(key_path).read()) return pkcs1_15.new(key).sign(h) if __name__ == "__main__": protected = ["Doc_0/Document.xml", "Doc_0/Pages/Page_0/Content.xml"] d = collect_protected_entries("sample.ofd", protected) sig = sign_digest_map(d, "test_key.pem") with open("SignedValue.dat", "wb") as f: f.write(sig) # 写回签名目录，再重新打包 print("signed bytes:", len(sig))

逻辑说明：第一步按保护范围逐条读取原始字节算 SHA-256，注意是“原始字节”，任何解压后再编码转换都会改变摘要；第二步把条目名与摘要按排序后拼接再整体摘要，排序是为了让签名方与验签方得到一致输入，这是最容易出分歧的参数点；第三步用 RSA 私钥做 PKCS#1 v1.5 签名，输出二进制写入SignedValue.dat。参数上，保护范围列表必须与Signs.xml声明完全一致，算法标识要与这里用的 SHA-256 + RSA 对应，否则验签方按声明算法算出来的结果对不上。

3.4 验签：把摘要重算一遍

验签不是“看签名文件在不在”，而是用证书公钥解签名、重算摘要、逐条比对：

from Crypto.Signature import pkcs1_15 from Crypto.Hash import SHA256 from Crypto.PublicKey import RSA def verify(zip_path, protected_paths, sig_path, cert_pub_path): d = collect_protected_entries(zip_path, protected_paths) ordered = "".join(f"{k}:{d[k]}" for k in sorted(d)) h = SHA256.new(ordered.encode('utf-8')) pub = RSA.import_key(open(cert_pub_path).read()) sig = open(sig_path, 'rb').read() try: pkcs1_15.new(pub).verify(h, sig) return True except (ValueError, TypeError): return False

这里的关键参数是protected_paths必须与签章时一致，且读取的是“当前文件”的条目——如果签章后被改过任何一个受保护条目，重算摘要就变，验签必然失败。返回False时不要急着怀疑算法，先打印重算出的摘要与签名时记录的摘要做对比，差异定位到具体条目，问题就收敛了。

4. 避坑与排查：签章跑不通时先看这几处

签章 demo 跑不起来，九成不是密码学问题，而是容器与结构问题。下面五条是我拆这类项目时反复遇到的，按“现象 → 原因 → 解决”记。

4.1 验签总失败但签名文件明明存在

现象：SignedValue.dat有内容，验签返回假。原因多半是保护范围不一致——签章时覆盖了三个条目，验签时只传了两个，拼接输入不同，摘要自然不同。解决：把Signs.xml里声明的保护范围解析出来，原样传给验签函数，不要手写列表。

4.2 重新打包后文件打不开

现象：改完签名重新 ZIP 后，阅读器报结构错误。原因是用普通压缩工具打包，条目顺序、是否压缩、ZIP64 标志与原始不一致，部分阅读器对OFD.xml必须位于首条有要求。解决：用脚本按原始条目顺序重建 ZIP，OFD.xml放第一条，保持条目名不变。

4.3 摘要对不上但内容看起来没变

现象：肉眼对比 XML 一样，摘要却不同。原因是 XML 换行符或属性顺序被编辑器改动，或者读取时做了 UTF-8 解码再编码。解决：全程按二进制读写，比较时用十六进制 diff 工具定位到字节级差异。

4.4 印章显示位置偏移

现象：章盖上了但跑到页面外。原因是印章外观坐标与页面坐标系不一致，Seal.esl里的边界框单位或原点定义与页面不匹配。解决：先确认页面尺寸与坐标单位，再按相对位置换算印章边界框，别直接抄示例里的绝对坐标。

4.5 证书链验不过

现象：签名值能解出，但证书校验失败。原因是自签证书不在信任列表，或中间证书缺失。解决：调试阶段显式信任测试证书，生产环境补齐证书链，并确认证书有效期与密钥用法包含数字签名。

注意：任何一次“改完再打包”都要重走完整签章流程，不要试图只替换签名值文件，摘要与保护范围是绑定的。

5. 进阶：把签章做成可回归的验证脚本

demo 跑通只是起点，真正省时间的是把它变成可重复执行的验证脚本。我的习惯是给每份样本配一个清单文件，记录保护范围、算法标识、证书指纹，然后用一个入口脚本批量跑“签章 → 验签 → 篡改后应失败”三态测试。这样每次换证书、换样本、升级依赖，都能在几分钟内确认链路没退化。

具体做法：准备三份输入——原始未签样本、签章后样本、签章后改动一个受保护条目的样本。期望结果是：第一份验签失败（无签名）、第二份通过、第三份失败。脚本里把三次结果打印成一行，任何一次不符合预期就退出非零码，方便接进流水线。参数上重点盯两个：保护范围列表从Signs.xml动态解析而非硬编码，证书指纹每次运行前比对，防止误用旧证书导致“看起来通过其实验的是别的证书”。

这套三态测试帮我挡过好几次“依赖升级后签名算法默认值变了”的隐性回归——表面能签能验，实际算法标识与实现不一致，换个验签方就崩。从那以后我每次接签章类需求，都强制先把这三态脚本跑一遍再谈业务集成，省下的返工时间远超写脚本的那半小时。希望帮到你。

本文还有配套的精品资源，点击获取