Installing the software

This chapter describes how to install the Security World Software on the host computer.

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. See the User Guide for your module and operating system for more about creating a Security World and the appropriate card sets, and further configuration or setup tasks.

Installing the Security World Software on Windows

For information about configuring silent installations and uninstallations on Windows, see the User Guide.

For a regular installation:

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 Security World 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, please consult the SNMP monitoring agent section in the User Guide for your module and operating system.

    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%

  10. Stop the nFast Server service.

  11. 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.

  12. 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.

  13. Start the nFast Server service.

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

  15. 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.

You may additionally need to do the following after you have installed the software:

  • In Windows Device Manager > Network adapters, select the appropriate module.

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

Installing the Security World Software on Linux

  1. Sign in as a user with root privileges.

  2. Mount the DVD/ISO image.

  3. Open a terminal window, and change to the root directory.

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

    <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

    Install all the software bundles by running tar:

    tar -xf <disc-name>/linux/<ver>/<file>.tar.gz

    From .rpm

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

      rpm --import disc-name/linux-rpms/<ver>/pubkey.asc

    2. Verify that the .rpm files are signed by Entrust:

      rpm --checksig <disc-name>/linux-rpms/<ver>/<file>.rpm

    3. Install all the software bundles by running rpm.

      If a subset of the packages is already installed and you have to install more packages, uninstall the installed packages (see Uninstalling Security World software), then install all the .rpm packages that you need from fresh.

      You must install the hwsp package first. If you have to re-install hwsp, uninstall it last, then re-install it first.

      rpm -i disc-name/linux-rpms/<ver>/<file>.rpm

  5. To use an nShield module with your Linux system, you must build a kernel driver. Entrust supplies the source to the NFP and a makefile for building the driver as a loadable module.

    The kernel level driver is installed as part of the hwsp bundle. To build the driver with the supplied makefile, you must have the correct headers installed for the kernel that you are running. They must be headers for the same version of the kernel and must contain the kernel configuration options with which your kernel was built. You must also have appropriate versions of gcc, make, and your C library’s development package.

    The configuration script looks for the kernel headers in the default directory /lib/modules/'<uname -r>'/build/include/. If your kernel headers are located in a different directory, set the KERNEL_HEADERS environment variable so that they are in $KERNEL_HEADERS/include/. Historically, the headers have resided in /usr/src/linux/include/. If the headers for your kernel are not already installed, install them from your Linux distribution disc, or contact your kernel supplier.

    Build the driver as a loadable kernel module. When you have ensured the correct headers are in place, perform the following steps to use the makefile:

    1. Change directory to the nShield PCI driver directory by running the command:

      # cd /opt/nfast/driver-nshield5

    2. Make the driver by running the command:

      # make

      This produces a driver file that is automatically loaded as part of the normal installation process.

  6. Run the install script by using the following command:

    /opt/nfast/sbin/install

    The install script will automatically run the 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 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.

  7. Sign in to your normal account.

  8. Add /opt/nfast/bin to your PATH system variable:

    Bourne shell

    PATH=/opt/nfast/bin:$PATH
export PATH

    C shell

    setenv PATH /opt/nfast/bin:$PATH

  9. 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).

Problems during installation and commissioning

If problems are encountered when installing or commissioning an nShield HSM which prevent services from starting it will not be possible to use any of the debugging and logging tools described in Checking the installation

In this situation the command hsmdiagnose may help identify network and hardware issues that are preventing the system from starting.

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

hsmdiagnose

The command takes no parameters:

When the command is executed it will run a series of diagnostics tests and store the results in a file on the client PC. The information in the file is primarily intended for use by Entrust Support but you may be able to use the information to diagnose the issue yourself. If you are unable to do so, contact Entrust Support and send them a copy of the results file.