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)