Install the Security World software

This chapter describes how to install the Security World Software on the computer, client, or RFS associated with your nShield HSM.

If you are upgrading an existing installation make sure you have made backup copies of any Security World data files and nShield 5s ssh-keys before you continue.

After you have installed the software, you must complete further Security World creation, configuration and setup tasks before you can use your nShield environment to protect and manage your keys.

Installing the Security World Software on Windows

For information about configuring silent installations and uninstallations on Windows, see Using silent installations.

For a regular installation:

(nShield 5s only) Installing Security World software on Windows via Remote Desktop Connection can result in a brief loss of RDP connection. If this happens, it will happen during the Status: part of the installation, towards the end. When the session reconnects, the installation carries on until completion.

  1. Sign in as an Administrator or as a user with local administrator rights.

    If the Found New Hardware Wizard appears and prompts you to install drivers, cancel this notification, and continue to install the Security World Software as normal. Drivers are installed during the installation of the Security World Software.

  2. Place the Security World Software installation media in the optical disc drive.

  3. Launch setup.msi manually when prompted.

  4. Follow the onscreen instructions.

  5. Accept the license terms and select Next to continue.

  6. Specify the installation directory and select Next to continue.

  7. Select all the components required for installation.

    By default, all components are selected. Use the drop-down menu to deselect the components that you do not want to install. nShield Hardware Support and Core Tools are necessary to install the Security World Software.

    See Software packages on the installation media for more about the component bundles and the additional software supplied on your installation media.

  8. Select Install.

    The selected components are installed in the installation directory chosen above. The installer creates links to the following nShield Cryptographic Service Provider (CSP) setup wizards as well as remote management tools under Start > Entrust or Entrust nShield Security World (depending on the version of Windows or Windows Server you are running):

    • If nShield CSPs (CAPI, CNG) was selected: 32bit CSP install wizard, which sets up CSPs for 32-bit applications

    • If nShield CSPs (CAPI, CNG) was selected: 64bit CSP install wizard, which sets up CSPs for 64-bit applications

    • If nShield CSPs (CAPI, CNG) was selected: CNG configuration wizard, which sets up the CNG providers

    • If nShield Java was selected: KeySafe, which runs the key management application

    • If nShield Remote Administration Client Tools was selected: Remote Administration Client, which runs the remote administration client

    If selected, the SNMP agent will be installed, but will not be added to the Services area in Control Panel > Administrative Tools of the target Windows machine. If you wish to install the SNMP agent as a service, consult the nShield SNMP Monitor v13.6.5 Install and User guide.

    (PCIe HSMs only) Do not run any CSP installation wizard before installing the module hardware.

  9. Select Finish to complete the installation.

    The following global variables are set upon install:

    • %NFAST_CERTDIR%

    • %NFAST_HOME%

    • %NFAST_KMDATA%

    • %NFAST_LOGDIR%

    • %NFAST_SERVICES_HOME% (nShield 5s only)

  10. Add C:\Program Files\nCipher\nfast\bin to the Windows system path.

  11. (nShield 5s only) If you are using an nShield 5s, complete the additional steps for nShield 5s.

  12. (PCIe HSMs only) If you are using a PCIe HSM, you might need to update the power saving settings:

    1. In Windows Device Manager > Security Accelerator (nShield Solo) or Windows Device Manager > Network adapters (nShield 5s), select the appropriate module.

    2. Under Properties > Power Management, deselect Allow the computer to turn off this device to save power.

