JarsignerX

JarsignerX is a Primus Tools utility adapted from Oracle's jarsigner. It signs and verifies Java Archives (JARs) using private keys stored on a Securosys Primus HSM - the private keys never leave the HSM boundary.

Prerequisites

• kt.jar must be in the same folder as primus-tools.jar. This library is required for the JarsignerX and KeytoolX subcommands to work.
• An established HSM connection with valid credentials. See HSM Connection and Access Credentials.
• A key pair already provisioned on the HSM. For example, you can generate one with KeytoolX.

HSM connection placeholder

All examples use $HSM as shorthand for the following:

HSM="-host <host> -port <port> -user <user> -password <password> -proxyuser <proxyuser> -proxypassword <proxypassword>"

When using Securosys CloudHSM the proxy credentials are required. For on-premise HSMs, leave out the -proxyuser and -proxypassword arguments.

Please note that the naming differs from the standard Primus Tools, which use -primusproxyuser and -primusproxypassword.

Java module access

JarsignerX requires additional JVM flags on Java 17+:

--add-opens=java.base/javax.security.auth.x500=ALL-UNNAMED
--add-opens=java.base/sun.security.x509=ALL-UNNAMED

These flags must appear before the -jar argument. For example: java --add-opens=... -jar primus-tools.jar

Sign a JAR

java \
    --add-opens=java.base/javax.security.auth.x500=ALL-UNNAMED \
    --add-opens=java.base/sun.security.x509=ALL-UNNAMED \
    -jar primus-tools.jar JarsignerX $HSM \
    -tsa http://tsa.swisssign.net \
    -tsa http://timestamp.digicert.com \
    -digestalg SHA-256 \
    -certchain chain.pem \
    myapp.jar codesign-key

Output on success:

jar signed.

Parameter	Description
-tsa <url>	Time Stamping Authority URL (repeatable for fallback)
-digestalg <alg>	Digest algorithm (e.g. SHA-256)
-certchain <file>	Certificate chain to embed in the JAR, in standard order (leaf → intermediate → root)
<jar>	The JAR file to sign (modified in-place)
<alias>	Label of the HSM key to use for signing

Verify a Signed JAR

Online Verification (via HSM)

You can use JarsignerX to verify the JAR signature. This will look up the certificates on the HSM.

java -jar primus-tools.jar JarsignerX $HSM -verify myapp.jar

Output on success:

jar verified.

Offline Verification (no HSM needed)

Signed JARs can be verified without HSM access using the normal jarsigner.

If the JAR contains a certificate chain that is rooted in a publicly trusted CA, verify as follows:

jarsigner -verify myapp.jar

To verify against a custom CA hierarchy, build a custom truststore, import the entire certificate chain, and verify against the truststore.

# 1. Extract the individual certificates from the chain
awk 'BEGIN{n=0} /-----BEGIN CERTIFICATE-----/{n++} {print > "cert-" n ".pem"}' fullchain.pem

# 2. Create a temporary JKS truststore and import the certificates
keytool -importcert -keystore truststore.jks -storepass changeme -noprompt -alias leaf -file cert-1.pem
keytool -importcert -keystore truststore.jks -storepass changeme -noprompt -alias root-ca -file cert-3.pem
keytool -importcert -keystore truststore.jks -storepass changeme -noprompt -alias intermediate-ca -file cert-2.pem

# 3. Verify
jarsigner -verify -keystore truststore.jks -storepass changeme myapp.jar

info

Plain jarsigner -verify checks only signature integrity. Add -strict to treat certificate-chain warnings (e.g., untrusted root, missing timestamp) as errors.

More Information

For more information about the underlying jarsigner utility, see the Java jarsigner documentation.

Known Issues

• KeytoolX may corrupt Private Key Entries. For more details and a workaround, see the KeytoolX documentation.