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.

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:

1. 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.

2. Login as the nfast user: sudo su nfast

3. Set the nCipher box to initialization mode by setting the switch to mode I.

4. Clear the nCipher box by pressing the reset button on the device.

5. 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 gen1AIF 

6. Create 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 = 6807e0b031c4f797b739ec33ca7dba05279cf54f

   The -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.

7. Change mode on the switch on the device to mode O.

8. Click Clear again.

9. 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

   $ 

   This 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.

10. 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 pausing 

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:

1. 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. 

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:

To create a new CA, perform the following in the EJBCA Admin UI:

1. 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.

2. Create a new CA, selecting the nShield Crypto Token, and selecting suitable algorithms and keys. See the EJBCA documentation for details o CA creation.

   1. 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.

OCS Protected Tokens

Using OCSP protected tokens the preload command must be used to load the OCS and keys.

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):

Not 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:

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:

Softcard 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:

Module 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

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:

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.

Build and redeploy EJBCA