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. This library is required for the KeytoolX and JarsignerX subcommands to work.
• An established HSM connection with valid credentials. See HSM Connection and Access Credentials.

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.

Command Overview

$ java -jar primus-tools.jar KeytoolX

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 creates a corresponding self-signed certificate.

# 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,L=Zurich,ST=Zurich,C=CH" \
    -validity 730

# 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

Export a Certificate

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

The -rfc option sets the export format to PEM. Otherwise, DER is used.

Generate a Self-Signed Certificate

The follow command generates a self-signed certificate for the key <alias> and writes it to the HSM with the same name. To export the certificate to a local file, use the -exportcert subcommand.

java -jar primus-tools.jar KeytoolX $HSM -selfcert -alias codesign-key

Generate a Certificate Signing Request (CSR)

java -jar primus-tools.jar KeytoolX $HSM \
    -certreq \
    -alias codesign-key \
    -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 \
    -gencert \
    -alias root-ca-key \
    -infile codesign.csr \
    -outfile codesign-chain.pem \
    -validity 730 \
    -ext eku=codeSigning \
    -ext ku=digitalSignature \
    -rfc

tip

This also supports the creation of self-signed certificates. Simply set the -alias to the key itself.

-gencert output format

If the CA signing key is a separate key, Primus Tools outputs the signed certificate and the issuer certificate(s). This is different from the standard keytool, which outputs only the signer certificate.

To extract the leaf certificate:

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

List Keystore Entries

java -jar primus-tools.jar KeytoolX $HSM -list -v

Delete an Entry

java -jar primus-tools.jar KeytoolX $HSM -delete -alias codesign-key

Import a Certificate Chain

java -jar primus-tools.jar KeytoolX $HSM \
    -importcert \
    -alias codesign-key \
    -file chain.pem \
    -noprompt

Known issue : -importcert corrupts Private Key Entry

In Primus Tools v2.4.4 and earlier, 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:

[exc] java.security.UnrecoverableKeyException: key <alias>: com.securosys.primus.jce.spi0.WrongKeyPasswordException: status: KeyPasswordMismatch; for key <alias>
jarsigner: key associated with <alias> not a private key
Exception in thread "main" java.lang.reflect.InvocationTargetException: java.lang.reflect.InvocationTargetException: java.lang.Exception: key associated with <alias> not a private key

The reason is that the -importcert installs the certificate with the additional side effect that the key password is changed to "NONENONE".

To fix this, use the RenameKey subcommand to remove the password:

java -jar primus-tools.jar RenameKey $HSM -keyname alias -newname alias-tmp -keypassword NONENONE
java -jar primus-tools.jar RenameKey $HSM -keyname alias-tmp -newname alias

Caution: This is a normal subcommand, not a KeytoolX subcommand. Therefore, if using CloudHSM, replace -proxyuser with -primusproxyuser and replace -proxypassword with -primusproxypassword.

This bug is fixed in Primus Tools v2.5.3.

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