Configuring YubiHSM 2 for Java Code Signing

The purpose of the scripts in this repository is to generate an RSA key pair and enroll for an X.509 certificate to a YubiHSM 2 using YubiHSM-Shell as the primary software tool. In addition to YubiHSM-Shell, Java KeyTool and OpenSSL are used.

Two scripts are published in the folder Scripts: the Windows PowerShell script YubiHSM_Cert_Enroll.ps1 and the Linux Bash script YubiHSM_Cert_Enroll.sh.

When the RSA keypair and certificate have been enrolled to the YubiHSM 2, the YubiHSM 2 PKCS #11 library can then be used with the Sun JCE PKCS #11 Provider.

More specifically, the key/certificate can be used for signing Java code, for example using JarSigner.

The following steps are performed by the scripts:

Generate an RSA key pair in the YubiHSM 2.
Export the CSR (Certificate Signing Request).
Sign the CSR into an X.509 certificate (using OpenSSL CA as an example).
Import the signed X.509 certificate into the YubiHSM 2.

The scripts are not officially supported and are provided as-is. The scripts are intended as references, and YubiHSM 2 administrators should ensure to read Yubico’s documentation on managing YubiHSMs, see Introduction before making any deployments in production.

Prerequisites

Operating System and SDKs

Use a computer with Windows 10 or a Linux distribution as the operating system.

Attach the YubiHSM 2 device to one of the available USB ports on the computer.

Install the following software SDKs and tools:

YubiHSM SDK (including YubiHSM-Setup, YubiHSM-Shell and YubiHSM-Connector)
OpenSSL
Java JDK (including KeyTool and JarSigner)

Basic Configuration of YubiHSM 2

Start the YubiHSM-Connector, either as a service or from a command prompt.

Launch the YubiHSM-Shell in a different command prompt, and run the following to make sure that the YubiHSM 2 is accessible:

yubihsm-shell
 Using default connector URL: http://127.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

Configuration File for YubiHSM 2 PKCS #11

Create the configuration file yubihsm_pkcs11.conf and store it in the same folder as the yubihsm_pkcs11 module (which is typically C:\Program Files\Yubico\YubiHSM Shell\bin\pkcs11\ on Windows and /usr/lib64/pkcs11/ on Linux).

Configure the yubihsm_pkcs11.conf according to the instructions on the Configuration webpage. If the YubiHSM-Connector is running on the same machine, it is sufficient to copy the Configuration File Sample and paste it into the file yubihsm_pkcs11.conf.

Configuration File of Sun JCE PKCS #11 Provider with YubiHSM 2

Next, the YubiHSM 2 PKCS #11 module must be configured for use with the Sun JCE PKCS #11 Provider.

Create the configuration file sun_yubihsm2_pkcs11.conf with the following content:

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

The path to the YubiHSM PKCS #11 configuration file must be set in the environment variables for Windows and Linux:

YUBIHSM_PKCS11_CONF = <YubiHSM PKCS11 folder>/yubihsm_pkcs11.conf

On Windows it is also recommended to add the following 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

The Java keystore contains a number of pre-configured trusted CA-certificates. The Java signing certificate in the YubiHSM 2 will be validated against the trusted CA-certificates in the Java keystore.

It is therefore recommended to check that the CA-certificate(s) that have been used to issue the Java signing certificates are present in the Java keystore. This can be checked by running the following command:

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

If it is not present, add the CA-certificate(s) as trusted certificate(s) to the Java keystore. The Java tool KeyTool can be used for this purpose.

In order to update the Java keystore, start a console in elevated mode (“Run as administrator” on Windows or use “sudo” on Linux), and then run the commands below to import and verify 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>

Below are examples of the commands to import and verify the CA-certificate(s) are:

keytool -import -noprompt -cacerts -storepass changeit -alias MyCACert -file ./rootCACert.pem

keytool -list -cacerts -storepass changeit -alias MyCACert

Signing JAR files

Consider the following minimal Java source file:

cat HelloWorld.java
public class HelloWorld {
      public static void main(String [] args) {
              System.out.println("Hello, world");
      }
    }

Compile the java source file and create an (unsigned) .jar file:

javac HelloWorld.java
jar cfe unsigned.jar HelloWorld HelloWorld.class

