MTG ERS to nShield HSMs Connection Guide

This page describes the process of connecting MTG ERS (CARA and/or KMS) to nShield HSMs via PKCS#11. The subsections below correspond to steps that must be followed top to bottom for successful connection. It is assumed that a healthy nShield setup is already present in the environment.

To learn how to setup nShield HSMs alongside the Entrust RFS Server, refer to the nShield’s official documentation.

Installing the Hardserver on the ERS Server(s)

Start with installing the necessary packages. Make sure to obtain the Security World ISO File. In case the HSM(s) were obtained from MTG AG as a reseller, MTG AG will provide all necessary packages.

  1. Prepare the mount directory and unpack the ISO:

    mkdir /mnt/secworld
unzip SecWorld_Lin64-13.3.2.iso.zip
mount SecWorld_Lin64-13.3.2.iso /mnt/secworld/

  2. Extract package files from the mounted image (ensure you’re in the root directory /):

    cd /
tar -vxf /mnt/secworld/linux/amd64/raserv.tar.gz
tar -vxf /mnt/secworld/linux/amd64/hwsp.tar.gz
tar -vxf /mnt/secworld/linux/amd64/ctls.tar.gz
tar -vxf /mnt/secworld/linux/amd64/ctd.tar.gz

  3. Run the installation script via /opt/nfast/sbin/install -d:

  4. Verify services are running:

    systemctl status nc_raserv.service
systemctl status nc_hardserver.service

Registering the Application Server with the HSM

This process can be completed on the RFS server.

  1. Copy the existing HSM config and update it:

    cp /opt/nfast/kmdata/$HSM_SERIAL_NUMBER/config/config \
   /opt/nfast/kmdata/$HSM_SERIAL_NUMBER/config/config.new

  2. Add a client entry under [hs_clients]:

    ## MY NEW APP
addr=$IP_ERS_SERVER
clientperm=unpriv
keyhash=5b00e88df8dcc8bc9b6f584683fae7a5582482d3
esn=

    The keyhash can be obtained from the ERS application server using:

    /opt/nfast/bin/enquiry

  3. Push the new config to the HSM:

    /opt/nfast/bin/cfg-pushnethsm -a $HSM_IP -p $HSM_PORT \
   /opt/nfast/kmdata/$HSM_SERIAL_NUMBER/config/config.new

  4. On successful run, the HSM pushes the configuration back to the RFS Server. You may check this by examining /opt/nfast/kmdata/$HSM_SERIAL_NUMBER/config/config for the changes that where made.

Registering the Application Server on the RFS Server

Add following entries under [remote_file_system] in /opt/nfast/kmdata/config/config on the RFS server:

-----
remote_ip=$IP_ERS_SERVER
remote_esn=
keyhash=$KEYHASH
native_path=/opt/nfast/nc-seemachines
volume=nc-seemachines
allow_read=yes
allow_write=no
allow_list=yes
is_directory=yes
is_text=no
-----
remote_ip=$IP_ERS_SERVER
remote_esn=
keyhash=$KEYHASH
native_path=/opt/nfast/custom-seemachines
volume=custom-seemachines
allow_read=yes
allow_write=no
allow_list=yes
is_directory=yes
is_text=no
-----
remote_ip=$IP_ERS_SERVER
remote_esn=
keyhash=$KEYHASH
native_path=/opt/nfast/kmdata/config/cardlist
volume=kmdata-config-cardlist
allow_read=yes
allow_write=no
allow_list=yes
is_directory=no
is_text=yes
-----
remote_ip=$IP_ERS_SERVER
remote_esn=
keyhash=$KEYHASH
native_path=/opt/nfast/kmdata/local
volume=kmdata-local
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no
-----
remote_ip=$IP_ERS_SERVER
remote_esn=
keyhash=$KEYHASH
native_path=/opt/nfast/kmdata/local/sync-store
volume=kmdata-backup
allow_read=yes
allow_write=yes
allow_list=yes
is_directory=yes
is_text=no

Refer to the ERS application server’s /opt/nfast/bin/enquiry output for the correct keyhash.

Adding the RFS Server to the ERS Application Server

On the ERS Server add the following under [rfs_sync_client] in /opt/nfast/kmdata/config/config:

remote_ip=$RFS_IP
remote_port=$RFS_PORT
use_kneti=no
local_esn=
remote_keyhash=$KEYHASH
remote_esn=

Find the RFS server’s keyhash using /opt/nfast/bin/enquiry.

Syncing Files from RFS Server

On the ERS application server, run:

/opt/nfast/bin/rfs-sync --commit

Verifying HSM Connectivity

Run the following command on the ERS application server, to verify connectivity to the HSM(s):

/opt/nfast/bin/enquiry

You should now see all configured HSMs listed in the output.

Configuring the ERS Services to use the nFast Hardserver

CARA

Add following environment variables to the config file /etc/opt/mtg-cara-ws-server/mtg-cara-ws-server.service.conf:

CKNFAST_LOADSHARING=true
CKNFAST_ASSUME_SINGLE_PROCESS=0

Additionally, set the PKCS#11 folder in the application properties of the service (/etc/opt/mtg-cara-ws-server/application.properties):

[...]

pkcs11Folder=/opt/nfast/toolkits/pkcs11

[...]

KMS

Add following environment variables to the config file /etc/opt/mtg-kms-server/mtg-kms-server.service.conf:

CKNFAST_LOADSHARING=true
CKNFAST_ASSUME_SINGLE_PROCESS=0

Login the KMS-UI with an Admin Account.

HSMs → Create →

HSM-Name: $HSM_NAME
Location: (Not important for PKCS11 connections, can choose what you want)
Address: /opt/nfast/toolkits/pkcs11/libcknfast.so
Type: PKCS11

Navigate to the Tenant to be used with the HSM and attach the HSM. Then, create an HSM Profile for the Tenant User that contains the Domain and Authentication Data.

That’s it! You should now be able to use MTG ERS products with nShield HSMs.