Tutorial: nCipher NetHSM and OpenSSL

A project I’ve been working on involves a fairly high security for dealing with S/MIME emails. The standard this is based on mandates the use of some kind of dedicated key storage hardware, conforming to FIPS and so on.

So I got to play with a couple of best of breed toys: nCipher NetHSM. Setting them up and configuring clients was a breeze (well, mostly); the trouble started when we tried interfacing our custom software to them. This is when I realized there was few to no information around on using OpenSSL with HSMs.

At the end I figured it out (as you figured, or I wouldn’t be blogging about this); however, since that took a while and a good look at sources, I thought I might save someone else some time by writing a short intro.

UPDATE: this is not what you are looking for? looking for a tutorial on OpenSSL with a broader scope? Please have a look at this post on more OpenSSL tutorials.

UPDATE: Duncan Jones sent me an email with some corrections on the way keys are stored (encypted) in the kmdata directory.

checklist

In the following I’m going to assume you already have:

• basic notions of security and SSL;
• set your hardware up and installed feature codes on your NetHSM(s);
• installed the RFS and configure the NetHSM(s) to use it (if needed);
• configured your clients to connect to the NetHSM(s);
• we’ll only go briefly over your hardserver and Security World setup, so you’ll have to have that already in place, too;
• you should have a set of Operator card(s), and you should already have made up your mind on how many of them you want in a set.

Another thing you definitely want to verify is your OpenSSL version: vulnerabilities aside, I heartily recommend running a version greater or equal to 0.9.7, as you’ll spare youself having to recompile OpenSSL.

mission goal

I will show you how to securely generate a private key on the NetHSM, then create a certificate request to send off to a CA, in order to get a certificate, which you’ll be able to use for any purpose, such as running an https or smtps server, signing S/MIME, etc…

briefing

The NetHSM is a powerful toy, and it can perform several functions. What we are mostly interest in however is its ability to safely store keys, and use them in crypto operations. Moreover, if you have more than one NetHSM in the same security world, they automatically mirror the keys, so you get resilience and load balancing¹.

Now if you’re used to using OpenSSL in the context of a secure web server or something like that, you might have never given much thought to keys; you might even have received it from somebody else in your company that deals with “that stuff” (that being security, or running the CA). But now you’ll have to care.

To run an SSL-based service (or any asymmetric crypto, for that matter), you need two pieces: your key and your certificate. You use your key to sign data meant for others and to decrypt data others sent your; you use the certificate to prove to others that somebody (the certificate issuer) trusts you. Obviously, the key needs to be kept secret, while your certificate is public.

Normally you don’t notice it, but when using an hardware key storage device, you have two different steps: you first create the key on your device (and maybe replicate it if you have more devices) using a procedure specific to your HSM brand and model; then you use OpenSSL to generate a certificate or certificate request.

There are few decisions you have to make when creating keys for OpenSSL use. One of those is how to protect your keys: you can use a token, a softcard, or a module. Leaving aside the softcard, which doesn’t make much sense, using the token to protect the key basically means you need to have an operator key inserted at all times to use the key. Since you definitely don’t want that, we will choose to protect them with the module.

get your engines running

Let’s go through the basics. OpenSSL² supports a number of “engines”, which are plugins which allow you, usually through external vendor shared objects, to delegate a number of operations to some kind of specialized hardware. The supported operations range from random number generation (to get better randomness), to signing (to get better speed), to key storage. This is what we’re mostly concerned with.

You can find out what engines your openssl supports by running:

# openssl version
(dynamic) Dynamic engine loading support
(cswift) CryptoSwift hardware engine support
(chil) nCipher hardware engine support
(atalla) Atalla hardware engine support
(nuron) Nuron hardware engine support
(ubsec) UBSEC hardware engine support
(padlock) VIA PadLock (no-RNG, no-ACE)
(aep) Aep hardware engine support
(sureware) SureWare hardware engine support
(4758cca) IBM 4758 CCA hardware engine support%