We can now sign this JAR file with the RSA signing key we have stored in our YubiHSM 2 and create a signed JAR file:

jarsigner -tsa http://timestamp.digicert.com -addProvider SunPKCS11 -providerArg ./sunpkcs11.conf -keystore NONE -storetype PKCS11 -storepass 0001password -signedjar signed.jar ./unsigned.jar rsaSign

jar signed.

Warning:
The signers certificate is self-signed.
The timestamp will expire on 2031-11-10.

In this case, a self-signed certificate was used, but for others to be able to validate the certificate you should use a public CA to sign your Java code.

Note that we are using a timestamp server to record the current time in the signed JAR file. This way we do not need to resign the JAR file when the signing certificate expires.

Verifying signed JAR files

To verify the signature on the signed JAR, we use the public key certificate stored on the YubiHSM 2.

jarsigner -verify -addProvider SunPKCS11 -providerArg ./sunpkcs11.conf -keystore NONE -storetype PKCS11 -storepass 0001password ./signed.jar

jar verified.

If we trust the signer and the Certificate Authority that issued the signer’s certificate, we can decide to run the software in the JAR file:

java -jar signed.jar
Hello, world

Note that access to the YubiHSM2 is not required when verifying a signature on a signed JAR file as the certificate is included in the JAR file itself. Verification will fail however unless the certificate was signed by a trusted Certification Authority.

Windows PowerShell script for generating keys and certificates

The PowerShell script YubiHSM_Cert_Enroll.ps1 in the Scripts folder can be executed on Windows to generate an RSA key pair and enroll for an X.509 certificate to a YubiHSM 2.

YubiHSM-Shell is used in command line mode.

OpenSSL is used as a basic CA for test and demo purposes only. For real deployments, however, the OpenSSL CA should be replaced with a proper CA that signs the CSR into an X.509 certificate.

Parameters

The PowerShell script has the following parameters.

Parameter	Purpose
Algorithm	Signature algorithm Default: RSA2048
AuthKeyID	KeyId of the YubiHSM 2 authentication key Default: 0x0001
AuthPW	Password to the YubiHSM 2 authentication key Default:
CAcertificate	CA certificate used by OpenSSL (for test purposes) Default: TestCACert.pem
CAPrivateKey	CA private key used by OpenSSL (for test purposes) Default: TestCAKey.pem
CAPrivateKeyPW	Password of the OpenSSL keystore (for test purposes) Default:
CreateCSR	Generate keys and export CSR and then exit
CSRfile	File to save the CSR request to Default: ./YHSM2-Sig.(date and time).csr
Dname	X.500 Distinguished Name to be used as subject fields Default:
Domain	Domain in the YubiHSM 2 Default: 1
ImportCert	Import signed certificate created with CreateCSR
KeyID	KeyID where the RSA key pair is stored Default: 0x0002
KeyName	Label of the key/certificate, same as Java alias Default: MyKey1
LogFile	Log file path Default: WorkDirectory/YubiHSM_PKCS11_Enroll.log
PKCS11Config	Java JCE PKCS #11 configuration file Default: ./sun_yubihsm2_pkcs11.conf
Quiet	Suppress output
SignedCert	Signed certificate file. Default:
WorkDirectory	Working directory where the script is executed Default: $PSScriptRoot

All parameters have default settings in the PowerShell script. The parameters can either be modified in the PowerShell script or be used as input variables when executing the script.

Example of how to execute the PowerShell script:

$ .\YubiHSM_PKCS11_Setup.ps1 -KeyID 0x0003

Linux Bash Script for Generating Keys and Certificates

The Bash script YubiHSM_Cert_Enroll.sh in the Scripts folder can be executed on Linux to generate an RSA key pair and enroll for an X.509 certificate to a YubiHSM 2.

YubiHSM-Shell is used in command line mode.

OpenSSL is used as a basic CA for test and demo purposes only. For real deployments, however, the OpenSSL CA should be replaced with a proper CA that signs the CSR into an X.509 certificate.

Parameters

The Bash script has the following parameters.

