How to Configure KeyLocker for JarSigner using the DigiCert KSP Library?

Digitally signing Java applications improves authenticity, integrity, and trust. DigiCert KeyLocker allows you to sign .jar files securely using keys stored in DigiCert’s cloud-based Hardware Security Modules (HSMs) and the DigiCert KSP Library. This guide explains how to establish your environment and use JarSigner to sign Java applications from KeyLocker.

What Is DigiCert KeyLocker?

DigiCert KeyLocker is a cloud-based key management system that keeps a private key completely secure in DigiCert’s FIPS-compliant HSMs in the cloud, allowing developers to sign software without exposing the private key on local machines.

When integrated with JarSigner, Java developers can utilize their development environment to securely sign code with a high degree of policy control from KeyLocker.

Prerequisites

Before configuring KeyLocker for JarSigner, please ensure you have the following components and environment set up. Each of these is necessary and plays a role in establishing a contracted, secure, engaging signing environment.

DigiCert ONE Account

You must have access to a valid DigiCert ONE account that has KeyLocker enabled. This single and secure management tool will allow you to create and manage your signing keys, certificates, and access, more importantly, from one tool. The account will be the primary location to create the API Key and manage the signer’s privileges for code signing.

Recommended: How to Purchase a DigiCert​​​​ KeyLocker Certificate?

KeyLocker API Key

A KeyLocker API key is required for authenticating your signing device with DigiCert’s cloud, which enables the local DigiCert KeyLocker Tools to communicate with the KeyLocker service. The API key can be created from your DigiCert ONE dashboard under the KeyLocker configuration area.

Client Certificate (.p12 File)

The client certificate file (.p12) provides secure certificate-based authentication for your local system and KeyLocker. The client certificate is downloaded from your DigiCert ONE account and contains encrypted credentials that confirm your identity before allowing access to the private keys stored within DigiCert’s HSMs.

Keypair Alias

Each code signing certificate in KeyLocker is assigned a unique keypair alias. This alias connects your local configuration to the specific code-signing certificate you are using. The keypair alias can be found in your DigiCert ONE account under the KeyLocker certificate management area. The keypair alias needs to be correctly referenced in the smctl and jarsigner commands.

Java Development Kit (JDK)

The Java Development Kit (JDK) is needed because it has the JarSigner utility that is used for signing and verifying .jar files. If you do not have the JDK installed, your signing commands will fail to run.

Ensure that you have the JDK installed properly and that the bin directory has been added to the system’s PATH variable so jarsigner.exe can run globally.

DigiCert KeyLocker Tools

Install DigiCert KeyLocker Tools package on your Windows Machine. The Tool set contains the smctl command line utility, which you will need for saving credentials, syncing certificates, and registering the Key Storage Provider (KSP).

Make note of the installed directory path, as you will need it to set the environment variables later in the setup process.

Steps to Configure KeyLocker for JarSigner using the DigiCert KSP Library

Step 1: Set Environment Variables  

First, you will need to set the environment variables of the KeyLocker Tools and JarSigner, so your system knows how to find these tools. 

• Open the Start Menu, search for “Environment Variables“, and select “Edit the system environment variables“. 
• In the System Properties window, click ‘Environment Variables‘.
• Under ‘System Variables‘, highlight ‘Path’, then click Edit. 
• Click ‘New‘, and paste the full directory where DigiCert KeyLocker Tools is installed: 

C:\Program Files\DigiCert\DigiCert KeyLocker Tools\

• Add another path where the JDK’s jarsigner.exe is located (e.g., C:\Program Files\Java\jdk-21\bin\).
• Click OK to save the changes.

Add KeyLocker Connection Variables

Now, create the following system variables:

Variable Name	Variable Value	Description
SM_HOST	https://clientauth.one.digicert.com	URL for KeyLocker authentication
SM_CLIENT_CERT_FILE	C:\clientcertpath\Certificate_pkcs12.p12	Path to your client certificate

After adding these, click OK to save and exit.

Step 2: Set KeyLocker Credentials and Register KSP Library

• Open Command Prompt as an Administrator.
• Save your credentials with the command:

smctl credentials save <API token> <client certificate password>

If successful, you’ll see:

• Credentials saved to OS store

Confirm the DigiCert KSP library is installed:

smctl windows ksp list

If not registered, run:

smctl windows ksp register

This command registers the DigiCert Key Storage Provider on your system.

Step 3: Synchronize and Verify Certificate Configuration

Now, synchronize your certificate with KeyLocker and verify your setup.

Run the following to sync your certificate:

smctl windows certsync --keypair-alias=<your_keypair_alias>

You’ll see output similar to:

Syncing certificate for alias: myKeyAlias, ID: 123456, SHA1 Fingerprint: <fingerprint>

Verify the configuration with a health check:

smctl healthcheck

Confirm that the following information appears correctly:

• Username (DigiCert ONE user)
• Host: https://clientauth.one.digicert.com
• API key
• Client certificate path and password

If JarSigner is successfully mapped, it will be listed in the health check output.

Step 4: Sign JAR Files with JarSigner

Once your setup is verified, you can sign .jar files using the DigiCert KeyLocker certificate.

Command Syntax:

jarsigner -keystore NONE -storetype Windows-My -signedjar <signed_file.jar> -sigalg SHA256withRSA -digestalg SHA-256 <unsigned_file.jar> <keypair_alias> -tsa http://timestamp.digicert.com

Example:

jarsigner -keystore NONE -storetype Windows-My -signedjar C:\signed\MyAppSigned.jar -sigalg SHA256withRSA -digestalg SHA-256 C:\unsigned\MyApp.jar mykeylockercert -tsa http://timestamp.digicert.com

If it’s successful, a confirmation message letting you know the JAR was signed will show up.

Step 5: Verify the Signed File

To ensure the JAR was signed properly, run:

jarsigner -verify C:\signed\MyAppSigned.jar

If verification succeeds, you’ll see:

jar verified.

Also Read: How to Configure DigiCert KeyLocker on Windows?

Conclusion

Configuring KeyLocker for JarSigner with the DigiCert KSP Library enables the developer to sign Java applications with an enterprise level of trust. The solution is based on using private keys secured in DigiCert Cloud HSM, and provides a fully automated signature without any disruptions using standard Java tools.

The procedure outlined in this document assures that every .jar will be “real” or “verified”, and with a level of trust, while keeping pace with the security best practices of today’s software security.

Search