跳至主要内容

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 TransformEnveloped Signature Transform
CanonicalizationInclusive Canonical XML 1.0
摘要演算法SHA-256
簽名演算法RSA-SHA256
KeyInfoX509Data，預設包含葉子憑證

呼叫方無需自行計算摘要或建構 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 檔案。
最後於 更新