Parameter	Purpose
-a, -algorithm	Signature algorithm Default: RSA2048
-c, -cacertificate	CA certificate used by OpenSSL (for test purposes) Default: ./TestCACert.pem
-C, -createcsr	Generate keys and export CSR and then exit
-d, -domain	Domain in the YubiHSM 2 Default: 1
-f, -pkcs11configfile	Java JCE PKCS #11 configuration file Default: ./sun_yubihsm2_pkcs11.conf
-F, -csrfile	File to save the CSR request to Default: ./YHSM2-Sig.(date and time).csr”
-k, -keyed	KeyID where the RSA key pair will be stored Default: 0x0002
-n, -keyname	Label of the key/certificate, same as Java Alias Default: MyKey1
-o, -dname	X.500 Distinguished Name to be used as subject fields Default:
-p, -authpassword	Password to the YubiHSM 2 authentication key Default:
-q, -quiet	Suppress output
-r, -caprivatekeypw	Password of the OpenSSL keystore (for test purposes) Default:
-s, -caprivatekey	CA private key used by OpenSSL (for test purposes) Default: ./TestCAKey.pem
-S, -signedcert	Signed certificate file. Mandatory when using -importcert Default: ”
-t, -logfile	Log file path Default: ./YubiHSM_PKCS11_Enroll.log

All parameters have default settings in the Bash script. The parameters can either be modified in the Bash script or be used as input variables when executing the script.

Example of How to Execute the Bash Script

$ ./YubiHSM_PKCS11_Setup.sh -k 0x0002 -n MyKey -d 1 -a rsa2048 -i 0x0001 -p password -c ./TestCACert.pem -s ./TestCAKey.pem -f ./sun_yubihsm2_pkcs11.conf

List the Objects on YubiHSM 2

The created RSA key pair and X.509 certificate can now be accessed through YubiHSM 2 PKCS11 and be used with Sun JCE PKCS11 Provider.

It is recommended to check that the RSA key pair and the X.509 certificate have been created on the YubiHSM 2. It is possible to use either YubiHSM-Shell or Java KeyTool to list and check those objects on the YubiHSM 2.

Example: YubiHSM-Shell Command

yubihsm> list objects 0
Found 3 object(s)
id: 0x0001, type: authentication-key, sequence: 0
id: 0x0002, type: opaque, sequence: 1
id: 0x0002, type: asymmetric-key, sequence: 0
yubihsm> get objectinfo 0 0x0002 asymmetric-key
id: 0x0002, type: asymmetric-key, algorithm: rsa2048, label:
    "........................................", length: 896, domains: 1,
    sequence: 0, origin: generated, capabilities: exportable-under-wrap:
    sign-attestation-certificate:sign-pkcs:sign-pss

Example: Java KeyTool Command

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg sun_yubihsm2_pkcs11.conf -storepass 0001password -v

Keystore type: PKCS11
Keystore provider: SunPKCS11-yubihsm-pkcs11

Your keystore contains 1 entry

Alias name: MyKey1
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=YubiHSM Attestation id:0xd353
Issuer: EMAILADDRESS=admin@test.se, CN=TestCA, OU=Test, O=Yubico, L=Stockholm, ST=Stockholm, C=SE
Serial number: 23161118fc1d59fbab75138b562a4b00c8163c3d
Valid from: Wed Apr 14 10:43:28 CEST 2021 until: Sat Aug 27 10:43:28 CEST 2022
Certificate fingerprints:
   SHA1: 38:1E:81:1A:0A:6E:B0:87:E0:B6:5C:8A:B8:C6:EC:91:1D:51:28:1A
   SHA256: CC:F7:26:6C:70:12:7E:E3:62:22:71:9B:3C:32:16:C8:C6:34:10:F:49:22:7A:18:70:09:E3:3E:73:42:38:47
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 1

Using YubiHSM 2 with Java Signing Applications

When the YubiHSM 2 has been configured with an RSA key pair and a X.509 certificate, the YubiHSM 2 PKCS11 can now be used with any Java signing application that utilizes the default Sun JCE PKCS11 Provider.

For example, JarSigner can be used to sign a JAR-file with the YubiHSM 2 and validate the signed JAR-file.

Example: Use JarSigner to sign a JAR-file

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.

Example: Use JarSigner to Validate a Signed JAR-file

jarsigner -verify lib.jar -verbose -certs
...
jar verified.

Signing XML files using YubiHSM 2

Many applications make use of XML to structure data stored in files, databases, or elsewhere. To establish trust in such data, these documents can be signed using XML Signatures.

