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

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 回正常に署名する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 連携
に最終更新