KeytoolX

KeytoolX is a Primus Tools utility adapted from Oracle's keytool. It manages key pairs and certificates stored directly on a Securosys Primus HSM - private keys never leave the HSM boundary.

Prerequisites

• kt.jar must be in the same folder as primus-tools.jar.
• An established HSM connection with valid credentials. See HSM Connection and Access Credentials.

HSM connection placeholder

All examples use <HSM> as shorthand.

-host <host> -port <port> -user <user> -password <password> -proxyuser <proxyuser> -proxypassword <proxypassword>

Note: When using Securosys CloudHSM with JarsignerX or KeytoolX, proxy credentials are required. In this case, use the parameters -proxyuser and -proxypassword.

Please note that these parameters differ from the standard Primus tools usage, which uses

-primusproxyuser and -primusproxypassword.

Available Commands

java -jar primus-tools.jar KeytoolX <HSM>

Key and Certificate Management Tool

Commands:
 -certreq            Generates a certificate request
 -changealias        Changes an entry's alias
 -delete             Deletes an entry
 -exportcert         Exports certificate
 -genkeypair         Generates a key pair
 -genseckey          Generates a secret key
 -gencert            Generates certificate from a certificate request
 -importcert         Imports a certificate or a certificate chain
 -importpass         Imports a password
 -importkeystore     Imports one or all entries from another keystore
 -keypasswd          Changes the key password of an entry
 -list               Lists entries in a keystore
 -printcert          Prints the content of a certificate
 -printcertreq       Prints the content of a certificate request
 -printcrl           Prints the content of a CRL file
 -storepasswd        Changes the store password of a keystore
 -keyclone           Clones a key entry
 -selfcert           Generates a self-signed certificate
 -gencrl             Generates CRL
 -identitydb         Imports entries from a JDK 1.1.x-style identity database

For full parameter descriptions, see the Java keytool documentation.

Common Operations

Generate a Key Pair

Creates an RSA or EC key pair on the HSM and registers an initial self-signed certificate entry.

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

# EC P-256 key pair
java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -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

Export a Certificate

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -exportcert \
    -alias root-ca-key \
    -rfc \
    -file root-ca.pem

Generate a Certificate Signing Request (CSR)

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -certreq \
    -alias codesign-key \
    -sigalg SHA256withRSA \
    -file codesign.csr

Sign a CSR (Issue a Certificate)

The signing CA's key must already exist on the HSM. Use -ext to set extensions on the issued certificate.

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -gencert \
    -alias root-ca-key \
    -infile codesign.csr \
    -outfile codesign-signed.pem \
    -validity 730 \
    -ext eku=codeSigning \
    -ext ku=digitalSignature \
    -rfc

-gencert output format

PrimusTools -gencert outputs the signed certificate and the issuer certificate(s), not just the signed certificate like standard keytool. When assembling certificate chains, extract only the first certificate from the output to avoid duplicates:

awk '/-----BEGIN CERTIFICATE-----/{found++}
     found==1{print}
     /-----END CERTIFICATE-----/&&found==1{exit}' codesign-signed.pem > codesign.pem

List Keystore Entries

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -list -v

Delete an Entry

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -delete \
    -alias codesign-key

Import a Certificate Chain

java -jar primus-tools.jar KeytoolX \
    <HSM> \
    -storetype Primus \
    -importcert \
    -alias codesign-key \
    -file chain.pem \
    -noprompt

Known issue - -importcert corrupts Private Key Entry (PrimusTools)

Importing a certificate chain into an existing PrivateKeyEntry via -importcert corrupts the key's password association on the HSM. The entry still appears as PrivateKeyEntry, but any subsequent attempt to use the private key fails with:

WrongKeyPasswordException: status: KeyPasswordMismatch; for key <alias>

Impact: the -importcert [-noprompt] installs the certificate with the additional side effect that the key password is changed to "NONENONE" the key password can be reset by primus-tools.jar RenameKey

Extension Syntax

PrimusTools uses a different extension syntax than standard keytool. Common extensions:

Extension	Syntax
BasicConstraints CA	-ext bc=ca:true
Key Usage (CA)	-ext ku=keyCertSign,cRLSign
Key Usage (signing)	-ext ku=digitalSignature
Extended Key Usage	-ext eku=codeSigning