Configuring YubiHSM 2 for Java Code Signing

The following procedure will explain Configure YubiHSM 2 for Java code signing.

Before moving on to the procedure, let’s look at the terms “HSM” and “YubiHSM 2”  which will be covered in this article.

What is HSM?

The HSM (Hardware Security Module) is a physical device that manages private keys and executes cryptographic operations. The basic concept is that the private keys never leave the hardware, therefore if a system is infiltrated or data is taken, there is no way to decode the data without having access to the HSM. Despite the fact that HSMs may be used for a variety of cryptographic operations.

YubiHSM 2

The YubiHSM enables organizations of all sizes to improve cryptographic key security across the entire lifecycle, minimize risk, and guarantee compliance with regulatory requirements.

With the YubiHSM SDK 2.0 now being made available as open source, organizations can swiftly add support for the secure HSM to a wide range of systems and platforms for both present as well as prospective use cases where robust security is more essential than ever before.

High Quality and Long-Lasting:

It is crush resistant, has no moving parts, and is certified IP68 (water and dirt resistant).

Rapid Integration, Simple Management:

Open-source libraries are used to support custom applications. YubiHSM KSP, PKCS#11, and native libraries are used as interfaces.

Form factor – “Nano” for Discrete in-port Retention:

For standard 1.0, 2.0, and 3.0 ports, use a USB-A connection. designed to use less electricity.

Securely Created:

Yubico assures the highest levels of security from component sourcing to manufacturing. Made in Sweden and the USA.

Prerequisites:

• SDKs and Operating Systems

• Use a device/system/PC that is running a Linux distribution or Windows 10.

• Connect the YubiHSM 2 device to one of the computer’s USB ports.

• Install the tools and SDKs listed below:
  
  YubiHSM SDK (including YubiHSM-Setup, YubiHSM-Shell, and YubiHSM-Connector)
  
  OpenSSL
  
  Java JDK (including KeyTool and JarSigner)

Configuration of YubiHSM 2

Begin the YubiHSM-Connector by running it from a command line or as a service.

To ensure that the YubiHSM 2 is accessible start the YubiHSM-Shell in a new command prompt and carry out the following steps:

yubihsm-shell
Using default connector URL: http://125.0.0.1:12345
yubihsm> connect.
Session keepalive set up to run every 15 seconds
yubihsm> session open 1 password
Created session 0
yubihsm> list objects 0
Found 1 object(s)
id: 0x0001, type: authentication-key, sequence: 0

YubiHSM 2 PKCS #11 Configuration file

