EzSign: Checking the HSM Configuration

Before configuring EzSign with an HSM it is worth performing a quick check that everything is working as expected and all libraries and passwords are correct

The steps below outline some steps that can be taken to verify everything is ready to go

HSM Status

The nCipher HSMs provide several commands for verifying the setup is correct

These utilities are normally located here:

On Linux/UNIX:

/opt/nfast/bin

On windows:

C:\Program Files (x86)\nCipher\nfast\bin

First run the enquiry command e.g. On Unix from a shell run:

./enquiry

On Windows, from a Command Prompt, run:

enquiry.exe

The output will be split into several sections:

  Server:

  ...

  Module #1:

  ...

And if there is more than one module configured you will also see headings for these, e.g.:

 Module #2:

 ...

etc.

The key things to note are that each of the module entries are showing:

mode operational

If there are no entries beneath the Server heading, first try starting the hardserver. On Unix:

/opt/nfast/sbin/init.d-ncipher start

On Windows, start the nFast Server service

HSM Test Tool

If all looks OK, download the Krestfield HSM Test tool from here

Run the tool as follows:

From a UNIX shell:

./hsmtest.sh

From a Windows Command Prompt:

hsmtest.bat

Krestfield HSM Test Tool

Enter PKCS#11 library path > /opt/nfast/toolkits/pkcs11/libcknfast-64.so  <-- Enter the full path to the PKCS#11 library
  PKCS#11 Token: Loading the PKCS#11 library: /opt/nfast/toolkits/pkcs11/libcknfast-64.so...
  PKCS#11 Token: Loaded PKCS#11 Driver /opt/nfast/toolkits/pkcs11/libcknfast-64.so OK

  HSM Driver loaded OK

  There are 2 slots:

  Slot: 0
   slotDescription:                                
   manufacturerID: nCipher Corp. Ltd       
   flags: CKF_TOKEN_PRESENT | CKF_HW_SLOT
   hardwareVersion: 0.00
   firmwareVersion: 0.00
  Slot: 1
   slotDescription: SFHSMTTOCS                           
   manufacturerID: nCipher Corp. Ltd       
   flags: CKF_TOKEN_PRESENT | CKF_REMOVABLE_DEVICE | CKF_HW_SLOT
   hardwareVersion: 0.00
   firmwareVersion: 0.00

Select Slot > 1 <-- Enter the slot number - normally 1 if an operatore card set is in use
 
  PKCS#11 Token: Opening session...
  PKCS#11 Token: Opened session for slot 1 OK
  HSM Session Opened OK. Session ID: 2251
  
Enter HSM OCS Passphrase > <-- Enter the operator cardset password and press enter

  PKCS#11 Token: Password provided, attempting logon...
  PKCS#11 Token: Logged on to Token

  Logged in OK. Configuration is good

This tool performs the same operations to connect to the HSM as EzSign. Therefore, if you see this success message, translating the values entered above into the following properties:

channel.1.tokenType=*This must be set to PKCS11*
channel.1.token.password=*Set this as the operator password (as entered above) via the Management Utility*
channel.1.token.pkcs11.library=*Set this to be the same path as entered above*
channel.1.token.pkcs11.slot=*Set this to be the same number slot as entered above*

e.g.

channel.1.tokenType=PKCS11
channel.1.token.password=Mt3WQvXz6fUy2yhpNC5ZBxCdPJWsy2Ol1QdLH3c1pogbHViP7oDeQA==
channel.1.token.pkcs11.library=/opt/nfast/toolkits/pkcs11/libcknfast-64.so
channel.1.token.pkcs11.slot=1

Should result in a successful HSM setup

Possible Errors

If when running the test tool you see the following:

Enter PKCS#11 library path > C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll
Using C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll

PKCS#11 Token: Loading the PKCS#11 library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll...
Token Exception: PKCS#11 Token: There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll Details: %1 is not a valid Win32 application.
C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll
There was an error checking the HSM: Token Exception: PKCS#11 Token: There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll Details: %1 is not a valid Win32 application.
C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll

I.e. an error such as:

There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-32.dll Details: %1 is not a valid Win32 application.

Or something similar such as:

no suitable image found

etc.

This indicates that you are either running a 64 bit JVM and attempting to load a 32 bit library - or vice versa. It could also indicate a corrupt library file. If the file cannot be read at all, this may indicate a permissions issue

And if you see the following output:

Enter PKCS#11 library path > C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll
Using C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll

PKCS#11 Token: Loading the PKCS#11 library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll...
Token Exception: PKCS#11 Token: There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll Details: CKR_FUNCTION_FAILED
There was an error checking the HSM: Token Exception: PKCS#11 Token: There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll Details: CKR_FUNCTION_FAILED

I.e. this error:

There was an error loading the library: C:/Program Files (x86)/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll Details: CKR_FUNCTION_FAILED

This indicates that your HSM is not setup correctly or the required services are not running (e.g. for nCipher if the hardserver is not running, you will see this error)