メインコンテンツまでスキップ

Java 連携

sslTrus は sslTrusJarsigner Java Provider を提供しており、JDK 付属の jarsigner ツールと連携して、リモートコード署名サービスを通じて Java JAR ファイルの署名を完了できます。

署名プロセスにおいて、コード署名秘密鍵は常にクラウド HSM 内に保存されます。ローカルでは署名対象データと署名構造の生成を担当し、sslTrusJarsigner Provider を通じてリモートサービスを呼び出して秘密鍵による署名を完了します。

JAR 署名に加えて、sslTrusJarsigner は XMLDSig 署名機能も提供しており、XML デジタル署名のシナリオで使用できます。

事前準備​

使用前に以下を準備してください：

  • JDK 8 以降。
  • sslTrusJarsigner-<version>.jar。
  • Access Key。
  • Access Secret。
  • 証明書番号（Cert Code）。
  • 署名対象の JAR ファイルまたは XML ファイル。

本文の例にある <version>、アクセス資格情報、証明書番号、ファイルパスはすべて実際の値に置き換える必要があります。

sslTrusJarsigner のダウンロード​

sslTrusJarsigner リリースページ から最新のリリースパッケージをダウンロードして解凍します。

リリースパッケージには以下が含まれます：

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

使用前には、SHA-256チェックサムによりファイル sslTrusJarsigner-<version>.jar の整合性を検証することをお勧めします。

実行環境の確認​

まず、JavaおよびJDKに付属する jarsigner が正常に使用できることを確認します。

java -version
jarsigner -help

sslTrusJarsignerのバージョンを確認します。

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

ヘルプを表示：

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

jarsigner コマンドが存在しない場合は、現在インストールされているのが Java Runtime のみを含む実行環境ではなく、完全な JDK であることを確認してください。

アクセス資格情報の設定​

sslTrusJarsigner は環境変数からリモートコード署名サービスのアクセス資格情報と証明書番号を読み取ります。

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"

専用サービスアドレスが提供されている場合は、SSLTRUS_JARSIGNER_URL も設定する必要があります。

LinuxおよびmacOS：

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

サービス専用アドレスが提供されていない場合は、この変数を設定する必要はありません。

Access Secret は機密性の高い認証情報であるため、ソースコード、公開設定ファイル、ビルドログに書き込まないでください。自動化環境では、CI/CD Secret またはその他の認証情報管理メカニズムを通じて注入することを推奨します。

JAR 署名​

sslTrusJarsigner は、Java Security Provider メカニズムを通じて標準の jarsigner ツールと統合されます。

次の例では、以下を行います。

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​

JDK 8 で Provider をロードする方法は、JDK 9 以降とは異なります。

まず確認します：

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。
  • 示例使用 SHA256withRSA 完成代码签名。
  • 不需要时间戳时，可以删除 -tsa 及其后的时间戳地址。

时间戳​

建议对正式发布的 JAR 签名添加可信时间戳。

示例中使用：

http://timestamp.sectigo.com

対応パラメータ：

-tsa http://timestamp.sectigo.com

タイムスタンプは、署名が行われた時刻を証明するために使用され、元の JAR ファイルがタイムスタンプサーバーにアップロードされることはありません。

他のタイムスタンプサービスを使用する必要がある場合は、-tsa の後のアドレスを、実際の署名ポリシーに適合する TSA アドレスに置き換えることができます。

さまざまなタイムスタンプサービスと本番環境での選択については、参考資料 を参照してください。

XML 署名​

sslTrusJarsigner は XML デジタル署名機能も提供します。

XML ファイルは、sign-xml コマンドを使用して XMLDSig Enveloped Signature を生成できます。

署名プロセスでは、ローカル側で 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"

デフォルトで出力される KeyInfo にはリーフ証明書のみが含まれます。受信側が XML に完全な証明書チェーンを含めることを要求する場合は、コマンドの末尾に --full-chain パラメータを追加できます。

実行完了後：

input.xml

元のXMLファイルに対して、

signed.xml

XML デジタル署名を含む出力ファイル用です。

コード署名の秘密鍵は XML ファイルに書き込まれず、ローカルコンピューターにも保存されません。