chil is what we’re interested in. You can verify whether it’s working or not, but chances are it won’t:

# openssl engine -t chil
(chil) nCipher hardware engine support
[ unavailable ]
643102:error:25066067:DSO support routines:DLFCN_LOAD:could not load the shared
library:dso_dlfcn.c:153:filename(libnfhwcrhk.so): 0509-022 Cannot load module .
0509-026 System error: A file or directory in the path name does not exist.
643102:error:25070067:DSO support routines:DSO_load:could not load the shared library:dso_lib.c:244:
643102:error:81067068:hwcrhk engine:HWCRHK_INIT:dso failure:hw_ncipher.c:529:

This is telling you it’s not finding the vendor library. You’ll find that under ${NFAST_HOME}/toolkits/hwcrhk³, so you’ll want to let the linker know, too. The way you do that is OS-dependent: under AIX, you would add this directory to LIBPATH; under Linux you’d probably need to add it to LD_LIBRARY_PATH instead.

Now try running openssl engine -t chil again, it should work:

# openssl engine -t chil
(chil) nCipher hardware engine support
[ available ]
360636:error:81067072:hwcrhk engine:HWCRHK_INIT:dynamic locking missing:hw_ncipher.c:584:
You HAVE to add dynamic locking callbacks via CRYPTOset_dynlock{create,lock,destroy}_callback()

Read that last line well. If you are writing your own software, read it again. What this is telling you is that this engine is not reentrant; if your app is multithreaded you’ll need to take extra steps. We won’t be covering this here; refer to man CRYPTO_set_dynlock_create_callback and crypto/threads/mttest.c and you’ll find enough info to get it done.

lift off!

Now before we start, take a look at what keys you have on your module: the command is ${NFAST_HOME}/bin/nfkminfo -k. Chances are this is a new system and you’ll see no keys for now.

To create a key, you use the command unsurprisingly called generatekey; it takes one mandatory parameter, which is the type of key you want to create. There are different types available, but since we’re only deal with OpenSSL here, you only need to care about hwcrhk. You will need to have your operator card(s) in the reader; if you don’t, it will ask you to do so.

So, let’s try it:

# ${NFAST_HOME}/bin/generatekey hwcrhk
module: Module to use? (1, 2) [1] >
protect: Protected by? (token, softcard, module) [token] > module
type: Key type? (RSA, DSA, DH) [RSA] >
size: Key size? (bits, minimum 1024) [1024] >
OPTIONAL: pubexp: Public exponent for RSA key (in hex)? [] >
ident: Key identifier? [] > test
key generation parameters:
operation Operation to perform generate
application Application hwcrhk
module Module to use 1
protect Protected by module
verify Verify security of key yes
type Key type RSA
size Key size 1024
pubexp Public exponent for RSA key (in hex)
ident Key identifier test
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_hwcrhk_rsa-test

For the most part, we’re just accepting default parameters⁴. We just need to make sure the key is protected by the module (that is, it’s resident in the main memory of the NetHSM and it’s always accessible even if the operator card is not in the reader). I gave the key the oh-so-imaginativa name of “test”; this is important as you’ll refer to the key as “rsa-test”.

Now look at the last line: it’s telling you the path to a file where the command has stored the key for backup purposes. Now that might sound weird and dangerous, given that the whole point of this exercise is to make sure the key is stored in the NetHSM and never exposed, but I can assure you it’s perfectly safe: this file is still no good without the operator card(s). On the other hand, this file will allow you to restore the key on a new NetHSM in case the original one is destroyed, so make sure you store it somewhere safe⁵.

UPDATE: Duncan Jones writes:
The file stored in kmdata/local is actually the key file. It is not a
backup, although of course you should back it up.

The file is encrypted under a secret key that is related to the currenty
security world of the netHSM. It is useless/unreadable in any other
security world, however it is not protected by any operator cards.

