The following covers how the nCipher nShield card is installed and used.

Installation Instructions

Step 1. Install the nShield Card

To install the nShield Card and create admin and operator card sets, do the following:

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:

nfast@donny:/home/lars/work$ /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
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.
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

$

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 is wrong. It's probably because you (sometime) 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 pausing

Step 2. Setup Environment

To set environments variables required before generating keys and installing a new CA, do the following.

Login as the user that is running the application server. This user must be a member of the nfast group.

The following environment variables should be set for this user:

JAVA_HOME (/usr/local/jdk1.6.0_16 or similar)
APPSRV_HOME (/home/jboss/jboss-5.1.0.GA or similar)
EJBCA_HOME (/home/jboss/ejbca or similar)
NFAST_HOME (/opt/nfast)

Step 3. Create PKCS#11 Keys Used on nShield card

To create the PKCS#11 keys that should be used on the nShield card, do the following:

Start a new window and login as the same user (jboss user).

An ECC key could not be used with preload (at least not the curve secp160r1). Such a key is generated OK and could be used as long as the current preload is running. But if all preload processes are stopped and then if then preload is restarted the key could not be used. This means that ECC could only be used with a 1/n OCS.
Now 3 keys protected by the key set ejbca are created like this:

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1

Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1

PKCS11 Token [SunPKCS11-NFastJava] Password:

Creating certificate with entry default.

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1

Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key (RSAPrivate) on modules 1

Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1

PKCS11 Token [SunPKCS11-NFastJava] Password:

Creating certificate with entry crypt.

$ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1

Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-27cfdae84bf4298f2dde83cd00980a81bcf095bf key (RSAPrivate) on modules 1

Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1

PKCS11 Token [SunPKCS11-NFastJava] Password:

Creating certificate with entry test.

Step 4. Start EJBCA with 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

Step 5. Create New CA

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

Choose PKCS#11 as CA Token Type.

Properties are defined according to the Generic PKCS#11 provider section above.

All preloaded operator card sets (OCSs) has its own slot. It is not possible to predict the slot ID. But the index of the slot in the slot list is predictable. slotListIndex must therefore be used. If only one OCS is preloaded this index is always 1.

If several CAs are sharing the same OCS (and hence slot) each key (identified by a key label) may only be used for one CA but the test key. Same test key could be used for all CAs.

Example with previous generated keys where signRoot is used for CAs signing, and defaultRoot is used for everything else (encryption):

When preload is used no authentication code is needed to activate a CA. You could give any value for the authentication code when activating. The pin property could be used in the configuration to automatically activate a CA. The value of this property could be anything.

defaultKey defaultRoot
testKey test
keyEncryptKey cryptRoot
hardTokenEncrypt cryptRoot
pin dummy
slotLabelType SLOT_INDEX
slotLabelValue 1
sharedLibrary /opt/nfast/toolkits/pkcs11/libcknfast.so 

Using Module Protected Keys

Module protected keys do not need an operator card set. Hence no PIN code is needed to active such a key. A CA could be configured to use a keystore with module protected keys.

When using PKCS#11 slot index 0 is used to indicate module protection. The only other thing except using slot index 0 you have to do is to use a configuration file when creating the key. The file could look like this when using clientToolBox:

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

Not Using Preload

If a 1/N card set is used, then preload don't have to be used (but it can be used). If preload is not used, then jboss could be made to start automatically at boot time.

For PKCS#11 simply do not use the preload command. The authentication code is now needed when activating the CA.

Using More Than One OCS

It is also possible to use more than one OCS. This is needed when you want different CAs protected by different OCSs.

The key to get this working is to 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 do:

$ CKNFAST_LOADSHARING=1 ~nfast/bin/ckinfo
PKCS#11 library CK_INFO
       interface version 2.01
                   flags 0
          manufacturerID "nCipher Corp. Ltd               "
      libraryDescription "nCipher PKCS#11 1.58.48         "
  implementation version 1.58
 
