Using KeySafe

This section describes how to use the legacy Java-based nShield KeySafe. For documentation on the new generation product, see the nShield KeySafe 5 documents on https://nshielddocs.entrust.com/.

KeySafe provides a GUI based interface to perform many of the main tasks required to use an nShield Security World. This appendix describes KeySafe, the Security World management tool. It includes information about:

  • Starting KeySafe

  • Using the graphical user interface (GUI) for KeySafe

  • Using buttons to select and run operations

  • Using the keyboard to navigate KeySafe

  • KeySafe error reporting.

To perform Security World management, card-set management, and key management tasks using KeySafe, see the relevant chapters of this guide.

By default, KeySafe uses the same mechanisms and supports the same features and applications as the generatekey utility.

About KeySafe

When you use KeySafe to create cards or keys for network-attached HSMs, the data is written to the Key Management Data directory on the computer on which you run KeySafe. An nShield HSM can only use this data when it is transferred to the remote file system (if it is on a different computer), from where it is loaded automatically onto the unit. For this reason, you may find it most convenient to run KeySafe on the same computer as the remote file system.

Although you can use KeySafe to generate keys, it is your chosen application that actually uses them. You do not need KeySafe to make use of the keys that are protected by the Security World. For example, if you share a Security World across several network-attached HSMs or across several host computers for PCIe or USB HSMs, you do not need to install KeySafe on every computer. To manage the Security World from a single computer, you can install KeySafe on just that one computer even though you are using the Security World data on other computers.

KeySafe enables you to:

  • Create OCSs

  • List the OCSs in the current Security World

  • Change the passphrase on an Operator Card

  • Remove a lost OCS from a Security World

  • Replace OCSs

  • Erase an Operator Card

  • Add a new key to a Security World

  • Import a key into a Security World

  • List the keys in the current Security World

  • Delete a key from a Security World.

KeySafe does not provide tools to back up and restore the host data or update hardware security module firmware, nor does KeySafe provide tools to synchronize host data between servers. These functions can be performed with your standard system utilities.

Setting up KeySafe

  1. You must have Java JRE/JDK 1.7, 1.8 or 11. We recommend that you install Java before you install the Security World Software. On Linux, the Java executable must be on your path.

    Java software is available from http://www.oracle.com/technetwork/java/. If your security policy does not allow the use of downloaded software, these components can be obtained on removable media from Oracle or from your operating system vendor.

    After you have set up the path, check that you are using the correct Java version by running java with the -version option.

    Example:

    >>java -version
java version "1.8.0_05"
Java(TM) SE Runtime Environment (build 1.8.0_05-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.5-b02, mixed mode)

  2. The Security World Software must be installed.

  3. In the configuration file at opt/nfast/kmdata/config/config (Linux) or %NFAST_KMDATA%\config\config (Windows), set the following port values in the server startup section:

    nonpriv_port=9000
priv_port=9001

    You must restart the hardserver after this change.

Starting KeySafe

To start KeySafe:

Linux

Ensure that X11 is properly configured and running before starting KeySafe.

Start KeySafe by running the /opt/nfast/bin/ksafe script (assuming you installed the Security World Software in the default /opt/nfast/ directory).

Windows

Start KeySafe from the Windows Start menu: Start > Entrust nShield Security World > KeySafe. You may need administrator privileges to run KeySafe.

The Windows KeySafe launcher checks that the components required to run KeySafe are installed. You will be prompted to install any missing components.

About the KeySafe window

The KeySafe window is divided into two areas:

  • The sidebar (on the left), subdivided into:

    • The menu buttons (at the top of the sidebar)

    • The Security World status pane (at the bottom of the sidebar)

  • The main panel area (on the right).

This layout is consistent throughout the KeySafe application.

Sidebar

The sidebar provides access to different parts of the KeySafe application (with the menu buttons) and also displays information about both the current Security World and your module or modules (with the Module Status tree).

The options listed below are also available from the Manage menu.

Menu buttons