Also, backing up individual key files is completely useless. You need
to back up the entire kmdata directory. You cannot simply use the
keyfile with another netHSM – the other netHSM must be initialised into
the SAME security world that the original netHSM was in (hence the need
to backup all of the kmdata/ directory).

Let’s check what we’ve done:

# ${NFAST_HOME}/bin/nfkminfo -k
Key list – 1 keys
AppName hwcrhk Ident rsa-test

waypoint reached, now to finish it off

We have created the key, now we only have to create the certificate the usual way⁶:

# openssl req -new -out newreq.pem -days 365 \
-engine chil -keyform engine -key rsa-test
engine “chil” set.
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ’.’, the field will be left blank.
——-
Country Name (2 letter code) [AU]:IT
State or Province Name (full name) [Some-State]:MI
Locality Name (eg, city) []:Milan
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example, inc.
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:smtp.example.com
Email Address []:me@example.com

Please enter the following ‘extra’ attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

This is possibly familiar, except the last three arguments:

• -engine chil as should now be clear instructs OpenSSL to load the correct library to use the engine to perform some task;
• -keyform engine tells OpenSSL that, of all the tasks the engine can be used for, we want to use it to access the key;
• -key rsa-test points OpenSSL to use the key we just created.

You now have a newreq.pem file you can send off to your favorite CA to get it signed. In alternative, you can add a -x509 argument to specify you want a self-signed certificate. This can be useful for instance if you’re starting your own CA.

debriefing

You should now have enough information to know your way around the instrumentation, and you’re free to fly solo. There is still a lot of information you can find useful in the nCipher documentation, so I will strongly advise you to go read it; but only after you’ve played some more.

notes

¹ By the way, this is the reason I picked the NetHSM instead of its less expensive PCI cousins: if you fry one of those, your server is useless; if your server goes down, you have to take the card out to put a new server into service. With the NetHSM you don’t have to worry about all that. and you can add server as you grow at just the price of an additional license.

² The first release to support engines was 0.9.6, but that was through a separate distribution. Release 0.9.7 has merged engine support into the main distribution. That’s why I recommend running a 0.9.7.

³ The exact value of ${NFAST_HOME} depends on your operating system, but you can also change it. Under AIX and possibly other OS it’s /opt/nfast. Refer to nCipher documentation if you are not sure.

⁴ During our tests we could not get a DSA key to work; we didn’t have time to get into the details. If you think you need to use DSA you’ll need to figure it out for yourself.

⁵ The file actually has one more very important use: I’m not one hundred percent sure why (if you know, you’re definitely welcome to tell me!), but you need to copy this file to any other client(s) you have.

⁶ If you have ever created certificates with OpenSSL, that is.

Comments

• Andrea Campi [bah! la realtà]!

• Categories

  Select Category english  (92) hiking  (4) italiano  (10) joost  (10)    content  (5) misc  (0)    administrivia  (9)    apple  (10)    cats  (2)    old  (59) mobile  (3) photo  (11) security  (4)    openssl  (2) veoh  (1) web development  (1)    AJAX  (2)    javascript  (8)    REST  (1)    rubyonrails  (1) web2.0  (4) zephirworks  (1)

• Archives

  Select Month September 2008  (8) August 2008  (1) May 2008  (1) April 2008  (2) December 2007  (2) November 2007  (3) October 2007  (15) February 2007  (3) January 2007  (4) December 2006  (4) October 2006  (2) August 2006  (9) July 2006  (5) June 2006  (17) May 2006  (17) April 2006  (13) March 2006  (2) June 2003  (4) May 2003  (7) April 2003  (2) March 2003  (8) February 2003  (23) January 2003  (13) November 2002  (1) October 2002  (1)

• Meta

  • Log in
  • Entries RSS
  • Comments RSS
  • WordPress.org

Copyright © 2008 bah! la realtà! • Using Dropshadow Wordpress Theme adapted by bastet.it