简介面向需要为OFD文档接入电子签章能力的Java开发者这份资源围绕开源项目ofdrw展开提供了可直接参考的签章demo与配套的OFD使用说明。OFD是国家标准的电子文档格式在政务、企业文档流转中应用广泛签章流程涉及数字证书、哈希计算、电子印章生成与验证等关键环节。资源包共606个文件以462个java源码文件为主配合31个OFD样例文档、21个XML配置和16个Markdown说明另有p12、der、esl等证书文件及字体、图片素材便于开发调试整体压缩包约76.61MB。目前已有330人学习下载。开发者通过demo代码与说明文档可快速熟悉ofdrw的API调用方式掌握OFD文档解析、对象操作、签章插入及证书管理并在此基础上按业务场景定制自己的电子签章方案。1. OFD签章Demo到底解决了什么问题从一份被拒收的采购合同说起去年年底某单位交付一批采购合同电子档结果被对方单位系统直接拒收理由是“文件未签章无法归档”。对方要求的不是PDF盖章而是OFD电子签章——一种基于国密算法的版式文档格式。当时身边没人搞过OFD翻遍网上资料要么是规范原文要么是厂商SDK的广告页真正能一键跑起来的Demo少得可怜。这份OFD签章Demo的价值就在这它把从解析OFD文件、读取签名节点、验签到在线调起签章、校验证书链的完整链路用可运行代码串了一遍还附带了一份使用说明。适合两类人一类是要在业务系统里接入OFD签章的Java后端开发者另一类是刚接手电子档案项目、被“签章验章”搞懵的测试或实施人员读完能明白这东西到底怎么工作。2. 脱机验签模块先把签名验出来再谈其他2.1 OFD文件结构与签名节点签名藏在哪OFD是基于XML描述、ZIP压缩包存储的版式文档。打开一个签过章的OFD文件能看到一个signatures目录里面存放签名描述文件Signature.xml和签名值文件。签名值通常以XML数字签名语法封装关键节点是Signature下的SignedInfo、SignatureValue和SignedValue等。验签的第一步不是跑代码而是先理解这些节点的层级关系。一个签名字段可能对应文档里的多个内容区域比如一个印章图片覆盖块、一段文档摘要。签名算法一般使用SM2withSM3公钥来自内含的签名证书。这个Demo里给的验签工具类核心逻辑就是读取签名值、提取原文摘要、用证书公钥做SM2验签。至于文件里的内容是否有变动还要比对SignedInfo里记录的摘要值与实际文件摘要是否一致。2.2 用Java跑通验签Demo解析XML与校验SM2签名Demo里的脱机验签类主要依赖javax.xml.crypto和org.bouncycastle两套库。下面这段是核心逻辑通过XML签名解析拿到签名值后用国密算法验签。// VerifySignature.java - OFD脱机验签核心片段 public boolean verify(String ofdFilePath, String signatureXmlPath) { try { // 1. 从OFD压缩包中读取签名节点 ZipFile zip new ZipFile(ofdFilePath); ZipEntry entry zip.getEntry(META-INF/signatures/Signature.xml); InputStream is zip.getInputStream(entry); // 2. 构造DOM解析XML签名 DocumentBuilderFactory dbf DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); Document doc dbf.newDocumentBuilder().parse(is); NodeList sigList doc.getElementsByTagName(ds:Signature); // 3. 取SignatureValue节点中的签名值Base64编码 String sigValueB64 doc.getElementsByTagName(ds:SignatureValue) .item(0).getTextContent().trim(); byte[] sigValue Base64.getDecoder().decode(sigValueB64); // 4. 取出签名证书公钥构造SM2验证对象 X509Certificate cert readCertFromSignature(doc); SM2PublicKey publicKey new SM2PublicKey(cert.getPublicKey()); // 5. 做实际验签操作摘要算法SM3 SM2Signer signer new SM2Signer(); signer.init(false, new ParametersWithID(publicKey, SM2Util.ID)); signer.update(sigValue, 0, sigValue.length); return signer.verifySignature(readSignedValueBytes(doc)); } catch (Exception e) { logger.error(验签失败, e); return false; } }逻辑说明第一步先解压OFD找到签章描述文件第二步把XML转成DOM树提取节点第三步取出Base64格式的签名值第四步解析证书公钥第五步用Bouncy Castle的SM2验签对象做校验。整个过程没有调用任何网络接口适合在离线环境下跑。参数说明Signature.xml可能不在META-INF/signatures/下有的厂商实现会放在其他目录。Demo里是用通配ZipFile.getEntry查找签名文件如果找不到需要到Doc_0.xml里找签名节点引用的路径。SM2Signer.init(false, ...)第二个参数传的是签名者ID标准SM2规范默认是1234567812345678国密标准里约定过这一项但部分厂商实现会自定义ID验签前最好先查文档确认。2.3 参数表算法参数与容错边界上面代码里涉及的参数在实际生产环境几乎每个都要确认一遍。下表是Demo使用说明里列出的核对项参数说明常见取值坑点摘要算法对原文章节算摘要SM3有的厂商用SHA256验签直接失败签名算法对摘要做签名SM2withSM3证书没启用签名用途时会失败签名者IDSM2验签参数1234567812345678自定义ID会导致验签不通过签章值格式SignatureValue节点内容BASE64部分实现用HEX字符串需转码证书格式XML中内嵌证书X.509 DER需要解开证书链做逐级校验这个表格是我根据实际对接经验总结的不是OFD规范原文的直接摘录。参数对不上代码再好也验不过。所以做脱机验签时先拿一个已知正常的签名文件跑通再改业务场景比直接拿生产文件调要稳。3. 在线签章流程从笔迹图片到标准签名值3.1 在线签章和手动签章差异在哪手动签章通常是本地装客户端插上USBKey在可视化界面上拖动印章。而在线签章是业务系统通过后台接口调用签名服务把待签文件内容摘要发送到签名服务端服务端用保存的私钥完成签名。签名服务端可以是自建国密设备也可以是第三方签名平台。Demo里作为示例的是某跨平台系统组件它只负责拼装请求和解析响应真正做签名的还是服务端。与本地签章不同在线签章需要额外处理一个问题印章图片的定位。章要盖在OFD文件可视区域的哪个坐标这个信息要随签章请求一起传给服务端。坐标的标准是页面左上角或左下角为原点不同组件定义不同。Demo使用说明里明确写了坐标偏移量以毫米为单位页面高度以实际内容尺寸为准不要用页面像素值换算。3.2 调用验签组件的Sign方法真实请求参数// SignRequestBuilder.java 在线签章请求构造 SignRequest request new SignRequest(); request.setDocPath(/data/contracts/vendor_a_2023.ofd); // 1.待签文档路径 request.setSealPath(/data/seals/company_seal.png); // 2.印章图片路径 request.setPageNo(3); // 3.盖在第3页 request.setX(56.7f); // 4.印章左上角X坐标毫米 request.setY(142.3f); // 5.印章左上角Y坐标毫米 request.setWidth(50.0f); // 6.印章显示宽度毫米 request.setHeight(50.0f); // 7.印章显示高度毫米 request.setSignType(SM2withSM3); // 8.签名算法 request.setCertId(CERTID_2024_A001); // 9.证书标识由服务端预先分配 request.setReason(同意本次采购合同内容); // 10.签名原因会写入签名属性 SignResult result signClient.execute(request); if (result.isSuccess()) { // 成功后签章组件会把签章结果写回到原OFD文档的Copy中 }逻辑说明这段代码把一次在线签章需要交代的信息全部封装进SignRequest。执行签章请求后组件会在服务端返回的签名值基础上主动修改OFD文件结构把签名节点挂到文档签名列表中去。参数说明sealPath指向的图片必须是透明背景PNG带白底会直接盖出白块。pageNo从1开始不是从0开始。坐标单位是毫米如果从PDF转过来的OFD页面尺寸要按PDF原始尺寸除以25.4换算成毫米。certId需要在签章前到服务端注册注册时会绑定证书和私钥信息。3.3 服务端证书链准备证书上下级顺序怎么传验章时如果只校验叶子证书不求上链到根证书会出现一种情况签名值有效但证书本身已过期或属于测试环境签发业务上依旧不认。Demo里的服务端示例代码支持把整条证书链以参数方式传入签名服务签名时证书链会随签名值一起封装进OFD文件。这样验签方打开文件就能看到完整信任链不必单独找根证书。证书链顺序有讲究请求时必须先放签名证书叶子再放中间CA证书最后放根证书。传反了部分解析组件会直接拒绝生成签名值。如果签章服务端返回错误先把证书数组的顺序打乱重试几次能快速确认是不是这个问题。另外证书过期前30天就要准备替换不然线上签章会突然失败而日志里只会提示“证书无效”不会说是过期导致。4. 避坑指南OFD签章常见的五个翻车现场4.1 印章图片盖完是一团黑块现象签章后OFD文件在阅读器里显示成黑块或白底方块完全看不到印章内容。原因印章PNG的通道格式不兼容。OFD组件对位深和透明通道有严格要求部分在线生成的PNG用了不支持的颜色格式比如CMYK或16位通道组件无法正确渲染透明区域。解决先把印章图片转成RGBA 8位PNG再用pngcheck之类工具确认没有附加ICC颜色配置文件。正确转换后再签黑块现象就消失了。4.2 Signature.xml 读取出来为空现象解压OFD文件后签名字节为空或者只有“\n”字符。原因OFD规范里允许签名值使用外部引用方式即SignatureValue节点内不写签名值而是通过Reference指向另一个文件比如SignedValue.dat。很多教程只讲了签名值内嵌的情况没有覆盖外部引用的结构。解决解析Signature.xml时不仅读节点文本还要检查是否存在外部引用。如果存在定位被引用的文件再从该文件中读取签名值。Demo使用说明里专门标注了这个点代码里也做了对应的兜底处理。4.3 服务器时间不正确导致验签时间戳失败现象签名本身没问题但验签结果一直报“时间戳验证失败”。原因OFD签章支持附带时间戳时间戳服务端校验的是请求时间。如果服务器时间比真实时间提早或延迟超过5分钟时间戳服务就会拒绝签发。解决部署前用系统命令同步时间比如ntpdate ntp.aliyun.com。在容器环境里记得检查宿主机时间而非容器内时间。4.4 同一OFD文件多次签章第二次覆盖第一次现象一个文件签两个章第二次签完后第一个章验不出来了。原因在线签章组件默认以“单签名”模式工作。第二次签章时组件清空了原有的签名节点列表再写入新签名而不是追加。解决使用组件提供的“追加签名接口”而不是普通签名接口。如果组件没提供需要在主请求中把已有签章信息先读出来再合并到新签名请求的签名节点列表中。Demo里给了mergeSignatureNodes方法的示例。4.5 验签在Windows通过Linux上不通过现象同一份签章文件在Windows环境下验签通过部署到Linux服务器后验签失败。原因常见原因是缺少国密算法提供者JDK默认不包含SM2/SM3实现BouncyCastle的版本不一致也会导致算法注册失败另一个原因是Linux系统字体缺失OFD里印章字体被渲染成乱码影响了摘要比对结果。解决确认生产环境的JDK与Demo开发环境一致并固定BouncyCastle版本号。字体问题可以在Linux系统里安装fonts-wqy-microhei解决。5. 进阶技巧验完签名后再校验文档版本一致性签章验签通过只能说明签名值有效、证书可信。但业务上还有一个关键问题这份签章文档是否就是当初参与签章的那一份。通俗讲要防的是“签章是签了但签章后内容被偷偷替换”的情况。做法是做一个文档层面的一致性校验打开OFD文件解压对最终文件整体计算SM3摘要跟SignedInfo里记录的文档摘要做比对。如果两边一致说明文件最后被签完后没发生过改动。这个摘要值和签名值的区别在于签名值是对摘要的签名而摘要值是对原始文档内容的直接哈希结果。只验签不比对摘要等于只看锁有没有换却没检查保险柜里的文件。// DocumentIntegrityChecker.java 文档摘要比对 public boolean checkIntegrity(String ofdFilePath, String signatureXmlPath) { try { // 1. 读OFD所有字节计算SM3摘要 byte[] docBytes Files.readAllBytes(Paths.get(ofdFilePath)); byte[] docHash SM3Util.hash(docBytes); // 2. 从签名XML中提取原始文档摘要 String originalHashB64 extractOriginalHash(signatureXmlPath); byte[] originalHash Base64.getDecoder().decode(originalHashB64); // 3. 比对摘要 return Arrays.equals(docHash, originalHash); } catch (Exception e) { logger.error(校验文档一致性失败, e); return false; } }逻辑说明这个一致性校验相当于多了一道防线防止签章文件在传输过程中或存储过程中被改动。参数说明extractOriginalHash方法实际是从SignedInfo节点的DigestValue里取值有的组件把这个值写在了Properties标签里解析时可多写几个分支尝试。校验时建议用SM3而不用MD5或SHA1国密算法与文件内部签名算法保持一致验签环境里跑起来不用额外引入其它算法库。从那次被拒收合同以后我每次接OFD签章相关需求都强制自己走一遍这套流程先跑通脱机验签再联调在线签章最后补一遍文档摘要比对。哪怕对方说只是临时用一下也别跳过这些步骤希望帮到你。本文还有配套的精品资源点击获取
