sslTrusJarsigner 使用指南

准备工作

使用前请准备：

• JDK 8 或更高版本。
• sslTrusJarsigner-<version>.jar。
• Access Key、Access Secret 和证书编号。
• 待签名的 JAR 文件或 TIMS/1E XML 文件。

请将本文中的 <version>、凭证、证书编号和文件路径替换为实际值。

下载

通过以下页面下载最新发布包：

下载最新包

下载并解压 ZIP 文件后，可获得：

• sslTrusJarsigner-<version>.jar
• SHA-256 校验文件

建议在使用前根据校验文件核对 JAR 文件的完整性。

检查运行环境

执行以下命令确认 Java、jarsigner 和工具文件可用：

java -version
jarsigner -help
java -jar sslTrusJarsigner-<version>.jar --version

查看帮助信息：

java -jar sslTrusJarsigner-<version>.jar --help

配置凭证

Linux 和 macOS

export SSLTRUS_JARSIGNER_ACCESS_KEY="YOUR_ACCESS_KEY"
export SSLTRUS_JARSIGNER_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SSLTRUS_JARSIGNER_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell

$env:SSLTRUS_JARSIGNER_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SSLTRUS_JARSIGNER_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SSLTRUS_JARSIGNER_CERT_CODE = "YOUR_CERT_CODE"

如果服务人员提供了专用服务地址，还需要设置：

Linux 和 macOS：

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

未提供专用服务地址时，请不要设置该变量。

签名

以下示例将 app-unsigned.jar 签名后保存为 app-signed.jar。固定参数请按示例原样使用。

JDK 9 或更高版本

Linux 和 macOS：

jarsigner \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerPath "sslTrusJarsigner-<version>.jar" \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerPath "sslTrusJarsigner-<version>.jar" `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

JDK 8

请先确认 JAVA_HOME 指向完整的 JDK 8。

Linux 和 macOS：

jarsigner \
  -J-cp \
  -J"$JAVA_HOME/lib/tools.jar:sslTrusJarsigner-<version>.jar" \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -J-cp `
  "-J$env:JAVA_HOME\lib\tools.jar;sslTrusJarsigner-<version>.jar" `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

注意

• 命令最后的证书编号必须与 SSLTRUS_JARSIGNER_CERT_CODE 一致。
• 建议始终使用 -signedjar 生成新文件，避免覆盖原始 JAR。
• 如果不需要时间戳，可以删除 -tsa 及其后的地址。

签名 XML（XMLDSig）

TIMS/1E XML 使用 sign-xml 命令生成 XML Digital Signature（XMLDSig） enveloped 签名。私钥仍只保留在远程签名服务中；工具会在本地生成 XMLDSig 所需的摘要和签名结构，再由远程服务完成 RSA 签名。

Linux 和 macOS：

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  sign-xml `
  "input.xml" `
  "signed.xml" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

签名格式

生成的签名使用 XMLDSig 标准命名空间 http://www.w3.org/2000/09/xmldsig#，Signature 节点作为根节点的最后一个子节点写入输出文件。当前签名 profile 固定如下：

项目	固定值
签名类型	Enveloped signature
签名范围	整份 XML 文档，Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
摘要算法	SHA-256
签名算法	RSA-SHA256
KeyInfo	X509Data，默认包含叶子证书

调用方无需自行计算摘要或构造 SignatureValue。工具会使用远程证书的叶子证书填充 KeyInfo/X509Data，并在 XML 中写入最终的 SignatureValue。

包含完整证书链

默认输出仅包含叶子证书，以减小 XML 体积并与常见 TIMS/1E 文件保持一致。若接收方要求 XML 内携带中间证书链，请在命令末尾加入 --full-chain：

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  --full-chain

--full-chain 只影响 KeyInfo/X509Data 中的证书列表，不改变签名范围、摘要算法或签名算法。该选项可以放在证书编号之前或之后；未提供证书编号时，使用 SSLTRUS_JARSIGNER_CERT_CODE。

输入与使用限制

• 输入必须是格式正确的 XML，且包含根节点。
• 输入文件不能已包含 XMLDSig Signature 节点；工具会拒绝重复签名，避免产生无法确认签名范围的文件。
• 当前仅支持整份文档的 enveloped 签名；不支持 detached signature、按元素 ID 签名或自定义 XMLDSig profile。
• 工具会禁用 XML 外部实体和外部 DTD 加载，因此不接受依赖外部实体展开的 XML。
• 签名完成后不要再修改 XML 的结构、文本、属性或命名空间；任何此类改动都会导致 XMLDSig 验证失败。应始终保留原始输入文件，并将签名结果写入新的输出文件。

生成验证文件

签名后，可以生成验证所需的 JKS 文件：

Linux 和 macOS：

java -jar sslTrusJarsigner-<version>.jar \
  generate-keystore \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  "verify.jks" \
  "SSLTRUS"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  generate-keystore `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE" `
  "verify.jks" `
  "SSLTRUS"

verify.jks 仅用于验证签名，不能用于执行签名。

验证签名

使用生成的 verify.jks 验证已签名 JAR：

jarsigner \
  -verify \
  -verbose \
  -certs \
  -keystore "verify.jks" \
  -storetype JKS \
  -storepass "SSLTRUS" \
  "app-signed.jar"

如果只需要查看 JAR 的签名信息：

jarsigner -verify -verbose -certs "app-signed.jar"

常见问题

提示缺少 Access Key、Access Secret 或证书编号

请确认当前终端已经设置以下环境变量：

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

设置环境变量后，需要在同一个终端窗口中执行签名命令。

提示 非法选项: -providerPath

当前使用的是 JDK 8。请改用本文中的 JDK 8 签名命令。

提示无法加载 com.racent.codesign.SSLTrusProvider

请检查：

• sslTrusJarsigner-<version>.jar 路径是否正确。
• 文件名中的版本号是否与实际文件一致。
• JDK 8 的 JAVA_HOME 是否指向完整 JDK。

提示找不到证书或 alias

请检查：

• 证书编号是否正确。
• 命令最后的证书编号是否与环境变量一致。
• 当前凭证是否有权使用该证书。

签名请求失败

请检查：

• 网络连接、代理和防火墙设置。
• 凭证和证书编号是否正确。
• 专用服务地址是否按服务人员提供的内容配置。

如仍无法解决，请保留完整错误信息并联系技术支持。提交错误信息前，请删除或遮盖凭证。

时间戳失败

请确认当前网络能够访问命令中的时间戳地址。如果业务允许，可以临时删除 -tsa 及其后的地址，再次执行签名以定位问题。

安全注意事项

• 不要在源码、文档、共享脚本或镜像中保存真实 Access Secret。
• 不要对外共享包含凭证的命令行、终端历史或流水线日志。
• 自动化环境应使用受保护的密钥变量注入凭证。
• 请从可信发布渠道下载工具，并在使用前校验文件完整性。
• 建议保留未签名的原始 JAR 文件。