There are five menu buttons at the top of the sidebar:

Menu button Description

Introduction

Clicking the Introduction menu button opens the introductory panel that KeySafe displays at startup.

World

Clicking the World menu button opens the World Operations panel, from which you can:

  • Add modules to a Security World

  • Remove modules from a Security World.

You cannot perform these operations on a module that is not in the pre-initialization mode.

Do not use the Initialize option. Creating a Security World from KeySafe is deprecated.

Card Sets

Clicking the Card Sets menu button opens the List Operator Card Sets panel, from which you can:

  • Examine or change an Operator Card Set or its passphrase

  • Create a new Operator Card Set

  • Replace an Operator or Administrator Card Set

  • Discard an Operator Card Set.

Softcards

Clicking the Softcards menu button opens the List Softcards panel, from which you can:

  • Create a new softcard

  • Change or recover the passphrase on a softcard

  • Discard a softcard

Keys

Clicking the Keys menu button opens the Keys panel, from which you can:

  • Create a key

  • Import a key

  • Discard a key

  • View details of a key.

While KeySafe is executing a command, the menu buttons are disabled. Their normal functionality returns when the command is completed.

Menus

Three menu options are available from the menu bar at the top of the screen:

  • File

    • Exit - displays a dialog asking whether you are sure you wish to quit KeySafe. Click Yes (or press the Enter key) to close KeySafe. Click No to close the dialog and return to your KeySafe session.

  • Manage

  • Help

    • About KeySafe - opens the About KeySafe panel, which displays current version numbers for KeySafe, kmjava and nfjava. You will need to quote these version numbers if you contact Support about KeySafe.

Module Status tree

The Module Status tree, in the lower part of the KeySafe sidebar, displays information about the current Security World and your modules in the form of a tree diagram.

Module Tree

At the top of the Module Status tree is an icon representing the computer on which the running copy of KeySafe is installed. The name of this computer is shown to the right of the icon.

Below the computer icon in the Module Status tree are icons and text identifiers representing the current Security World and your module(s). To the left of each icon is an expand/collapse toggle, or node. By default, when KeySafe starts, these nodes are collapsed and show a minus sign. Click the node to display expanded information about the Security World or module. Click the node again to collapse this information.

Security World information

At the top level of the Security World tree, the following information is displayed:

  • Cipher suite — the type of key protecting the Security World

  • Initialized — whether the Security World is initialized (Yes or No)

  • Strict FIPS 140 Level 3 — whether the Security World is operating at FIPS 140 Level 3 (Yes or No)

  • Key Recovery — whether key recovery is enabled (Yes or No)

  • passphrase Recovery — whether passphrase recovery is enabled (Yes or No). For more information, see passphrase replacement.

When the Advanced node is expanded, the following additional information is displayed:

  • RTC Key — whether a real-time clock authorization key has been generated (Yes or No)

    This is not applicable for nShield 5c.

  • NVRAM Key — whether a non-volatile memory authorization key has been generated (Yes or No)

  • SEE Debug Key — whether SEE debugging has been enabled (Yes or No)

  • Open SEE Debugging — whether Open SEE debugging has been enabled (Yes or No)

  • FTO Key — whether a foreign token key has been generated (Yes or No)

Module information

Module information may be displayed either inside or outside the Security World. Modules that have not been incorporated into a Security World will be shown beneath the Outside Security World node.

At the top level of the Module tree, the following information is displayed:

  • The module’s state, which is one of the following:

    Mode Description

    PreInitMode

    The module is in pre-initialization mode.

    InitMode

    The module is in initialization mode.

    Operational:Useable

    The module is in the current Security World and useable for key operations.

    Operational:Unknown

    The mode of the module cannot be determined.

    Operational:Uninitialized

    The module key is set and the module must be initialized before use.

    Operational:Factory

    The module key is set to the factory default.

    Operational:Foreign

    The module is from an unknown Security World.

    Operational:AccelOnly

    The module is an acceleration-only module.

    Operational:Unchecked

    Although the module appears to be in the current Security World, KeySafe cannot find a module initialization certificate (a module_ESN file) for this module

    Failed

    The module has failed.

    PreMaintMode

    The module is in the pre-maintenance mode.

    MaintMode

    The module is in the maintenance mode.

  • the status of the smart card reader slot(s).

    For FIPS 140 Level 3 Security Worlds, a FIPS Auth Loaded entry shows if an Administrator Card or Operator Card has been inserted to authorize an operation that requires a FIPS key.

