nCipher nShield/netHSM

This section describes how the nShield card from nCipher is used.
First the card has to be installed and admin and operator card sets has to be created. This is described in step 1.
Step 2 describes environments variables that must be set before generating keys and installing a new CA.
Step 3-5 describe PKCS#11 keys are generated and how different CAs within an installation is configured to use these keys. In earlier versions of this manual it was also described how the nCipher JCA provider could be used by EJBCA. This has been removed since PKCS#11 keys are better in every respect.

Installation Instructions

Step 1. Install the nShield card

  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:

    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 
  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. Press the Clear button 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 is wrong. It's probably because you (sometime) 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. Setup the environment
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 that should be used on the nShield card

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

  2. 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 a new CA in the web GUI of EJBCA

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 0 is used to indicate module protection. The only other thing except using slot 0 you have to do is to use a configuration file when creating the key. The file could look like this:

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
} 

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