In order to sign XML documents you can use a tool called xmlsectool. As xmlsectool is implemented as a Java application using the JCA en JCE standards, we can use a YubiHSM 2 to store the signing keys we use for generating XML signatures.

A simple example

As an example, generate an RSA key pair and a self-signed certificate stored on the YubiHSM 2:

$ keytool -keystore NONE -storetype PKCS11 -storepass 0001password -addProvider SunPKCS11 -providerArg ./sunpkcs11.conf -genkey -alias rsaSign -keyalg RSA -dname CN=rsaSign
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 90 days
for: CN=rsaSign

As before, we are using the SunPKCS11 provider to interface with the YubiHSM2, similar to other examples in this chapter.

Signing XML files

Let’s generate a very simple XML file:

$ echo '<x></x>' > unsigned.xml

Sign the XML file using xmlsectool:

$ xmlsectool --sign --pkcs11Config ./sunpkcs11.conf --inFile unsigned.xml --keyAlias rsaSign --keyPassword 0001password --outFile signed.xml

INFO  XMLSecTool - Reading XML document from file 'unsigned.xml'
INFO  XMLSecTool - XML document parsed and is well-formed.
INFO  XMLSecTool - XML document successfully signed
INFO  XMLSecTool - XML document written to file /home/user/signed.xml

The signed XML document nog contains a Signature element containing the a SignatureValue and a KeyInfo element containing a copy of the X.509 certificate on the YubiHSM 2:

<x>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
  <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
  <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
  <ds:Reference URI="">
    <ds:Transforms>
      <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
      <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    </ds:Transforms>
  <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <ds:DigestValue>9hy1oK7rXCJu4rTqLZ7cGUH3rPyGm4QllC8VRv6mX60=</ds:DigestValue>
  </ds:Reference>
    </ds:SignedInfo>
  <ds:SignatureValue>ce5SooQsD...aiUDiOkaBiWI8A4olAuRcIgme0PqeLg==</ds:SignatureValue>
  <ds:KeyInfo>
    <ds:KeyValue>
      <ds:RSAKeyValue>
        <ds:Modulus>uSsZh/aAk...MK4yY1LTUqF2HzSO9d4vGdWzwm4Z63ot6w==</ds:Modulus>
        <ds:Exponent>AQAB</ds:Exponent>
      </ds:RSAKeyValue>
    </ds:KeyValue>
    <ds:X509Data>
      <ds:X509Certificate>MIICxzCCAa+g.../BUkO7i8reQw+6qA==</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </ds:Signature>
</x>

In the above document, we have shortened the Base64 encoded text elements for brevity.

Verifying XML digital signatures

To verify the signed XML file, we can also use xmlsectool:

$ xmlsectool --verifySignature --inFile signed.xml --pkcs11Config ./sunpkcs11.conf --keyAlias rsaSign --keyPassword 0001password
INFO  XMLSecTool - Reading XML document from file 'signed.xml'
INFO  XMLSecTool - XML document parsed and is well-formed.
INFO  XMLSecTool - XML document signature verified.

Here, we are referring to the signing certificate stored on the YubiHSM 2 to be able to verify signatures when direct access to the YubiHSM 2 is not available, we need to export the signing certificate and distribute it to whoever needs to be able to verify such signatures.

To export the signing certificate stored on a YubiHSM 2 using keytool:

$ keytool -keystore NONE -storetype PKCS11 -storepass 0001password -addProvider SunPKCS11 -providerArg ./sunpkcs11.conf -exportcert -alias rsaSign -rfc > signing-crt.pem

We can now use xmlsectool to verify an XML digital signature using the public key in the signing certificate:

xmlsectool  --verifySignature --inFile signed.xml --certificate signing-crt.pem
INFO  XMLSecTool - Reading XML document from file 'signed.xml'
INFO  XMLSecTool - XML document parsed and is well-formed.
INFO  XMLSecTool - XML document signature verified.

In case the signature does not verify, xmlsectool will complain:

$ xmlsectool  --verifySignature --inFile signed.xml --certificate signing-crt.pem
INFO  XMLSecTool - Reading XML document from file 'signed.xml'
INFO  XMLSecTool - XML document parsed and is well-formed.
WARN  XMLSignature - Signature verification failed.
ERROR XMLSecTool - XML document signature verification failed
make: *** [verify] Error 7

