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

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 と一致している必要があります。
  • 元のJARファイルが上書きされるのを防ぐため、常に -signedjar を使用して新しいファイルを生成することを推奨します。
  • タイムスタンプが不要な場合は、-tsa とその後ろのアドレスを削除できます。

XMLへの署名（XMLDSig）​

TIMS/1E XMLは sign-xml コマンドを使用してXML Digital Signature（XMLDSig）のエンベロープド署名を生成します。秘密鍵は引き続きリモート署名サービス内にのみ保持されます。ツールはローカルで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 ノードをルートノードの最後の子ノードとして出力ファイルに書き込みます。現在の署名プロファイルは以下のように固定されています：

項目固定値
署名タイプEnveloped signature
署名範囲XMLドキュメント全体、Reference URI=""
Reference TransformEnveloped Signature Transform
CanonicalizationInclusive Canonical XML 1.0
ダイジェストアルゴリズムSHA-256
署名アルゴリズムRSA-SHA256
KeyInfoX509Data、デフォルトでリーフ証明書を含む

呼び出し元がダイジェストを計算したり SignatureValue を構成したりする必要はありません。ツールがリモート証明書のリーフ証明書を使用して KeyInfo/X509Data を埋め、最終的な SignatureValue をXMLに書き込みます。

完全な証明書チェーンを含める​

デフォルトではエンドエンティティ証明書のみが出力されます。これにより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プロファイルはサポートしていません。
  • ツールは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 ファイルを保管することを推奨します。
に最終更新