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”
- rm $name.key.pem
- rm $name.csr
- rm $name.pem
- 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 ?
This sets the end date for the certificate – the end date is set when it is signed.
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
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.
- 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
- –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
(Having a CA just for HSM keys, such as SSSCAHSM would make it more obvious.)
One thought on “Using a hardware security module USB as a keystore for a browser.”