Configuring YubiHSM 2 for Java Code Signing

The purpose of the scripts in this repository is to generate an RSA keypair 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 keypair 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

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 keypair 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 keypair will be 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 keypair 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 keypair 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 keypair 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 keypair 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 keypair 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>
          MIHnMIGiAgEBMA0GCSqGSIb3DQEBBAUAMA8xDTALBgNVBAMMBHNpZ24wHhcNMjMwMTA1MTI0ODExWhcNMjgwNjI3MTI0ODExWjAPMQ0wCwYDVQQDDARzaWduMEwwDQYJKoZIhvcNAQEBBQADOwAwOAIxAKrBRhYU03MSaU8jBPNUx9wcc6bWhMpinZmINR0JNdh3Sk/Pddh7zskcLGonFsmasQIDAQABMA0GCSqGSIb3DQEBBAUAAzEADng7opb78PNoLZH1QzYqmxV0ZSc3rE0OlTW00W/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.