Integrating the Entrust nShield HSM and OneSpan Authentication Server requires to integrate the HSM with OneSpan Authentication Server Framework. This requires to sign the OneSpan Authentication Server client as an SEE machine, install the SEE machine, and configure the module accordingly.
The signed OneSpan Authentication Server SEE machine module for Entrust nShield HSMs, supporting both the SEE unrestricted and restricted activation features, are part of the OneSpan Authentication Server package. We recommend to copy and use the respective file to the /opt/nfast/kmdata folder.
Entrust nShield 5. The files for this HSM type are located in installation_image_root_folder/Software/HSM-NCIPHER/n5/ and include:
03009658-ONESPANNV.pem: OneSpan certificate.
aal2sdk-signed.cs5: Signed OneSpan Authentication Server CSEE module.
Entrust nShield XC. The files for this HSM type are located in installation_image_root_folder/Software/HSM-NCIPHER/xc/ and include:
seemach_ppc-xc.sar: Signed OneSpan Authentication Server SEE machine for Entrust nShield XC HSMs.
seemach_hash.txt: Hash of the OneSpan SEE code signing key used to sign the SEE machine.
seemach.cert: ADDER certificate necessary if using the signed SEE machine with the SEE restricted activation feature.
build_userdata.sh: Example script to generate a signed user data file, copy the signed SEE machine in the nfast key management data directory, and copy the ADDER certificate in the nfast feature certificates directory.
We strongly recommend to use the provided SEE machine that is already signed by OneSpan.
To install and configure the CSEE module (nShield 5)
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.
Sing and package the user data:
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, 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 the user data file. The machine key should match the certificate:
tct2 --sign-and-pack --infile=userdata.dat --key=seesigningkey --machine-key=machine_key --outfile=userdata.sar
Sign and load 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
Open the configuration file located in the /opt/nfast/kmdata/config folder 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 file referenced in the path should be the aal2sdk-signedex.cs5 file signed with your signing key in the previous step.
Force the HSM to load the new configuration:
cfg-reread
nopclearfail -c -m module_id
Note that it can take a few minutes to load the SEE machine.
Test if 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]
To install and configure the SEE machine (nShield XC)
Navigate to the location of the SEE machine.
Generate the SEE code signing key with the name seesigningkey. This is the key name expected by the signing script used by the SEE module:
generatekey --generate seeinteg type=rsa size=2048 pubexp= recovery=yes nvram=no plainname=seesigningkey
The SEE code signing key will be created as the following file and is protected by the OCS: /opt/nfast/kmdata/local/key_seeinteg_seesigningkey
Do one of the following:
(RECOMMENDED) Copy the signed SEE machine (seemach_ppc.sar) provided by OneSpan to the client machine that will load the SEE machine in the nfast key management data directory:
cp seemach_ppc.sar /opt/nfast/kmdata
Create your own signed SEE machine:
Sign the SEE module file using the SEE code signing key:
tct2 --sign --key=seesigningkey --is-machine --machine-type=PowerPCELF --module=moduleID ‑o aal2sdk.sig aal2sdk.elf
where moduleID is the identifier of the module with which you want to perform the signing operation. This module identifier is likely 1.
You can also use the environmental variable ${moduleID} as the moduleID. If you do, the command will automatically use the appropriate module ID from your environment.
Generate the signed SEE machine file, i.e., seemach_ppc.sar:
tct2 --pack --module=moduleID -o "/opt/nfast/kmdata/seemach_ppc.sar" --infile=aal2sdk.sxf --sigfile=aal2sdk.sig
This command will generate the following SEE machine file: /opt/nfast/kmdata/seemach_ppc.sar
Sign and package the user data:
Generate a dummy user data file named userdata.dat:
echo 'Dummy data' > userdata.dat
Generate a signed user data file with the SEE code signing key. To do so, run the following two commands:
tct2 --sign --key seesigningkey --machine-key-ident=seesigningkey --machine-type=PowerPCELF ‑‑module=moduleID -o userdata.sig userdata.dat
tct2 --pack --module=moduleID -o "/opt/nfast/kmdata/userdata.sar" --infile=userdata.dat --sigfile=userdata.sig
Delete the userdata.dat and userdata.sig files for security reasons.
The OneSpan Authentication Server instance is now fully configured as an SEE machine. As such, it can now be integrated with theEntrust nShield HSM.