Additional steps for nShield 5s

  1. Stop the nFast Server service.

  2. The nShield installer creates and enables an inbound rule called nShield 5s mDNS to allow UDP port 5353 for any program. This enables the discovery of nShield 5s modules. If enrollment fails to find any modules in the following step, check that this firewall rule is present and enabled; if it does not exist, create it manually and retry enrollment.

  3. Set up the secure communication channels between the host PC and the HSM:

    "%NFAST_HOME%\bin\hsmadmin" enroll

    The HSM must be in factory state or else the registered sshadmin key must be in place otherwise this command will fail. If you have a backup of your sshadmin key, you can restore it using hsmadmin keys restore. If this is not a first-time installation of this HSM, and the sshadmin key trusted by this HSM is no longer available, enter recovery mode and then retry enrollment.

    From firmware versions 13.5 onwards, the secure communication channels between the host PC and the HSM are protected by internally generated certificates. The hsmadmin enroll command automatically validates certificates as part of the enrollment process and produces a warning if it fails to find a certificate for any service. This warning is expected if the HSM:

    • is in recovery mode

    • is running a firmware version prior to 13.5

    • has been upgraded to a firmware version of 13.5 or later but has not performed a factory state operation since the upgrade.

    If you receive this warning in any other circumstance you should contact Entrust support.

  4. Start the nFast Server service.

  5. If Remote Administration is installed, also start the nFast Remote Administration service.

  6. Entrust recommends that you take a backup of your sshadmin key with hsmadmin keys backup path\to\backup_key for backups that will be restored to the same machine. Note that this key will not be usable on another machine or if the OS is re-installed as it has protections tied to the local machine. For backups that may be restored to a different machine or re-installed OS, use hsmadmin keys backup --passphrase path\to\backup_key to protect the key with a user-supplied passphrase. Replace path\to\backup_key with the actual path to where the backup key should be written in the example commands above.

Install the Security World software on Linux

  1. Sign in and enter a root shell.

  2. Mount the DVD/ISO image.

  3. Extract the required files if you are using .tar or install the rpm packages.

    <disc-name>

    Name of the mount point of the installation media
    <ver>

    Architecture of the operating system, for example, i386 or amd64
    <file.tar>

    Name of the .tar.gz file for the component
    <file.rpm>

    Name of the .rpm file for the component

From tar files

If you already have an earlier version of the nShield software installed you must run the uninstall script before proceeding with a tar installation:

bash /opt/nfast/sbin/install -u

Change to the directory containing the tar.gz packages:

cd <disc-name>/linux/ver/

Install the required software components using tar:

tar -C / -xf <file>.tar.gz
You must always unpack the hwsp.tar.gz archive for new installations.

Linux PCI driver installation

If you are using nShield PCI cards you must compile the PCI drivers. To do this you must first install the kernel development tooling and headers for your running kernel.

Check that you have the correct kernel headers:

ls -l /lib/modules/$(uname -r)/build

The above should print a symlink to your kernel headers. If you see No such file or directory you will need to install the correct kernel development packages for your OS.

Compile drivers for nShield Solo+ or SoloXC:

cd /opt/nfast/driver
make clean
make
make install

Compile drivers for nShield5:

cd /opt/nfast/driver-nshield5
make clean
make
make install

Finally, You must run the nShield install script:

bash /opt/nfast/sbin/install

From RPM packages

Change to the RPMs folder:

cd <disc-name>/linux-rpms/<ver>/

Import the Entrust RPM signing public key in <disc-name>/linux-rpms/<ver>/pubkey.asc into rpm:

rpm --import pubkey.asc

Verify that each .rpm file is signed by Entrust:

rpm --checksig <file>.rpm

Install the required software and driver packages by running yum or dnf.

dnf install --repofrompath=nc,$(pwd) <component1> <componentN>

For example:

dnf install --repofrompath=nc,$(pwd) nShield-ctls nShield-raserv

Yum/dnf should print output similar to:

$ dnf install --repofrompath=nc,`pwd` nShield-raserv nShield-ctls
Added nc repo from /cdrom/linux-rpms/14.0.0/x86_64
Last metadata expiration check: 0:04:04 ago on Mon Dec  2 11:08:31 2024.
Dependencies resolved.
======================================================================================
 Package            Arch       Version                               Repository  Size
======================================================================================
Installing:
 nShield-ctls       x86_64     14.0.0-1.1732201800.6eef148ee17       nc          58 M
 nShield-raserv     x86_64     14.0.0-1.1732201800.6eef148ee17       nc         344 k
