[Mud] Using an HSM to sign MUD files?

[Eliot Lear <[e-mail]>]

I was asked by a partner how to modify the normal MUD signing instructions when an HSM is in play.  Each HSM is a little different, but the general concepts are the same.  OpenSSL does come equipped with a means to invoke HSMs.  What has to happen, roughly speaking is the following:

Configure the HSM engine in the openssl.cnf file.
Make sure you know the PKCS#11 URI
Invoke the engine using cms.

I’m using SoftHSM2 only as an example in this message.  If you need to install a certificate and a key into the HSM, follow its instructions to do so.  For SoftHSM2 that means doing the following:

Initialize a token:
softhsm2-util --init-token --slot 1 --label mud
Find the Slot # associated with that label
softhsm-util —show-slots
Load the appropriate private key:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so  --slot 1810141384 --pin secret --write-object clientcert.key --type privkey
Load the appropriate certificate:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --slot 1810141384 -pin secret --write-object clientcert.pem --type cert


One must next inform OpenSSL that the engine is to be used.  This is done in the openssl.cnf file.  I will not go through the details of this file’s construction, as it was written by good people who happen to have sadistic tendencies.

At the very top of the file, we add the following line:

openssl_conf = openssl_init

Then at the very bottom of the file we will add the following lines:

[openssl_init]

engines=engine_section

[engine_section]
pkcs11=pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/x86_64-linux-gnu/engines-1.1/libpkcs11.so
MODULE_PATH= /usr/lib/softhsm/libsofthsm2.so
default_algorithms = ALL
init = 1

The top part informs openssl that it should check the [openssl_init] section on initialization.  The openssl_init section indicates where to find the engine section, and then we get to the pkcs11 engine.

You will need to replace the softhsm line with an appropriate line for you, given to you by the HSM manufacturer, and they may also give you some arguments.

Now… you will note the use of libpkcs11 above.  To install that:

sudo apt-get install -y libpkcs11 libengine-pkcs11-openssl1.1

The next thing you will need is the appropriate PKCS#11 URI.  To get that, I have found that p11tool does the job best, as follows:

sudo apt-get install -y gnutls-bin
p11tool --list-tokens


You should get output along the lines of:

Token 2:
	URL: pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=88807c3febe490c8;token=mud
	Label: mud
	Type: Generic token
	Manufacturer: SoftHSM project
	Model: SoftHSM v2
	Serial: 88807c3febe490c8
	Module: /usr/lib/softhsm/libsofthsm2.so

All of this information will likely vary for you.  The only thing you care about is the URI.  Copy what you see in the response.  If you don’t see anything with p11tool, stop.  Some debugging is in order at that point.

Now to sign the file using cms, we use a line similar to how one normally signs a mud file.  This time, however, we will invoke the PKCS#11 engine.  This has to be done in three ways: by specifying the -engine option, by indicating the keyform, and by modifying -inkey.

% openssl cms -in mudfile.json -outform der -engine pkcs11 -keyform engine -sign -signer clientcert.pem -binary -certfile intermediate.pem -out mudfile.p7s  -inkey 'pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=88807c3febe490c8;token=mud;pin-value=123456’


Note the addition of the pin at the end.

For this operation to work, we presume that you have the normal signing certificate available as a file.

Different drivers work a little differently.  Some are in a position to prompt you for the PIN, and this is of course preferred.

Eliot