Before you can use the Authentication Suite Server SDK SEE machine signed by OneSpan, you need to complete the following steps to be able to upload the SEE machine to the HSMs.
Loading the OneSpan certificate
To load the OneSpan certificate to the security world
Connect to your security world.
Type the following command to add the OneSpan certificate to your security world:
csadmin ids add certificate_file
Replace the following:
certificate_file. The name of the PEM file containing the OneSpan certificate including the full path.
Creating the user data file
To create the user data file (userdata.sar)
If you don't have one already, create a signingkey with the following command:
generatekey --generate seeinteg type=rsa size=2048 pubexp= recovery=yes nvram=no plainname=seesigningkey
In your RFS directory /opt/nfast/kmdata/local (%NFAST_KMDATA%\local on Windows), use the following command to create a userdata.dat file:
echo 'Dummy data' > userdata.dat
Use the following command to generate the .sar file from userdata. The machine key should match the certificate:
tct2 --sign-and-pack --infile=userdata.dat --key=seesigningkey --machine-key=machine_key --outfile=userdata.sar
This file will be used by the OneSpan Key Management Tool (manager-5) to bind your storage and transport keys with your current security world.
Previous versions of the Key Management Tool (4 or earlier) used to store the generated keys in the kmdata directory. They are now stored in the kmdata/local directory, where your userdata.sar file should also reside.
Signing and loading CSEE modules
To sign the CSEE module
Add a signature to the provided aal2sdk-signed.cs5 image file using the same signing key that was used to create the userdata.sar file:
csadmin image signextra --appname seeinteg --key seesigningkey --out ~/aal2sdk-signedex.cs5 ~/aal2sdk-signed.cs5
The steps to load the CSEE module depends on the version of the used firmware.
To load the CSEE module with firmware versions earlier than 13.9.5 (single-client use only)
Open the configuration file located in the /opt/nfast/kmdata/config folder (%NFAST_KMDATA%\hsm-your_hsm_esn\config on Windows) in a text editor.
Locate the [codesafe] section and add the module settings:
esn=[YOUR_HSM_ESN] enabled=yes image_file=[PATH_TO_CS5_IMAGE] worldid_pubname=onespanIf the [codesafe] section does not exist, you can add it before the [load_seemachine] section. The cs5 image referenced in the path should be the aal2sdk-signedex.cs5 file signed with your signing key in the previous step.
We recommend to put the cs5 image in your kmdata/local directory. The electronic serial number (ESN) of your HSM can be retrieved with the enquiry command if required.
Use the following commands to make the HSM read the new configuration and load it:
cfg-reread
nopclearfail -c -m module_id
Note that it can take a few minutes to load the SEE machine.
Use the following command to make sure the SEE machine is running:
csadmin list
You should see an output looking like this:
[YOUR_HSM_ESN] UUID State Name IP Address ----------------------------------------------------------------------------- [XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX] RUNNING aal2sdk [IP_ADRESS]
Multi-client use requires a CSEE module (cs5 file) that was created with Authentication Suite Server SDK 4.0.2.1 or later. It will not work with cs5 files from version 4.0.1.1 or 4.0.2.0.
To load the CSEE module with firmware version 13.9.5 and later (multi-client use possible)
If you were previously using the single client configuration (as described before), remove the [codesafe] section from the local config file on your client (/opt/nfast/kmdata/config/config on Linux and %NFAST_KMDATA%\hsm-your_hsm_esn\config\config on Windows).
On your HSM's Remote File System, copy the original nShield 5c configuration file (/opt/nfast/kmdata/hsm-esn/config/config on Linux and %PROGRAMDATA%\nCipher\Key Management Data\hsm-esn\config\config on Windows) to config.new in the same directory.
Open the config.new file in a text editor and change the [codesafe] section to have the following content (since the file will be pulled from the RFS volume for custom SEE machines, use only the filename and omit the path):
[codesafe] image_file=aal2sdk-signedex.cs5 seejobs_transport=plain worldid_pubname=onespan pull_rfs=yesPush the configuration to the HSM:
Linux:
cfg-pushnethsm -a nshield5c_ip_address -m module_number /opt/nfast/kmdata/hsm-esn/config/config.new
Windows:
cfg-pushnethsm -a nshield5c_ip_address -m module_number "%PROGRAMDATA%\nCipher\Key Management Data\hsm-esn\config\config.new"
Make the HSM read the new configuration and load it:
nopclearfail -m module_number --clear --wait
Note that it can take a few minutes to load the SEE machine.
Verify that the SEE machine has been correctly uploaded and is running:
appliance-cli -m module_number gethsmcs5stats
You should see an output looking like this:
{ "YOUR_ESN": { "succeeded": true, "data": { "cs_stats": { "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": { "State": "RUNNING", "Friendly Name": "aal2sdk", "Name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "IP": "xxxx::xxx:xxxx:xxxx:xxxx", "PID": xxx, "CPU use": xxxxx, "Memory use": xxxxxxx, "KMem use": xxxxxxx, "Link": { "name": "xxxxxxxxxx", "TX bytes": xxxxxxxxx, "RX bytes": xxxxxxxxx, "Total bytes": xxxxxxxxx }, "Logging enabled": true } }, "cs_enabled": true } } }You can now call the module from any client into your security world.