The Public-Key Cryptography Standard (PKCS#11) specifies a platform-independent API for interacting with cryptographic tokens.

Generate the yubihsm_pkcs11.conf configuration file and place it in the same folder as the yubihsm_pkcs11 module (usually, /usr/lib64/pkcs11/ on Linux and

C:Program Files/Yubico/YubiHSM Shellbin/pkcs11 on Windows).

Following the guidelines on the YubiHSM 2 PKCS #11 website configure the yubihsm_pkcs11.conf.

Copying and pasting the YubiHSM 2 PKCS #11 configuration example into the yubihsm_pkcs11.conf file is sufficient if the YubiHSM-Connector is operating on the same computer.

Sun JCE PKCS #11 Provider Configuration file for YubiHSM 2

The YubiHSM 2 PKCS #11 module must be configured to work with the Sun JCE PKCS #11 Provider.

Create the configuration file sun_yubihsm2_pkcs11.conf and fill it with the following information:

name = yubihsm-pkcs11
library = C:\Program Files\Yubico\YubiHSM Shell\bin\pkcs11\yubihsm_pkcs11.dll
attributes(*, CKO_PRIVATE_KEY, CKK_RSA) = {
  CKA_SIGN=true
}

Environment Variables

In the environment variables for Windows and Linux, the following path to the YubiHSM PKCS #11 configuration file must be set:

YUBIHSM_PKCS11_CONF = <YubiHSM PKCS11
folder>/yubihsm_pkcs11.conf

Next on Windows, it is also suggested to add the subsequent folder paths to the environment variable PATH:

‘C:\Program Files\Yubico\YubiHSM Shell\bin'
'C:\Program Files\OpenSSL-Win64\bin'
'C:\Program Files\Java\jdk-<version>\bin'

Java Keystore

Several pre-configured trustworthy CA-certificates are contained in the Java keystore. Verification will be done between the trusted CA-certificates in the Java keystore and the Java signing certificate in the YubiHSM 2.

Because of this, it is advised to make sure the CA certificate(s) that were used to generate the Java signing certificates are still available in the Java keystore. The following command can be used to check this:

keytool -list -cacerts -storepass <password to Java keystore>

Add the CA-certificate(s) as trusted certificate(s) to the Java keystore if it isn’t already available. This could be accomplished using the Java tool KeyTool.

To update the Java keystore, use a terminal in elevated mode (“Run as administrator” on Windows or “sudo” on Linux), and then carry out the following commands to import and validate the CA-certificate(s):

keytool -import -noprompt -cacerts -storepass <password to Java keystore> -alias <alias of the CA-cert> -file <path to the CA-certificate file>

keytool -list -cacerts -storepass <password to Java keystore> -alias <alias of the CA-cert>

Windows PowerShell Script for Creating Keys and Certificates

• To create an RSA keypair and enroll for an X.509 certificate on Windows, run the PowerShell script YubiHSM_Cert_Enroll.ps1 in the Scripts folder.
• YubiHSM-Shell can be used in command-line mode.
• Only for test and demonstration motives, OpenSSL is utilized as the basic CA. However, a proper CA that signs the CSR into an X.509 certificate should be used in place of the OpenSSL CA for actual deployments.

Parameters

Check a few of the parameters in the PowerShell script.

Algorithm – Signature algorithm (RSA2048 by default)

CreateCSR – Generate keys and export CSR and then exit.

KeyID – KeyID that will be used to hold the RSA keypair by default (0x0002).

KeyName – The key or certificate’s label, often known as the Java Alias [Default: MyKey1]

LogFile – Path to the log file WorkDirectory/YubiHSM_PKCS11_Enroll.log by default

WorkDirectory – The working directory in which the script is run [$PSScriptRoot by default]

CAPrivateKeyPW – OpenSSL keystore password (for testing purposes)

Domain– In the YubiHSM 2, the domain is set to [Default: 1].

AuthKeyID – The key ID for the YubiHSM 2 authentication key [Default: 0x0001]

The PowerShell script has predefined settings for all the parameters. The PowerShell script’s parameters can be modified, or they can be utilized as input variables when the script is executing.

Key and Certificate Generation using a Linux Bash Script

Linux users may produce an RSA keypair and enroll for an X.509 certificate to a YubiHSM 2 by executing the Bash script YubiHSM_Cert_Enroll.sh in the Scripts folder.

In command-line mode, YubiHSM-Shell will be used.

Only for test and demo purposes, OpenSSL serves as a basic CA. However, for actual deployments, the OpenSSL CA should be substituted with a legitimate CA that signs the CSR into an X.509 certificate.

Parameters

Check a few of the parameters in the Bash script.

The Bash script has a default setting for all the parameters. The Bash script’s parameters can be modified, or they can be utilized as input variables when the script is executing.

• a, –algorithm – Signature algorithm [RSA2048 by default] 
• -k, –keyid – KeyID to use to store the RSA keypair [Default: 0x0002]
• -f, –pkcs11configfile – Java JCE PKCS #11 configuration file [Default: ./sun_yubihsm2_pkcs11.conf]
• -o, –dname – X.500 Distinguished Name to be used as subject fields [Default: ]
• -t, –logfile – Log file path [Default: ./YubiHSM_PKCS11_Enroll.log
• -d, –domain – YubiHSM 2 domain [Default: 1]
• -i, –authkeyid – KeyId of the YubiHSM 2 authentication key Default: 0x0001;
• -p, –authpassword –  The authentication key password for the YubiHSM 2 [Default:]

A List of the Items on YubiHSM 2

You may now use Sun JCE PKCS11 Provider and YubiHSM 2 PKCS11 to access the generated RSA keypair and X.509 certificate.

It is advised to verify the creation of the X.509 certificate and the RSA keypair on the YubiHSM 2. To list and look at such items on the YubiHSM 2, use either YubiHSM-Shell or Java KeyTool.

Java Application Signing with YubiHSM 2

Any Java signing app that makes use of the standard Sun JCE PKCS11 Provider can now use the YubiHSM 2 PKCS11 once it was configured with an RSA keypair and an X.509 certificate.

For instance, JarSigner could be used to validate a signed JAR file and sign a JAR file using the YubiHSM 2.

To Sign a JAR file, use JarSigner

jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg sun_yubihsm2_pkcs11.conf lib.jar MyKey1 -storepass 0001password -sigalg SHA256withRSA -tsa http://timestamp.digicert.com -verbose

...
jar signed.

To Verify a Signed JAR file, Use JarSigner

jarsigner -verify lib.jar -verbose -certs

...
jar verified.