Installing dependencies:
 nShield-hwsp       x86_64     14.0.0-1.1732201800.6eef148ee17       nc          71 M
 net-tools          x86_64     2.0-0.52.20160912git.el8              baseos     321 k
 procps-ng          x86_64     3.3.15-14.el8                         baseos     329 k

Transaction Summary
======================================================================================
Install  5 Packages

Total size: 130 M
Total download size: 650 k
Installed size: 558 M
Is this ok [y/N]:
If you require them, you can include all the optional RPM packages (such as javasp, raserv or ncsnmp) in the same command line.
If you require PCI drivers to be built and installed you must include the nShield-driver-nfp RPM for Solo+/SoloXC modules or the nShield-driver-nshield5 RPM for nShield5 modules. This will install the required kernel packages and compile the PCI drivers. If however you change your kernel at a later date, you must re-build the drivers manually as explained in Linux PCI driver installation above.

If you are upgrading from an earlier version of nShield you will not need to manually uninstall any RPMs before upgrading.

If you are installing several RPM packages at the same time you may notice the install script is executed multiple times. This is normal and does not indicate a problem.

Additional steps for nShield 5s

The RPMs and install script will automatically run the /opt/nfast/bin/hsmadmin enroll command. From firmware versions 13.5 onwards the secure communication channels between the host PC and the HSM are protected by internally generated certificates. The /opt/nfast/bin/hsmadmin enroll command automatically validates certificates as part of the enrollment process and produces a warning if it fails to find a certificate for any service. This warning is expected if the HSM:

  • is in recovery mode

  • is running a firmware version prior to 13.5

  • has been upgraded to a firmware version of 13.5 or later but has not performed a factory state operation since the upgrade.

    If you receive this warning in any other circumstance you should contact Entrust support.

(nShield 5s only) Entrust recommends that you take a backup of your sshadmin key.

For example, you could use hsmadmin keys backup /root/.ssh/id_nshield5_sshadmin for backups that will be restored to the same machine. If the path /root/.ssh/id_nshield5_sshadmin is used, and the sshadmin key is missing from the usual installed location under /opt/nfast, then that key will be used automatically when running the nShield install script.

Note that this key will not be usable on another machine or if the OS is re-installed as it has protections tied to the local machine. For backups that may be restored to a different machine or re-installed OS, use hsmadmin keys backup --passphrase /path/to/backup_key to protect the key with a user-supplied passphrase (replacing /path/to/backup_key with the actual path to where the backup key should be written).

After installing the software

After you have successfully installed the Security World Software, complete the following steps to finish preparing your HSM for use:

  1. Ensure that your public firewall is set up correctly.
    See Before you install the software.

  2. nShield 5s: If the SSH keys have not been set up, create the communication path between the host machine and the HSM, as described in Set up communication between host and module (nShield 5s HSMs).

    If you followed all the steps in the installation instructions when installing the software, this should already be set up.

  3. Network-attached HSMs: Perform the necessary basic HSM-client configuration tasks, as described in Basic HSM and remote file system (RFS) configuration.

  4. PCIe and USB HSMs: If necessary, perform additional software and HSM configuration tasks, as described in Client software and module configuration: PCIe and USB HSMs:

  5. Create and configure a Security World, as described in Create a new Security World.

  6. Create an OCS, as described in Creating Operator Card Sets (OCSs).

  7. Network-attached HSMs: Complete additional necessary HSM-client configuration tasks:

    1. To configure the unit so that it works with the client machine, see Configuring the nShield HSM to use the client.

    2. To configure client computers so that they work with the unit, see Configuring client computers to use the nShield HSM.

      For this release, you must generate a new client configuration file to take advantage of new functionality. To generate a new client configuration file, back up your existing configuration file and run cfg-mkdefault. This generates a template for the configuration file into which you can copy the settings from your old configuration file.

    3. To enable the TCP sockets for Java applications (including KeySafe), run the command:

      config-serverstartup -sp

      For more information, see Client configuration utilities.

      When all additional HSM configuration tasks are completed, you can:

      1. Stop and then restart the hardserver, as described in Stopping and restarting the hardserver.

      2. Test the installation and configuration.