In this case, either the XML document was changed after its signature was generated, or the public key in the certificate does not match the private key used for signing. Either way, the XML signature cannot be used to establish trust in the XML document’s authenticity.

For more information, see Using PKCS11 Credentials from the xmlsectool documentation.

A real-world example: SAML metadata signing

One example application of using XML signatures is in identity federation, where users can logon to a web application after authenticating somewhere else. A well-known protocol used for identity federation is SAML 2.0, and this protocol is based on XML.

The parties where users may want to logon (called Service Providers) need to exchange information with the parties where users authenticate (called Identity Providers), and this SAML 2.0 Metadata is typically signed using XML Signatures so it can be automatically verified by SAML peers.

Consider the following SAML 2.0 metadata document for a fictitious Service Provider which specifies its identifier (entity ID), its SAML signing certificate and the URL endpoint an Identity Provider can direct users to in order to process a SAML authentication response:

<md:EntityDescriptor  ID="XYZ123456"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://example.com/saml/sp.xml">
<md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" >
<md:KeyDescriptor>
  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:X509Data>
      <ds:X509Certificate>
          MIHnMIGiAgEBMA0GCSqGSIb3DQEBBAUAMA8xDTALBgNVBAMMBHNpZ24wHhcNMjMwM
          TA1MTI0ODExWhcNMjgwNjI3MTI0ODExWjAPMQ0wCwYDVQQDDARzaWduMEwwDQYJKo
          ZIhvcNAQEBBQADOwAwOAIxAKrBRhYU03MSaU8jBPNUx9wcc6bWhMpinZmINR0JNdh
          3SkPddh7zskcLGonFsmasQIDAQABMA0GCSqGSIb3DQEBBAUAAzEADng7opb78PNoL
          ZH1QzYqmxV0ZSc3rE0OlTW00W/Xq7+77OhU5vVAVYnXpQLlv6sB
  </ds:X509Certificate>
    </ds:X509Data>
  </ds:KeyInfo>
</md:KeyDescriptor>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" index="0" Location="https://example.com/saml/acs"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

Note that the certificate in the Metadata is intended for validating SAML protocol messages and is typically different from the certificate used for validating SAML 2.0 metadata. Either or both certificates can have their private keys stored on the YubiHSM 2, but be aware that SAML protocol messages are signed much more frequently than SAML metadata documents, so the former may require multiple YubiHSM 2 deployments in order to scale with the load on your SAML IdP or SP.

To sign this SAML metadata document, we again use xmlsectool with the signing key stored in a YubiHSM 2. We also specify ID as the name of the XML attribute to use in the XML signature.

xmlsectool --sign --pkcs11Config ./sunpkcs11.conf  --inFile unsigned.xml --keyAlias rsaSign --keyPassword 0001password --outFile signed.xml --referenceIdAttributeName ID

As before, we will need to export the SAML signing certificate to distribute among our SAML peers so they can validate our signed metadata.

Example Java code using YubiHSM 2

To interface to cryptographic keys stored on a YubiHSM 2 from Java code, we can use the SunPKCS11 provider.

This has the added benefit that we can write code that is independent of the specific HSM used, as long as the HSM has a PKCS#11 module available.

Apart from writing code, we need to configure all components correctly in order for the code to work correctly. This includes the configuration of the YubiHSM 2 connector, Java keytool, and the SunPKCS11 provider.

To illustrate, we will code a simple RSA signing example below.

Setup

Let’s assume we have a single YubiHSM 2 connected locally via USB. Store the connector configuration in a file named yubihsm.conf and point to it via the YUBIHSM_PKCS11_CONF environment variable so that the YubiHSM 2 PKCS#11 module will be able to find it:

$ echo "connector=yhusb://" > yubihsm.conf export YUBIHSM_PKCS11_CONF=yubihsm.conf

We will be using Java’s keytool to manage keys and certificates on the YubiHSM 2. For convenience, store the PKCS#11 configuration options in a file named keytool.config:

$ cat keytool.config
keytool.all = -keystore NONE -storetype PKCS11 -storepass 0001password -addProvider SunPKCS11 -providerArg ./sunpkcs11.conf

The file sunpkcs11.conf is used to configure the PKCS#11 module we want to use, and the PKCS#11 attributes we want to define for objects created or imported via the SunPKCS11 provider:

