KeySafe 5 Local

There is a Local installation available for KeySafe 5 for managing a single machine through its local graphical desktop environment. If you have an internal nShield HSM you may set up the Agent configuration to communicate with the KeySafe 5 Local installation. You may also configure remote nShield Connect HSMs to communicate with the KeySafe 5 Local installation.

Installation

Linux

Only users that are members of the nfastadmin group may use KeySafe 5 Local. Add your local users who will be using the system to this group before we begin, and ensure that this is reflected in the output of id -Gn. You may need to log out, and then log back in again for changes to group membership to apply.

  1. Extract the KeySafe 5 Local package to the root of the filesystem:

    sudo tar -C / -xf /path/to/keysafe5-local-1.4.0-linux.tar.gz

  2. Ensure any running services using the nShield HSMs have been cleanly shut down.

  3. Run the nShield Security World install script:

    sudo /opt/nfast/sbin/install

    This will set up the log files along with the local directory as writeable to users in the nfastadmin group.

Windows

To install KeySafe 5 Local, double-click on keysafe5-local.msi.

You must have Microsoft WebView2 installed to run KeySafe 5 in Windows.

Configuration

Linux

The configuration file is located in /opt/nfast/keysafe5/local/config and named config.yaml. There is an example configuration file named config.yaml.example located in the same place. If one does not already exist, the install process above will copy the config.yaml.example over to a new config.yaml that you may modify. Do not modify the known_clients section as there is a tool that will add to this.

If any of the paths are modified, ensure that new paths are created with the right permissions, writeable to users who will be permitted to run KeySafe 5 Local.

The databases are stored in the database_directory, and this directory should be part of your backup routine.

Running /opt/nfast/bin/keysafe5-local-admin init will set up the TLS keys for securing communication between KeySafe 5 Agents and KeySafe 5 Local.

Windows

The configuration file is located in %NFAST_DATA_HOME%\keysafe5\local\conf\config.yaml. There is an example configuration file named config.yaml.example located in the same place. The easiest approach is to copy the config.yaml.example to config.yaml and then modify anything as required.

The databases are stored in the database_directory, and this directory should be part of your backup routine.

Running %NFAST_HOME%\bin\keysafe5-local-admin init from an Administrator command prompt will set up the TLS keys for securing communication between KeySafe 5 Agents and KeySafe 5 Local.

Running

Linux

KeySafe 5 Local should be available in the desktop environment’s application launcher, usually under System. Otherwise, it may be launched from the command line as /opt/nfast/bin/keysafe5-local.

Windows

KeySafe 5 Local should be available in the Start menu, under Entrust nShield Security World.

Adding HSMs to KeySafe 5 Local

For KeySafe 5 Local to manage local and remote HSMs, a KeySafe 5 Agent running alongside the HSM must be configured to communicate with KeySafe 5 Local.

KeySafe 5 Local may be configured to communicate with any number of KeySafe 5 Agents running on HSMs, but only with one KeySafe 5 Agent that is running on a host machine. That host machine agent must be on the same machine as the KeySafe 5 Local instance.

If configuring a KeySafe 5 Agent on HSM to communicate with KeySafe 5 Local, then the port used for agent communications must be open to incoming connections in your firewall configuration for the machine running KeySafe 5 Local. This port is specified in the KeySafe 5 Local configuration. By default, this is port 18084.

Adding KeySafe 5 Agents to KeySafe 5 Local

The steps below provide an example for configuring the KeySafe 5 Agent on the host machine that is running KeySafe 5 Local. For configuring a KeySafe 5 Agent on a network-attached HSM, see KeySafe 5 agent on network-attached HSMs.

  1. Configure the KeySafe 5 Agent to communicate with KeySafe 5 Local. In the KeySafe 5 Agent configuration file:

    1. Set message_bus.type to nats.

    2. Set message_bus.url to the IP address the host running KeySafe 5 Local (or 127.0.0.1 if this is the same machine). The port of the url should match the agent_comms port set in the KeySafe 5 Local configuration file.

    3. Set message_bus.auth_type to tls to enable TLS authentication.

      message_bus:
  type: nats
  url: 127.0.0.1:18084
  auth_type: tls

  2. Produce a TLS private key and Certificate Signing Request (CSR) for this Agent using ks5agenttls. See Generating a KeySafe 5 agent private key and TLS certificate. If you did not initially generate the private key to the KeySafe 5 Agent configuration directory, ensure that the TLS private key is saved to tls.key in the correct directory on the KeySafe 5 Agent machine.

    cp tls.key /opt/nfast/keysafe5/conf/messagebus/tls/tls.key

  3. Copy the CSR produced by ks5agenttls to the KeySafe 5 Local machine, and run keysafe5-local-admin sign with the file.

    keysafe5-local-admin sign <path_to_csr_file>

    A tls.crt and ca.crt will be written to the current directory and the KeySafe 5 Agent will automatically be added to the list of known clients in KeySafe 5 Local’s configuration file.

  4. Copy tls.crt and ca.crt to the correct directory on the KeySafe 5 Agent machine.

    cp ca.crt tls.crt /opt/nfast/keysafe5/conf/messagebus/tls/

  5. Restart KeySafe 5 Local to apply the changes to KeySafe 5 Local’s configuration.

Because the KeySafe 5 Agent communicates directly with KeySafe 5 Local, updates from the KeySafe 5 Agent will only be received and processed while KeySafe 5 Local is running.

Application Logs

You can find application logs at:

  • Linux: /opt/nfast/log/keysafe5-local-*.log

  • Windows: %NFAST_LOGDIR%\KeySafe5-local-*.log

This path is configurable by setting logging.file.path in the KeySafe 5 Local configuration file.

Database backup

The database can be backed up by stopping KeySafe 5 Local and creating a backup of the SQLite database files found in the configured database_directory.

By default, you can find the database file at:

  • Linux: /opt/nfast/kmdata/databases

  • Windows: %NFAST_KMDATA%\databases

Uninstalling

Linux

To uninstall, first run the main uninstall script sudo /opt/nfast/sbin/install -u. This will remove the desktop environment shortcuts. The files added by the tar.gz are:

  • /opt/nfast/keysafe5/local/config/config.yaml.example

  • /opt/nfast/scripts/install.d/20keysafe5-local

  • /opt/nfast/bin/keysafe5-local

  • /opt/nfast/bin/keysafe5-local.png

  • /opt/nfast/bin/keysafe5-local-admin

  • /opt/nfast/lib/versions/keysafe5-local-atv.txt

There are additional files and directories that may have been created that may also be removed:

  • /opt/nfast/keysafe5/local

  • /opt/nfast/kmdata/databases

  • /opt/nfast/log/keysafe5-local-*.log

Windows

To uninstall, you may use Uninstall a program from Control Panel to uninstall nShield KeySafe 5 Local.

There are additional files and directories that may have been created that may also be removed:

  • %NFAST_DATA_HOME%\keysafe5\local

  • %NFAST_DATA_HOME%\Key Management Data\databases

  • %NFAST_DATA_HOME%\Log Files\keysafe5-local-*.log