slots[0] CK_SLOT_INFO
         slotDescription "                                                                "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 5
                   flags & CKF_TOKEN_PRESENT
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[0] CK_TOKEN_INFO
                   label "loadshared accelerator          "
          manufacturerID "nCipher Corp. Ltd               "
                   model "                "
            serialNumber "                "
                   flags 201
                   flags & CKF_RNG
                   flags & CKF_DUAL_CRYPTO_OPERATIONS
       ulMaxSessionCount 1024
     ulMaxRwSessionCount 1024
             ulMaxPinLen 18446744073709551615
             ulMinPinLen 0
     ulTotalPublicMemory CK_UNAVAILABLE_INFORMATION
      ulFreePublicMemory CK_UNAVAILABLE_INFORMATION
    ulTotalPrivateMemory CK_UNAVAILABLE_INFORMATION
     ulFreePrivateMemory CK_UNAVAILABLE_INFORMATION
        hardware version 0.00
        firmware version 0.00
                 utcTime "                "
 
slots[1] CK_SLOT_INFO
         slotDescription "1of2_0                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[1] Token not present
slots[2] CK_SLOT_INFO
         slotDescription "2of3_0                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[2] Token not present
slots[3] CK_SLOT_INFO
         slotDescription "ejbca                                                           "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[3] Token not present
slots[4] CK_SLOT_INFO
         slotDescription "2of3_1                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 6
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[4] Token not present
slots[5] CK_SLOT_INFO
         slotDescription "1of2_1                                                          "
          manufacturerID "nCipher Corp. Ltd               "
                   flags 7
                   flags & CKF_TOKEN_PRESENT
                   flags & CKF_REMOVABLE_DEVICE
                   flags & CKF_HW_SLOT
        hardware version 0.00
        firmware version 0.00
 
 
slots[5] CK_TOKEN_INFO
                   label "1of2_1                          "
          manufacturerID "nCipher Corp. Ltd               "
                   model "                "
            serialNumber "ee6071c52a77370c"
                   flags 20D
                   flags & CKF_RNG
                   flags & CKF_LOGIN_REQUIRED
                   flags & CKF_USER_PIN_INITIALIZED
                   flags & CKF_DUAL_CRYPTO_OPERATIONS
       ulMaxSessionCount 1024
     ulMaxRwSessionCount 1024
             ulMaxPinLen 18446744073709551615
             ulMinPinLen 0
     ulTotalPublicMemory CK_UNAVAILABLE_INFORMATION
      ulFreePublicMemory CK_UNAVAILABLE_INFORMATION
    ulTotalPrivateMemory CK_UNAVAILABLE_INFORMATION
     ulFreePrivateMemory CK_UNAVAILABLE_INFORMATION
        hardware version 0.00
        firmware version 0.00
                 utcTime "                " 

You then got to identify your OCSs with the slot index. The label in the list gives the name you gave to your OCS when creating it. Then you get the slot list index from the x in slot[x]. Use this for slotListIndex in the CA properties.

When using a 1/n OCS one card of the OCS must be inserted when activating a CA. If the OCS is persistent then the card could be removed and you could then activate another CA by inserting its OCS.

To make the OCS persistent use the -p argument at createocs time, if this is not the case as soon as the card is removed then the cardset will unload itself.

When using k/n OCS where k>1 you got 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. -- 

When the application server then is started with preload, CAs defined for slot list index 2 and 4 could be activated. When activating a CA when running preload no PIN has to be given. Also when the application server is started with preload then only CAs of preloaded slots could be activated (not preloaded 1/n slots could not be used).

nCipher Load 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.
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. Preload implicitly sets CKNFAST_LOADSHARING.

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

When 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.
Sample catoken.properties for generating the initial ManagementCA on the netHSM.

defaultKey defaultKey
certSignKey defaultSign
crlSignKey defaultSign
testKey testKey
sharedLibrary /opt/nfast/toolkits/pkcs11/libcknfast.so
slotLabelType=SLOT_INDEX
slotLabelValue 1