nShield Edge v12.81 User Guide (Windows)

Introduction

Read this guide if …​

Read this guide if you need to configure or manage:

  • An Entrust nShield Solo or nShield Solo XC or nShield Edge Hardware Security Module (HSM).

  • An associated Security World. nShield hardware security modules use the Security World paradigm to provide a secure environment for all your HSM and key management operations.

All nShield HSMs support standard cryptography frameworks and integrate with many standards based products.

This guide assumes that:

  • You are familiar with the basic concepts of cryptography and Public Key Infrastructure (PKI)

  • You have read the Installation Guide.

  • You have installed your nShield Solo or nShield SoloXC, nShield5s or nShield Edge.

Throughout this guide, the term Installation Guide refers to the particular Installation Guide for your product.

Terminology

Model numbers

Model numbering conventions are used to distinguish different nShield hardware security devices. In the table below n represents any single-digit integer.

Model number Used for

nC3nnnE-nnn, nC4nnnE-nnn

nShield Solo PCIe

nC30n5E-nnn, nC40n5E-nnn

nShield Solo XC PCIe

nC30nnU-10, nC40nnU-10

nShield Edge

Security World Software

The hardserver software controls communication between applications and Entrust nShield product line HSMs, which may be installed locally or remotely. It runs as a service on the host computer.

The Security World for nShield is a collection of programs and utilities, including the hardserver, supplied by Entrust to install and maintain your nShield security system.

The Edge is supplied with the latest version of the HSM firmware installed. For more information about:

Software architecture

The software, firmware and utilities have version numbers and there is also a version number for the World which refers to the World data that is stored in encrypted form on the client computer, typically in the NFAST_KMDATA directory or on the RFS. This data includes information concerning the World itself and also concerning each key that was created within that World. The World version created is determined by the version numbers of the software and firmware used when it was first created, see Creating and managing a Security World.

The latest World version is version 3. You can query the version of the World loaded on your system by using the command kmfile-dump.

Default directories

The default locations for Security World Software and program data directories on English-language systems are summarized in the following table:

Directory name Environment variable Windows Server 2016 or later

nShield Installation

NFAST_HOME

C:\Program Files\nCipher\nfast

Key Management Data

NFAST_KMDATA

C:\ProgramData\nCipher\Key Management Data

Dynamic Feature Certificates

NFAST_CERTDIR

C:\ProgramData\nCipher\Feature Certificates

Static Feature Certificates

%NFAST_KMDATA%\hsm-ESN\feature

Log Files

NFAST_LOGDIR

C:\ProgramData\nCipher\Log Files

User Log Files

NFAST_USER_LOGDIR

C:\Users\<user>\nshieldlogs

Remote Static Feature Certificates

%NFAST_KMDATA%\hsm-ESN\features

Remote Dynamic Feature Certificates

%NFAST_KMDATA%\hsm-ESN\features

By default, the Windows C:\ProgramData\ directory is a hidden directory. To see this directory and its contents, you must enable the display of hidden files and directories in the View settings of the Folder Options.
Dynamic feature certificates must be stored in the directory stated above. The directory shown for static feature certificates is an example location. You can store those certificates in any directory and provide the appropriate path when using the Feature Enable Tool. However, you must not store static feature certificates in the dynamic features certificates directory.

The absolute paths to the Security World Software installation directory and program data directories are stored in the indicated nShield environment variables at the time of installation. If you are unsure of the location of any of these directories, check the path set in the environment variable.

The instructions in this guide refer to the locations of the software installation and program data directories by their names (for example, Key Management Data) or nShield environment variable names enclosed with percent signs (for example, %NFAST_KMDATA%).

If the software has been installed into a non-default location, ensure that the associated nShield environment variables are re-set with the correct paths for your installation.

With previous versions of Security World Software, the Key Management Data directory was located by default in C:\nfast\kmdata, the Feature Certificates directory was located by default in C:\nfast\fem, and the Log Files directory was located by default in C:\nfast\log.

Utility help options

Unless noted, all the executable utilities provided in the bin subdirectory of your nShield installation have the following standard help options:

  • -h|--help displays help for the utility

  • -v|--version displays the version number of the utility

  • -u|--usage displays a brief usage summary for the utility.

Setting the PATH for nShield utilities

It is recommended that the PATH environment variable be changed to include <%NFAST_HOME%\bin> (usually C:\Program Files\nCipher\nfast\bin).

This is the directory in the nShield installation that contains the nShield command-line utilities and some DLLs.

This will allow all the nShield command-line utilities to be run without the need to type the full path, e.g. running enquiry instead of <%NFAST_HOME%\bin\enquiry>.

<%NFAST_HOME%\bin> must be set in the PATH in order to use the OpenSSL module in the Python that is bundled with nShield.

The Python bundled with nShield is located in a separate directory %NFAST_HOME\python\bin (usually C:\Program Files\nCipher\nfast\python\bin). If using the nShield Python, you may additionally want to add this directory to the PATH environment variable so that you can run the nShield python as just the python command. You may not want to do this if you are also using other Python installations on the same machine.

Further information

This guide forms one part of the information and support provided by Entrust.

If you have installed the Java Developer component, the Java Generic Stub classes, nCipherKM JCA/JCE provider classes, and Java Key Management classes are supplied with HTML documentation in standard Javadoc format, which is installed in the appropriate nfast\java directory when you install these classes.

Release notes containing the latest information about your product are available in the release directory of your installation media.

We strongly recommend familiarizing yourself with the information provided in the release notes before using any hardware and software related to your product.

Security advisories

If Entrust becomes aware of a security issue affecting nShield HSMs, Entrust will publish a security advisory to customers. The security advisory will describe the issue and provide recommended actions. In some circumstances the advisory may recommend you upgrade the nShield firmware and or nShield Connect image file. In this situation you will need to re-present a quorum of administrator smart cards to the HSM to reload a Security World. As such, deployment and maintenance of your HSMs should consider the procedures and actions required to upgrade devices in the field.

The Remote Administration feature supports remote firmware upgrade of nShield Solo, nShield Solo XC, nShield Connect and remote ACS card presentation.

We recommend that you monitor the Announcements & Security Notices section on Entrust nShield Support, https://nshieldsupport.entrust.com, where any announcement of nShield Security Advisories will be made.

Recycling and disposal information

For recycling and disposal guidance, see the nShield product’s Warnings and Cautions documentation.