sslTrusJarsigner User Guide

Prerequisites

Before using, please prepare:

• JDK 8 or a later version.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret, and certificate ID.
• The JAR file or TIMS/1E XML file to be signed.

Please replace <version>, credentials, certificate ID, and file paths in this document with actual values.

Download

Download the latest release package from the following page:

Download latest package

After downloading and extracting the ZIP file, you will obtain:

• sslTrusJarsigner-<version>.jar
• SHA-256 checksum file

It is recommended to verify the integrity of the JAR file against the checksum file before use.

Check the Runtime Environment

Run the following command to confirm that Java, jarsigner, and the tool file are available:

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

View help information:

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

Configure credentials

Linux and 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"

If the service personnel provides a dedicated service address, you also need to set:

Linux and macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Do not set this variable if no dedicated service address is provided.

Signature

The following example signs app-unsigned.jar and saves the result as app-signed.jar. Use fixed parameters exactly as shown in the example.

JDK 9 or later

Linux and 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

Please confirm that JAVA_HOME points to the full JDK 8 installation.

Linux and 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"

Note

• The certificate number at the end of the command must match SSLTRUS_JARSIGNER_CERT_CODE.
• It is recommended to always use -signedjar to generate a new file to avoid overwriting the original JAR.
• If you do not need a timestamp, you can remove -tsa and the address that follows it.

Signing XML (XMLDSig)

TIMS/1E XML uses the sign-xml command to generate an XML Digital Signature (XMLDSig) enveloped signature. The private key remains exclusively in the remote signing service; the tool generates the digest and signature structure required for XMLDSig locally, and the remote service then completes the RSA signature.

For Linux and 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"

Signature Format

The generated signature uses the XMLDSig standard namespace http://www.w3.org/2000/09/xmldsig#, and the Signature node is written to the output file as the last child of the root node. The current signature profile is fixed as follows:

Item	Fixed value
Signature type	Enveloped signature
Signature scope	The entire XML document, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Digest algorithm	SHA-256
Signature algorithm	RSA-SHA256
KeyInfo	X509Data, includes the leaf certificate by default

The caller does not need to calculate the digest or construct SignatureValue on their own. The tool will populate KeyInfo/X509Data with the leaf certificate of the remote certificate, and write the final SignatureValue into the XML.

Include the full certificate chain

By default, only leaf certificates are included in the output to reduce the XML file size and maintain consistency with common TIMS/1E files. If the recipient requires the intermediate certificate chain to be carried in the XML, add --full-chain at the end of the command:

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

--full-chain only affects the certificate list in KeyInfo/X509Data, and does not change the signature scope, digest algorithm, or signature algorithm. This option can be placed before or after the certificate number; if no certificate number is provided, SSLTRUS_JARSIGNER_CERT_CODE will be used.

Input and Usage Restrictions

• The input must be well-formed XML and contain a root node.
• The input file must not already contain an XMLDSig Signature node; the tool will reject duplicate signatures to avoid generating files where the signature scope cannot be confirmed.
• Currently, only enveloped signatures for the entire document are supported; detached signatures, signing by element ID, or custom XMLDSig profiles are not supported.
• The tool disables loading of XML external entities and external DTDs, so XML that relies on external entity expansion will not be accepted.
• After signing is complete, do not modify the structure, text, attributes, or namespaces of the XML; any such changes will cause XMLDSig verification to fail. You should always retain the original input file and write the signing result to a new output file.

Generate Verification File

After signing, you can generate the JKS file required for verification:

Linux and 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 It is only used for signature verification and cannot be used to perform signing.

Verify Signature

Use the generated verify.jks to verify the signed JAR:

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

If you only need to view the signature information of the JAR:

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

FAQ

Prompt indicating missing Access Key, Access Secret or certificate ID

Please confirm that the following environment variables have been set in the current terminal:

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

After setting the environment variables, you need to execute the signing command in the same terminal window.

Prompt indicating Invalid option: -providerPath

You are currently using JDK 8. Please use the JDK 8 signing command provided in this document instead.

Prompt indicating failure to load com.racent.codesign.SSLTrusProvider

Please check:

• Whether the sslTrusJarsigner-<version>.jar path is correct.
• Whether the version number in the file name matches the actual file.
• Whether the JAVA_HOME of JDK 8 points to the full JDK.

Prompt indicating certificate or alias not found

Please check:

• Whether the certificate ID is correct.
• Whether the certificate ID at the end of the command matches the one in the environment variable.
• Whether the current credentials have permission to use the certificate.

Signing request failed

Please check:

• Network connection, proxy and firewall settings.
• Whether the credentials and certificate ID are correct.
• Whether the dedicated service address is configured according to the content provided by the service personnel.

If the issue still cannot be resolved, please retain the complete error message and contact technical support. Before submitting the error message, please delete or mask the credentials.

Timestamp failure

Please confirm that the current network can access the timestamp address in the command. If permitted by your business, you can temporarily delete -tsa and the address following it, then execute the signing again to locate the problem.

Security Notes

• Do not store real Access Secrets in source code, documents, shared scripts or images.
• Do not share command lines, terminal history or pipeline logs that contain credentials with others.
• Automated environments should inject credentials using protected secret variables.
• Please download tools from trusted release channels, and verify file integrity before use.
• It is recommended to retain the original unsigned JAR file.