検証ファイルの生成​

署名完了後、署名検証用の 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

このファイルは署名検証専用であり、コード署名の実行には使用できません。

コード署名の秘密鍵は引き続きリモートHSMに保存され、verify.jksに書き込まれることはありません。

JAR署名の検証​

生成されたverify.jksを使用して署名を検証します。

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

JAR 内の既存の署名情報のみを確認する必要がある場合は、以下を実行します。

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

署名の検証は既存の署名をチェックするだけであり、リモートの秘密鍵を再度呼び出して署名を実行することはありません。

署名回数​

Jarsigner の署名回数は、実際に正常に完了したリモート署名操作の回数に基づいて計算されます。

通常は以下のとおりです。

操作署名回数
1 つの JAR に正常に署名した場合1 回
3 つの JAR にそれぞれ署名した場合3 回
同じ JAR に対してもう一度署名を実行した場合さらに 1 回追加
jarsigner -verify 署名の検証0 回
verify.jks の生成0 回

したがって、署名回数は主に、実際に実行された正常な署名操作の回数によって決まり、Java プロジェクトのソースコードファイル数には依存しません。

詳細なルールについては 参考资料 をご参照ください。

よくある質問​

Access Key、Access Secret、または証明書番号が不足している場合​

現在のターミナルで以下が設定されていることを確認してください。

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

環境変数を設定した後は、同じターミナルセッション内で署名コマンドを実行する必要があります。

Invalid option: -providerPath​

もし以下のように表示された場合：

Invalid option: -providerPath

通常は、現在JDK 8を使用していることを示します。

JDK 8では、JDK 9以降のバージョンの例にある-providerPathパラメータは使用しません。本記事で提供されているJDK 8用のコマンドを使用してください。

SSLTrusProviderを読み込めません​

読み込めないというメッセージが表示された場合：

com.racent.codesign.SSLTrusProvider

请检查：

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

找不到证书或 alias​

请检查：

  • 证书编号是否正确。
  • 命令最后指定的证书编号是否与 SSLTRUS_JARSIGNER_CERT_CODE 一致。
  • 当前 Access Key 和 Access Secret 是否具有该证书的使用权限。

远程签名请求失败​

请检查：

  • 当前网络是否能够访问远程代码签名服务。
  • 代理、防火墙和 DNS 配置是否正常。
  • Access Key 和 Access Secret 是否正确。
  • 证书编号是否正确。
  • 如果使用专用服务地址，SSLTRUS_JARSIGNER_URL 是否按照实际交付信息配置。

排查问题时可以保留完整错误信息，但在提交日志或错误截图前，应删除或脱敏 Access Secret 等敏感凭证。

时间戳失败​

确认当前网络能够访问 -tsa 指定的时间戳服务器。

如果业务允许，可以暂时移除：

-tsa <URL>

署名を再度実行し、問題がリモートコード署名とタイムスタンプ要求のどちらの段階で発生しているかを判断します。

セキュリティに関する注意​

Java 統合プロセスでは以下の点に注意が必要です。

  • Access Secret は機密認証情報として保存してください。
  • アクセス認証情報を Git リポジトリにコミットしないでください。
  • 完全な Access Secret をログに出力しないでください。
  • verify.jks は検証専用であり、リモート署名に使用できる秘密鍵は含まれていません。
  • ローカルの sslTrusJarsigner Provider はコード署名用秘密鍵を保存しません。
  • 秘密鍵による署名操作は常にリモートコード署名サービスによって実行されます。
  • 自動化環境では、CI/CD Secret または専用の認証情報管理システムを使用してアクセス認証情報を注入することを推奨します。

関連する統合方法​

署名対象が Java JAR または XML ファイルではない場合、実際のシナリオに応じて以下の他の統合方法を選択できます。

シナリオ統合方法
コマンドラインで EXE、DLL、MSI などのファイルを直接署名する場合クライアントツール
Microsoft SignTool、Visual Studio などの Windows ツールWindows Provider
GitHub Actions、Electron Builder などの自動ビルドCI/CD とビルドツール
リモート署名クライアントを独自に開発する場合API 統合
に最終更新