sslTrusJarsigner Usage Guide

Prerequisites

Before use, please prepare:

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

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

Download

Download the latest release package via 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 Runtime Environment

Run the following commands to confirm Java, jarsigner, and tool files 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 provide a dedicated service address, you also need to configure:

Linux and macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

If a dedicated service address is not provided, please do not set this variable.

Signature

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

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 first confirm that JAVA_HOME points to a complete JDK 8.

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 timestamps are not needed, you can remove -tsa and the address that follows it.

Signing XML (XMLDSig)

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

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#, with the Signature node written as the last child node of the root node in the output file. The current signature profile is fixed as follows:

Item	Fixed Value
Signature Type	Enveloped signature
Signature Scope	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 leaf certificate by default

Callers do not need to compute the digest or construct the SignatureValue themselves. The tool will populate the KeyInfo/X509Data using the leaf certificate of the remote certificate and write the final SignatureValue into the XML.

Including the Full Certificate Chain

Default output includes only the leaf certificate to reduce XML size and stay consistent with common TIMS/1E files. If the recipient requires the intermediate certificate chain to be included in the XML, append --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; it 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 is used.

Input and Usage Limitations

• 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 signing to avoid producing files with an unverifiable signature scope.
• 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 XML external entities and external DTD loading, so XML relying on external entity expansion is not accepted.
• Do not modify the XML structure, text, attributes, or namespaces after signing; any such changes will cause XMLDSig verification to fail. Always retain the original input file and write the signed result to a new output file.

Generating a 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 is used only for signature verification and cannot be used for performing signatures.

Verify the 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

Error: Missing Access Key, Access Secret, or certificate number

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.

Error: Illegal option: -providerPath

JDK 8 is currently in use. Please use the JDK 8 signing command described in this article instead.

Error: Unable 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 JDK 8 JAVA_HOME points to a full JDK installation.

Error: Certificate or alias not found

Please check:

• Whether the certificate number is correct.
• Whether the certificate number at the end of the command matches the environment variable.
• Whether the current credentials are authorized to use the certificate.

Signing request failed

Please check:

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

If the issue persists, please retain the complete error message and contact technical support. Before submitting the error information, please delete or redact the credentials.

Timestamp failed

Please confirm that the current network can access the timestamp address in the command. If business requirements permit, you can temporarily remove -tsa and the address that follows it, then run the signing command again to isolate the issue.

Security Considerations

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