$ cat sunpkcs11.conf
name = YubiHSM2
library = /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib
attributes(*, CKO_PRIVATE_KEY, CKK_RSA) = {
   CKA_SIGN=true
}

Finally, we can create an RSA key pair and a self-signed certificate using Java’s keytool.

 $ keytool -conf keytool.config -genkey -alias rsaSign -keyalg RSA -dname CN=rsaSign
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 90 days for: CN=rsaSign

Note that when using keytool, the keys are generated in software and subsequently imported into the YubiHSM 2. To generate keys on the YubiHSM 2 itself, use the yubihsm-shell tool.

The generated certificate should now be visible from keytool. For example:

$ keytool -conf keytool.config -list
Keystore type: PKCS11
Keystore provider: SunPKCS11-YubiHSM2

Your keystore contains 1 entry

rsaSign, PrivateKeyEntry,
Certificate fingerprint (SHA-256):
   02:50:E4:1B:D8:FB:1B:07:AB:8C:05:85:37:BD:FB:89:6F:57:1F:CC:86:EC:
   E5:F2:BE:61:76:68:38:58:F0:39

Code

Now, let’s turn to coding. In this example, we will be signing files using the RSA private key stored on our YubiHSM 2.

The data to be signed is a simple text file, for instance:

$ date > datatosign

The code needs to do some file I/O, and use the JCA and JCE standards to generate and verify signatures. Let’s start with the necessary imports:

import java.nio.file.Path;
import java.nio.file.Files;
import java.io.FileOutputStream;
import java.security.cert.X509Certificate;
import java.security.*;

To keep things simple, we do not handle Exceptions here and define some hardcoded parameters:

public class RsaSignP11 {
   public static void main(String... argv) throws Exception {

     String pkcs11Conf = "sunpkcs11.conf";
     String userPin = "0001password";
     String keyAlias = "rsaSign";
     String infile = "datatosign";
     String outfile = "signature.bin";

   // see below ...
  }
}

Using hard-coded parameters is only to keep the example concise. Normally these would be command-line parameters or read from a configuration file. Passwords should never be hard-coded and are typically read from a terminal on demand.

To continue with our example code, first load and configure the SunPKCS11 provider:

Provider provider = Security.getProvider("SunPKCS11"); provider = provider.configure(pkcs11Conf); Security.addProvider(provider);

Load the PKCS11 KeyStore, authenticating with the User PIN:

KeyStore ks = KeyStore.getInstance("PKCS11", provider); ks.load(null, userPin.toCharArray());

Retrieve the private key, and sign the data read from the datatosign file using the SHA256withRSA algorithm:

PrivateKey privateKey = (PrivateKey) (ks.getKey(keyAlias, null));
Signature rsaSig = Signature.getInstance("SHA256withRSA"); rsaSig.initSign(privateKey); byte[] datatosign = Files.readAllBytes(Path.of(infile)); rsaSig.update(datatosign); byte[] sigBytes = rsaSig.sign();

Optionally, the signature can be stored in a signature file for others to verify:

new FileOutputStream(outfile).write(sigBytes);

While we are at it, let’s also verify if the signature generated in sigBytes can be verified using the corresponding public Key.

First we need to extract the public key from the certificate pointed to by our rsaSign alias:

X509Certificate cert = (X509Certificate) ks.getCertificate(keyAlias); PublicKey publicKey = cert.getPublicKey();

Again using the SHA256withRSA algorithm, verify that the signature in sigBytes matches the data in datatosign using our publicKey:

rsaSig = Signature.getInstance("SHA256withRSA");
rsaSig.initVerify(publicKey);
rsaSig.update(datatosign);
assert rsaSig.verify(sigBytes) == true : "verify failed";

To test, compile the source:

$ javac RsaSignP11.java

Run the program:

$ java RsaSignP11

There is no output, meaning the assert was passed without issues and the signatures verifies.

Troubleshooting

Debugging issues with HSMs can be difficult. It may help to enable logging using the following JVM system properties:

For PKCS#11 keystore specific debugging info:

-Djava.security.debug=pkcs11keystore

For general SunPKCS11 provider debugging info:

-Djava.security.debug=sunpkcs11

Also, refer to the documentation on PKCS#11 with YubiHSM 2 for generating debug logs from the PKCS#11 module itself.