nCipher nShield/netHSM
The following covers how the nCipher nShield card is installed and used.
Introduction
nCipher's Security World Concept
The key material for the nShield HSM is stored inside so-called key blobs on the host computer. Each key blob is an encrypted container that contains keys and an Access Control List (ACL) which determines how the keys in the key blob are allowed to be used.
Before a nShield HSM can be used, you must set up a security world. A security world consists of the following:
- A set of HSMs sharing the same module key
- Exactly one Administrator Card Set (ACS) which grants administrative access to the security world
- Zero or more key blobs, where each key blob is protected by one of the following
- The module key and an Operator Card Set (OCS)
- The module key and a passphrase
- The module key only
When a security world is created, a new module key is generated inside the HSM and an ACS is created. Both the ACS and the OCS are a set of N smart cards, such that any M smart cards are required to authorize an operation or decrypt a key blob.
Preload Key Blobs
Each key blob created in the security world corresponds to a token in EJBCA. To make the token visible when creating a new crypto token in EJBCA, you need to preload the key blobs you want to use. When a key blob is preloaded, the key blob is copied to and decrypted inside the HSM. The user on the host computer which ran the preload command is then able to use the keys in the key blob until:
- There is a timeout (controlled by the --timeout parameter of the createocs command)
- The last operator card from the OCS was ejected from the HSM (if an OCS is used to protect the key blob and the OCS is a non-persistent card set)
- Or if the PKCS#11 session was killed, e.g. because the HSM was disconnected from the host
To preload key blobs, the preload command, for OCS tokens, or the ppmk command, for softcard tokens is used.
Example Installation Instructions
Step 1 - Install the nShield Module and Create a Token
Install the nShield module as described in the nShield Installation Guide. Install the client software on the EJBCA server and connect the EJBCA server to the HSM.
The client components needed to install are:
hwsp (drivers, daemon etc)
ctls (key management, and other core tools, key generation tools, config, test tools, pkcs11, etc)
ctd (native and standard basic API tools)
The following provides a summarized example of the above, how to install the nShield Module and create admin and operator card sets:
- Make sure you have all necessary software and drivers installed and created the user and group nfast. In Linux should the software be installed to /opt/nfast or the location environment variable NFAST_HOME is pointing to.
- Login as the nfast user: sudo su nfast
- Set the nCipher box to initialization mode by setting the switch to mode I.
- Clear the nCipher box by pressing the reset button on the device.
Check that the mode is in pre-initialization mode and not in operational:
$ /opt/nfast/bin/enquiry Server: enquiry reply flags none enquiry reply level Six serial number 41C5-BA04-6D2C mode operational version 2.23.6 speed index 147 rec. queue 442..642 level one flags Hardware HasTokens version string 2.23.6cam5, 2.22.6cam7 built on Apr 25 2005 18:15:46 checked in 00000000431dca98 Tue Sep 6 18:58:00 2005 level two flags none max. write size 8192 level three flags KeyStorage level four flags OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred module type code 0 product name nFast server device name EnquirySix version 4 impath kx groups feature ctrl flags none features enabled none version serial 0 remote server port 9004 Module #1: enquiry reply flags none enquiry reply level Six serial number 41C5-BA04-6D2C mode pre-initialisation version 2.22.6 speed index 147 rec. queue 9..152 level one flags Hardware HasTokens InitialisationMode PreMaintInitMode version string 2.22.6cam7 built on Apr 25 2005 18:15:46 checked in 00000000426636cd Wed Apr 20 13:02:37 2005 level two flags none max. write size 8192 level three flags KeyStorage level four flags OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred module type code 6 product name nC1002P/nC3022P device name #1 nFast PCI device, bus 0, slot 13. EnquirySix version 5 impath kx groups DHPrime1024 feature ctrl flags LongTerm features enabled StandardKM version serial 24 rec. LongJobs queue 8 SEE machine type gen1AIFBASHCreate the security world with the command:
$ /opt/nfast/bin/new-world -i -Q 1/1 15:04:50 WARNING: Module #1: preemptively erasing module to see its slots! Create Security World: Module 1: 0 cards of 1 written Module 1 slot 0: empty Module 1 slot 0: unknown card Module 1 slot 0:- passphrase specified - overwriting card Card writing complete. security world generated on module #0; hknso = 6807e0b031c4f797b739ec33ca7dba05279cf54fBASHThe -Q K/N option tells how many administration cards that are created N. K of these cards will be needed to restore a module with a backup of the security world. 1/1 is a bad choice in production but will do in this example. Choose K>=3 and N>K in production.
- Change mode on the switch on the device to mode O.
- Click Clear again.
Check with enquiry that the mode has changed to Operational
Example on creation of operator cards:$ /opt/nfast/bin/createocs -m 1 -Q 2/3 -N ejbca -M -p -T 0 Creating Cardset: Module 1: 0 cards of 3 written Module 1 slot 0: Admin Card #1 Module 1 slot 0: empty Module 1 slot 0: blank card Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 1') Module 1: 1 card of 3 written Module 1 slot 0: remove already-written card #1 Module 1 slot 0: empty Module 1 slot 0: blank card Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 2') Module 1: 2 cards of 3 written Module 1 slot 0: remove already-written card #2 Module 1 slot 0: empty Module 1 slot 0: blank card New passphrases do not match; please try again. Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 3') Card writing complete. cardset created; hkltu = 8d30f2ab5bdccacd8a4333aefed2c0ea1ff0e6db $BASHThis will generate 3 cards of the card set named ejbca. Any 2 of these cards will be needed when generating keys and starting ejbca. Different card sets could be used for different CAs.
The preload command (see below) must always be called as the same user unless the directory /opt/nfast/kmdata/preload is removed.
If you get a HostDataAccessDenied error when running preload or starting JBoss, it is because the file permissions on the directory /opt/nfast/kmdata/preload are wrong. It's probably because you (at some time) ran preload as another user, such as root or nfast.Load the card set so that keys protected by the card set could be generated (card set named ejbca):
$ /opt/nfast/bin/preload -c ejbca pause Loading cardsets: ejbca on modules 1 Loading `ejbca': Module 1 slot 0: `ejbca' #3 (`EJBCA card 3') Module 1 slot 0:- passphrase supplied - reading card Module 1 slot 0: `ejbca' #3 (`EJBCA card 3'): already read Module 1 slot 0: empty Module 1 slot 0: `ejbca' #2 (`EJBCA card 2') Module 1 slot 0:- passphrase supplied - reading card Card reading complete. Loading complete; now pausingBASH
Step 2 - Create PKCS#11 Keys on the nShield Module
You can create keys in HSM either with EJBCA using either the clientToolBox command line interface, or using the web based Admin UI. Using the CLI is a very fast and convenient way to verify that HSM connections are working.
All preloaded operator card sets (OCSs) has their own slot. It is not possible to predict the slot ID. But the label of the slot is the name of the OCS. The index of the slots depends on what order OCS are loaded, therefore it is recommended to reference slots using Slot/Token Label.
The below commands assume that EJBCA is installed in /opt/ejbca, JBoss in /opt/jboss and nShield in /opt/nfast. The software can be installed in other locations and you have to modify the commands accordingly.
To create PKCS#11 keys on the nShield module, using the command line interface:
Log in as the user that is running the application server. This user must be a member of the nfast group.
To create PKCS#11 keys, do the following:
Create 3 keys protected by the key set ejbca like this:
$ ~nfast/bin/preload -c ejbca /opt/ejbca/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 signKey TOKEN_LABEL:ejbca PKCS11 Token [SunPKCS11-NFastJava] Password: Creating certificate with entry signKey. $ ~nfast/bin/preload -c ejbca /opt/ejbca/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 defaultKey TOKEN_LABEL:ejbca Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key (RSAPrivate) on modules 1 PKCS11 Token [SunPKCS11-NFastJava] Password: Creating certificate with entry defaultKey. $ ~nfast/bin/preload -c ejbca /opt/ejbca/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 testKey TOKEN_LABEL:ejbca Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-27cfdae84bf4298f2dde83cd00980a81bcf095bf key (RSAPrivate) on modules 1 PKCS11 Token [SunPKCS11-NFastJava] Password: Creating certificate with entry testKey.BASH
Step 3 - Create a CA using the nShield HSM
To start EJBCA, preload must be running with the required key stores loaded. In this example this was done in step 2. Preload is now used to start JBoss/WildFly:
$ ~nfast/bin/preload -c ejbca $APPSRV_HOME/bin/standalone.sh To create a new CA, perform the following in the EJBCA Admin UI:
Create a new Crypto Token. Choose PKCS#11 as Type. Use ‘Slot/Token Label’ to reference the slot, and slot index may change depending on the order that OCS is loaded. Depending on the token type you either provide an authentication code or none. After creating the crypto token you should see the keys listed and you can test them by clicking the Test button.
Create a new CA, selecting the nShield Crypto Token, and selecting suitable algorithms and keys. See the EJBCA documentation for details o CA creation.
With the previously generated keys, a best practice example is to use signKey for cert- and CRL signing, testKey for tests and defaultKey for everything else (encryption):
If several CAs are sharing the same OCS (and hence slot) you should only create one Crypto Token in EJBCA and reference this crypto token from all CAs.
When preload is used no authentication code is needed to activate a CA. You could give any value for the authentication code when activating.
Module-, OCS- and Softcard protected Tokens
nCipher has (at least) three different types of tokens. You can use all different types of tokens with EJBCA. Module, Operator Card Set (OCS), or Softcard protected tokens.
OCS Protected Tokens
Using OCSP protected tokens the preload command must be used to load the OCS and keys.
If you get a HostDataAccessDenied error when running preload or starting the application server, it is because the file permissions on the directory /opt/nfast/kmdata/preload are wrong. It's probably because you (at some time) ran preload as another user, such as root or nfast.
Load the card set so that keys protected by the card set can be generated (in this example we named the OCS ejbca, but it can be named arbitrarily):
$ /opt/nfast/bin/preload -c ejbca pause
Loading cardsets:
ejbca on modules 1
Loading `ejbca':
Module 1 slot 0: `ejbca' #3 (`EJBCA card 3')
Module 1 slot 0:- passphrase supplied - reading card
Module 1 slot 0: `ejbca' #3 (`EJBCA card 3'): already read
Module 1 slot 0: empty
Module 1 slot 0: `ejbca' #2 (`EJBCA card 2')
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.
Loading complete; now pausingNot Using Preload
If a 1/N card set is used, then preload does not have to be used (but it can be used). For PKCS#11 simply do not use the preload command. The authentication code is now needed when activating the Crypto Token in EJBCA.
When using a 1/n OCS one card of the OCS must be inserted when activating a crypto token in EJBCA. If the OCS is persistent then the card cn be removed and you could then activate another crypto token by inserting its OCS. If the OCS is not persistent the cardset will unload itself as soon as the card is removed.
When using k/n OCS where k>1 you have to load all OCSs to be used with preload and then start the application server also with preload.
Example:
$ ~nfast/bin/preload -c 2of3_0 pause
-- follow instruction to insert cards and enter pins. --
-- then press ctr-z --
$ bg
$ ~nfast/bin/preload -c 2of3_1 exit
-- follow instruction to insert cards and enter pins. –Using More Than One OCS
It is possible to use more than one OCS. This is needed when you want different CAs protected by different OCSs. For this to work, you set the environment variable CKNFAST_LOADSHARING=1. This environment variable is also implicitly set when running with preload. To get a list of all available slots you can run the following command:
$ CKNFAST_LOADSHARING=1 ~nfast/bin/ckinfoSoftcard Protected Tokens
Softcard protected tokens behave similarly to OCS protected tokens with the only difference that the ppmk command is used instead of preload. For example:
$ /opt/nfast/bin/ppmk -m 1 -p ejbca pauseModule Protected Tokens
Module protected keys do not need a card set and no preload or ppmk commands need to be run. Hence no PIN code is needed to activate such a token. Module Protected keys are suitable as database protection keys in EJBCA.
Module protected keys are stored in a slot with the slot index 0. This slot is visible if the environment variable CKNFAST_NO_ACCELERATOR_SLOTS is set to 0. This variable can be set permanently for all PKCS#11 applications by adding the following to /opt/nfast/cknfastrc
# Enable module protected keys
CKNFAST_NO_ACCELERATOR_SLOTS=0
Except for using slot index 0 you have to use a PKCS#11 configuration file when creating keys. This is because the PKCS#11 attribute CKA_PRIVATE must be set to false to allow the key to be used without login. The file could look like this when using EJBCA clientToolBox:
Example:
name=NFastJava
library=/opt/nfast/toolkits/pkcs11/libcknfast.so
slotListIndex=0
attributes(*,CKO_PUBLIC_KEY,*) = {
CKA_TOKEN = false
}
attributes(*,CKO_PRIVATE_KEY,*) = {
CKA_TOKEN = true
CKA_PRIVATE = false
CKA_SIGN = true
CKA_DECRYPT = true
}
disabledMechanisms = {
CKM_SHA1_RSA_PKCS
CKM_SHA256_RSA_PKCS
CKM_SHA384_RSA_PKCS
CKM_SHA512_RSA_PKCS
CKM_MD2_RSA_PKCS
CKM_MD5_RSA_PKCS
CKM_DSA_SHA1
CKM_ECDSA_SHA1
} When adding it as an attributes file to be used in the Admin UI, the rows name, library and slotListIndex must be removed, as they are added by your selection in the UI. Hence you need two files, one for usage with clientToolBox and one for usage in the Admin UI.
Reference the fie used for the Admin UI in $EJBCA_HOME/conf/web.properties, by adding the following two lines, if the file is put in /opt/ejbca-custom/attrib/ModuleProtectedKey.conf.
cryptotoken.p11.attr.0.name=ModuleProtectedKey
cryptotoken.p11.attr.0.file=/opt/ejbca-custom/attrib/ModuleProtectedKey.confBuild and redeploy EJBCA
cd /opt/ejbca
ant -q clean deployearLoad Balancing
If you want to use the Loadsharing with multiple modules, be it PCI cards of NetHSM's then you must ensure you have a 1/N OCS and the N quorum to be able to have enough cards to be inserted in every HSM you want to load balance the key at server/CA start up when logging in. The same security world got to be loaded in all modules participating.
After setting up the first netHSM, do the following on the second:
- Use the panel of the second netHSM to configure the rfs
- Use the panel of the second netHSM to load the security world
- Use the panel of the second netHSM to configure clients
- on each client run: /opt/nfast/bin/nethsmenroll
With load balancing, you need to have CKNFAST_LOADSHARING=1.
If preload is used fail-over to the other HSM, if one of the HSMs is broken, is not working.
Example of starting jboss:
ejbca@host:/usr/local/ejbca> CKNFAST_LOADSHARING=1 ../jboss/bin/standalone.shWhen activating a CA you need a smart card from the OCS of the corresponding slot inserted in both HSMs. The OCS got to be 1/n since preload can not be used.
Support for Elliptic Curve Cryptography
If you want to generate elliptic curve (EC) keys such as secp256r1, and use the ECDSA signature algorithm, you need to buy a license from nCipher. When you try to generate an EC key in EJBCA without a license installed on the HSM, you get an error message similar to "Algorithm EC was not recognized".