Code Signing (JAR) with Primus HSM

This guide explains how to sign Java Archives (JARs) with private keys stored on a Securosys Primus HSM.

You can choose between three options for how to issue a certificate for the code signing key:

1. Self-signed: The code signing certificate is signed by the code signing key itself.
2. Ad-hoc CA: The code signing certificate is signed by an intermediate CA which in turn is signed by a Root CA. Both CAs are created ad-hoc using the Primus Tools, and their keys are also stored on the HSM.
3. Professional CA: The code signing certificate is signed by a separate CA. This can be an existing in-house CA or a public CA (such as DigiCert of SwissSign).

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.

Workflow 1: Self-Signed

In this flow, the code signing certificate is signed by the code signing key itself. This is useful for development and basic testing.

Create a signing key using KeytoolX. This will automatically create a self-signed certificate using the same alias.

# EC P-256 key pair
java -jar primus-tools.jar KeytoolX $HSM \
    -genkeypair \
    -alias codesign-key \
    -keyalg EC -groupname P-256 \
    -sigalg SHA256withECDSA \
    -dname "CN=My Code Signing,OU=IT,O=My Organisation,C=CH" \
    -validity 730

Then export the certificate:

java -jar primus-tools.jar KeytoolX $HSM \
    -exportcert \
    -alias codesign-key \
    -rfc \
    -file codesign-fullchain.pem

Note: we call this codesign-fullchain.pem even though it is only a single certificate. This makes it easier to apply the same signing and verification commands as for certificates generated via flows 2+3.

Continue to signing a JAR.

---

Workflow 2: Ad-hoc CA

In this flow, the code signing certificate is signed by an intermediate CA which in turn is signed by a Root CA. Both CAs are created ad-hoc using the Primus Tools, and their keys are also stored on the HSM.

This workflow is for testing and internal distribution. It is useful when you want more control and separation than using self-signed certificates (flow 1), but you also don't want to run a fully-fledged CA service (flow 3).

Create the Root CA

# Generate RSA 4096-bit key pair
java -jar primus-tools.jar KeytoolX $HSM \
    -genkeypair -alias root-ca-key \
    -keyalg RSA -keysize 4096 -sigalg SHA256withRSA \
    -dname "CN=My Root CA,OU=IT,O=My Organisation,C=CH" \
    -validity 3650

# Re-issue self-signed cert with CA extensions (BasicConstraints)
java -jar primus-tools.jar KeytoolX $HSM \
    -selfcert -alias root-ca-key \
    -sigalg SHA256withRSA \
    -dname "CN=My Root CA,OU=IT,O=My Organisation,C=CH" \
    -validity 3650 \
    -ext bc=ca:true -ext ku=keyCertSign,cRLSign

# Export root certificate
java -jar primus-tools.jar KeytoolX $HSM \
    -exportcert -alias root-ca-key -rfc -file root-ca.crt

Create the Intermediate CA

# Generate key pair
java -jar primus-tools.jar KeytoolX $HSM \
    -genkeypair -alias intermediate-ca-key \
    -keyalg RSA -keysize 4096 -sigalg SHA256withRSA \
    -dname "CN=My Intermediate CA,OU=IT,O=My Organisation,C=CH" \
    -validity 1825

# Generate CSR
java -jar primus-tools.jar KeytoolX $HSM \
    -certreq -alias intermediate-ca-key \
    -file intermediate-ca.csr

# Root CA signs the intermediate certificate
java -jar primus-tools.jar KeytoolX $HSM \
    -gencert -alias root-ca-key \
    -infile intermediate-ca.csr -outfile intermediate-ca.crt \
    -validity 1825 \
    -ext bc=ca:true -ext ku=keyCertSign,cRLSign -rfc

Create the Code-Signing Key

# Generate RSA 4096-bit key pair
java -jar primus-tools.jar KeytoolX $HSM \
    -genkeypair -alias codesign-key \
    -keyalg RSA -keysize 4096 -sigalg SHA256withRSA \
    -dname "CN=My Code Signing,OU=IT,O=My Organisation,C=CH" \
    -validity 730

# Generate CSR
java -jar primus-tools.jar KeytoolX $HSM \
    -certreq -alias codesign-key \
    -file codesign.csr

# Intermediate CA signs the code-signing certificate
java -jar primus-tools.jar KeytoolX $HSM \
    -gencert -alias intermediate-ca-key \
    -infile codesign.csr -outfile codesign.crt \
    -validity 730 \
    -ext eku=codeSigning -ext ku=digitalSignature -rfc

Assemble the Chain

cat codesign.crt intermediate-ca.crt root-ca.crt > codesign-fullchain.pem

The file should contain three certificates in order: end-entity → intermediate → root.

-----BEGIN CERTIFICATE-----
(code-signing certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(intermediate CA certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(root CA certificate)
-----END CERTIFICATE-----

Continue to signing a JAR.

---

Workflow 3: Professional CA

In this flow, the code signing certificate is signed by a separate CA. This can be an existing in-house CA or a public CA. This is useful if:

• You have an existing in-house CA system that you want to use, or if
• The JAR is for public distribution and its signature must be verifiable by end-users using a publicly-trusted CA (such as DigiCert or SwissSign).

Create Key and Generate CSR

# Generate RSA 4096-bit key pair
java -jar primus-tools.jar KeytoolX $HSM \
    -genkeypair -alias codesign-key \
    -keyalg RSA -keysize 4096 -sigalg SHA256withRSA \
    -dname "CN=My Code Signing,OU=IT,O=My Organisation,C=CH" \
    -validity 730

# Generate CSR
java -jar primus-tools.jar KeytoolX $HSM \
    -certreq -alias codesign-key \
    -file codesign.csr

Submit CSR to Your CA

1. Submit codesign.csr to your CA's code-signing certificate portal.
2. Complete the CA's validation process.
3. Download the signed certificate and full chain as a PEM file. Rename it to codesign-fullchain.pem.

The chain PEM should contain certificates in order: end-entity → intermediate(s) → root.

Sign a JAR

You should now have the following:

• A code signing key on Primus HSM with label/alias codesign-key
• A certificate chain in a local file called codesign-fullchain.pem
• A JAR that you want to sign called myapp.jar

Continue with the JarsignerX tutorial to learn how to sign and verify the JAR with this key.

Known Issues

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