The Module status tree has an Advanced folder that shows the following details when expanded:

  • ESN — the module’s electronic serial number (ESN), which is a unique identifier. You must quote a module’s ESN if you need to contact Support. Keep a record of the ESN(s) associated with your module(s).

  • the HSM type and model number

  • Firmware version — the version of the module’s firmware

  • Has RTC  — whether the module has a Real Time Clock (RTC)

  • Has NVRAM  — whether the module has nonvolatile memory (NVRAM).

  • RO Compatible —

  • RO Permitted —

Main panel area

The KeySafe main panel area is used to display information and options pertaining to a chosen operation. For example, clicking the World menu button takes you to the World Operations panel in the main panel area.

Navigation and command buttons

On each Operations panel there are a number of navigation buttons. Clicking a navigation button does not commit you to an action, but instead selects an operation and loads another panel of additional information and options related to the selected operation. From the World Operations panel, for example, clicking the Erase Module navigation button does not itself erase a module, but rather loads the Erase Module panel.

On the next panel, the Commit button executes an operation, while the Back button returns to the previous panel. For example, on the Erase Module panel, clicking the Commit button will erase the module, while clicking the Back button will return to the World Operations panel.

Clicking the Commit button tells KeySafe to write or delete data: it is not necessarily possible to reverse such changes even if you subsequently cancel the operation. In some cases, clicking the Commit button causes KeySafe to display a dialog asking you to confirm your command. Such features help prevent you from accidentally destroying your data or keys.

Some panels require that you select options by means of radio buttons or that you enter data into text fields before clicking the Commit button. For example, if you click the Reprogram Module button on the World Operations panel, the next panel prompts you to choose whether the module can receive remote operator card shares.

Input may be in the form of radio buttons (allowing several options, one of which — the default — will be already selected) or text boxes (allowing you to enter text: no default value is set). If you click the Commit button without having entered data into a mandatory text field, or if KeySafe detects that the information you provided is inconsistent or invalid, KeySafe displays an error message. Click the message’s OK button, and then provide or correct the necessary information.

After you successfully issue a command by clicking the Commit button, the menu buttons are disabled until the requested command is completed.

Navigating with the keyboard

The Tab key always takes you to the next field or button. If the cursor is not currently active in a text field, pressing the space bar or the Enter key activates the currently selected button (as if you had clicked it). Pressing the Shift-Tab button combination takes you to the previous field (if any) or deselects an automatically selected button (if any).

Errors

If KeySafe detects an error from which it cannot recover, it may display a Fatal Error message.

Unable to establish KeySafe session.

Error

Please ensure that the hardserver is running and accepting TCP connections.
Click OK to exit.

Possible causes

  • The hardserver is unable to receive TCP connections. The server program communicates with clients by using named pipes or TCP sockets.

  • The hardserver is not running, or is physically disconnected.

Suggested solutions

Unable to generate key

*Error reported by nShield hardware module in response to GenerateKeyPair:

nFast error: UnknownFlag

Possible causes

Your hardware or firmware may not be up to date.

Suggested solutions

Exit KeySafe and update your HSM firmware.

The firmware upgrade process destroys all persistent data held in a key-management module. If your security system requires that the persistent data held in a key-management module must survive intact during the upgrade or initialization of the key-management module, a backup and recovery mechanism of your kmdata (Linux) or _%NFAST_KMDATA% (Windows) directory must be implemented.

If you receive any error message titled Unexpected Error, contact Support with details of what you were doing, and the exact error message.