Using a hardware security module USB as a keystore for a browser.

Background to certificates and keystores

When using TLS(SSL) you have two keystores

• A keystore for holding the public part and private key of your certificate
• A trust store which holds the public keys of certificate sent to you which you need to authenticate.

Your certificate has two parts

• The private key which contains information needed to encrypt information you send. This needs to be kept private.
• The public part,which has information that is needed to decrypt information you have encrypted, along with information such as your Distinguished Dame (DN) such as CN=ColinPaice C=GB,O=StromnessSoftware

The process of creating a signed certificate is

• Create a private key and public key. This can be done using an external device Hardware Security Module (HSM), such as the Nitrogen HSM USB, or software, for example using OPENSSL. This produces a private key file, and a certificate request file containing the public information.
• Send the public information to your certificate authority which signs it, and returns it
• Import the signed public certificate into your keystore.

Creating a certificate using an HSM as the key repository

I used openssl to process my certificates, I’ve discussed the openssl setup here.

I use a bash script because it is easy to parametrize, and makes it easy to rerun until it works. I’ll give the script, then explain what it does

• enddate=”-enddate 20240130164600Z”
• name=”hw”
• rm $name.key.pem
• rm $name.csr
• rm $name.pem
• ca=”carsa1024″
• pkcs11-tool –keypairgen –key-type rsa:2048 –login –pin 648219 –label “my_key3”
• OPENSSL_CONF=eccert.config openssl req -new -engine pkcs11 -keyform engine -key label_my_key3 -out $name.csr -sha256 -subj “/C=GB/O=HW/CN=colinpaice” -nodes
• openssl ca -config openssl-ca-user.cnf -policy signing_policy -md sha256 -cert $ca.pem -keyfile $ca.key.pem -out $name.pem -in $name.csr $enddate
• openssl x509 -inform pem -outform der -in $name.pem -out $name.der
• pkcs11-tool –write-object $name.der –type cert –label “my_key3” -l –pin 648219

What does the script do ?

enddate=”-enddate 20240130164600Z”

This sets the end date for the certificate – the end date is set when it is signed.

name=”hw”

This is used within the script to ensure the correct files are being used.

Remove old intermediate files

• rm $name.key.pem
• rm $name.csr
• rm $name.pem

ca=”carsa1024″

Define the name of the CA files to use at signing time. The $ca.pem and $ca.key.pem are both needed.

pkcs11-tool –keypairgen –key-type rsa:2048 –login –pin 648219 –label “my_key3”

• pkcs11-tool use this tool
• –keypairgen to create a key pair (private and public pair)
• –key-type rsa:2048 use this key type and key length
• –login –pin 648219 login with the pin number
• –label “my_key3” use this label to identify the key

OPENSSL_CONF=eccert.config openssl req -new -engine pkcs11 -keyform engine -key label_my_key3 -out $name.csr -sha256 -subj “/C=GB/O=HW/CN=colinpaice”

• OPENSSL_CONF=eccert.config this sets up the openssl config file. Having -config eccert.config does not work. See here.
• openssl
• req this is to create a certificate requests – create a .csr.
• -new it is a new request
• -engine pkcs11 use the named engine, pkcs11, defined to the system
• -keyform engine this says use the engine (HSM). Other choices are der and pem
• -key label_my_key3 go to the engine and look for the my_key3 label
• -out $name.csr create this request file with this name.
• -sha256 using this signature
• -subj “/C=GB/O=HW/CN=colinpaice” the name to go in the certificate. It uses colinpaice as the certificate will be used to authenticate with the mq web server, and this is the userid the mq web server should use.

Send the .csr file to the CA for signing (which is the same machine in my case).

openssl ca -config openssl-ca-user.cnf -policy signing_policy -md sha256 -cert $ca.pem -keyfile $ca.key.pem -out $name.pem -in $name.csr $enddate

• openssl ca Use this command to sign the certificate
• -config openssl-ca-user.cnf use this configuration file
• -policy signing_policy use this policy within the config file
• -md sha256 use this for the message digest
• -cert $ca.pem use the public certificate of the CA
• -keyfile $ca.key.pem use this private key of the CA to encrypt information about the csr request’s certificate
• -out $name.pem whee to store the output
• -in $name.csr the input .csr request
• $enddate specify the certificate expiry date – set at the top of the script

Send the signed certificate back to the requester.b

openssl x509 -inform pem -outform der -in $name.pem -out $name.der

The pkcs11-tool uses .der files so convert the .pem file to .der format

• openssl x509
• -inform pem input format
• -outform der output format
• -in $name.pem hw.pem
• -out $name.der hw.der

pkcs11-tool –write-object $name.der –type cert –label “my_key3” -l –pin 648219

Read the signed certificate and write it to the HSM

• pkcs11-tool
• –write-object $name.der write onto the HSM the file hw.der coverted above
• –type cert import type (cert|pubkey|privkey)
• –label “my_key3” use this name
• -l –pin 648219 and logon with this pin number

Define the HSM to Chrome browser

Stop the browser because you need to update the keystore.
The command was issued in the home directory, because key store is in the home directory/.pki .

modutil -dbdir sql:.pki/nssdb/ -add “my_HSM” -libfile opensc-pkcs11.so

• modutil use this command
• -dbdir sql:.pki/nssdb/ to up date this keystore (in ~)
• -add “my_HSM” give it this name
• -libfile opensc-pkcs11.so and use this file to communicate to it

Display the contents of the browser’s keystore

modutil -dbdir sql:.pki/nssdb/ -list

This gave me

Listing of PKCS #11 Modules
 NSS Internal PKCS #11 Module
...
 Mozilla Root Certs
 library name: /usr/lib/x86_64-linux-gnu/nss/libnssckbi.so
...
my_HSM
 library name: opensc-pkcs11.so
    uri: pkcs11:library-manufacturer=OpenSC%20Project;library-description=OpenSC%20smartcard%20framework;library-version=0.17
  slots: 1 slot attached
 status: loaded
 slot: Nitrokey Nitrokey HSM (DENK01051600000         ) 00 00
 token: UserPIN (SmartCard-HSM)
   uri: pkcs11:token=UserPIN%20(SmartCard-HSM);manufacturer=www.CardContact.de;serial=DENK0105160;model=PKCS%2315%20emulated 

Restart the browser.

Use an URL which needs a certificate for authentication.

The browser prompts for the pin number (twice), and displays the list of valid certificate CNs. Pick one. When I connected to the mqweb server, I had 3 certificates displayed. I had to remember which one I wanted from the Issuer’s CN and serial number. For example

Subject	Issuer	Serial
colinpaice	SSCARSA1024	019c
ibmsys1	SSCARSA1024	019a
170594	SSCARSA1024	0197

(Having a CA just for HSM keys, such as SSSCAHSM would make it more obvious.)