KeySafe 5 Agent Installation

Installation

The Keysafe 5 agent runs alongside the existing hardserver and enables the central management platform to manage all HSMs and Security Worlds visible to the hardserver.

The Keysafe 5 agent is a privileged client of the hardserver. For more information on privileged clients, see the nShield Security World Software documentation.

The connection between the agent and the central monitoring platform is via the RabbitMQ message bus using the Advanced Message Queueing Protocol (AMQP). It is configured in the Keysafe 5 agent configuration file.

The Keysafe 5 agent ensures that all key management data, with the exception of keys, is synchronized between the nShield client machine and a central (MongoDB) database.

This means that when resources, such as Card Sets or Softcards, appear in the kmdata/local directory on a client machine, they are automatically stored in the central database. It also means that when a Card Set or Softcard is created via the new management tools, the resource also appears in kmdata/local on any host machine that is in the right Security World.

The Card Set or Softcard can then be used with the traditional nShield tools on each nShield client machine.

If a resource is deleted via the Keysafe 5 application then it will be removed from kmdata/local for all client machines running a Keysafe 5 agent. If the resource is deleted locally on a nShield client machine then that deletion is not synchronized to other client machines in the same Security World.

Configuration

The install contains an example configuration file at %NFAST_DATA_HOME%/keysafe5/conf/config.yaml.example. Make a copy of it at the same location and rename the copy to %NFAST_DATA_HOME%/keysafe5/conf/config.yaml.

Unless configured otherwise, %NFAST_DATA_HOME% is located at /opt/nfast on Linux and C:\ProgramData\nCipher on Windows.

Configuration Key Description Example Value

Configuration Key	Description	Example Value
`override_hostname`	Set the hostname for this agent. This appears as the Host resource name in Keysafe 5. The hostname is set by the operating system if not overridden here. This is not related to the hostname used by TLS authentication.	`hostname`
`logging.level`	Minimum severity level of log statements to output. Valid values: `trace`, `debug`, `info`, `warning`, `error`. The default is to output at `info` level and above.	`info`
`logging.format`	Format of the log statements. Valid values: `json`, `logfmt`. The default is to output in `json` format.	`json`
`logging.file.enabled`	To enable log output to file, set to `true`. The default is to output to file (`true`).	`true`
`logging.file.path`	The absolute path of the file that logs should be written to. The default is `/opt/nfast/log/keysafe5-agent.log` on Linux and `C:\ProgramData\nCipher\Log Files\KeySafe5-agent.log` on Windows.	`/opt/nfast/log/keysafe5-agent.log`
`amqp.auth_type`	Authentication method for the AMQP connection. Valid values: `none`, `pwd`, `tls`. The default is to use TLS authentication.	`tls`
`amqp.url`	The URL points to the AMQP service with its IP address or DNS name, including the port number. For an OVA install, this is the IP address or DNS name of the VM. This parameter is required, there is no default.	`127.0.0.1:5671`
`amqp.disable_tls`	To disable Mutual TLS for the AMQP connection, set to `true`. The default is to use Mutual TLS (`false`). Entrust recommends that this is always set to `false`.	`false`
`update_interval`	The period of time between publishing data updates. The interval string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". The default is once a minute.	`1m`
`health_interval`	The period of time between checking the underlying service health and attempting recovery if necessary. The format is as used for `update_interval`. The default is once a minute.	`1m`
`kmdata_poll_interval`	The rate at which the agent polls the `kmdata` directory to look for changes. The format is as used for `update_interval`. The default is once a second.	`1s`
`amqp.min_protocol_version`	The minimum TLS protocol version that is used by the AMQP connection of the keysafe5 agent. The default is `TLSV1_2`.	`TLSV1_2`
`amqp.cipherSuites`	The available ciphersuites for the AMQP connection of the keysafe5 agent. The defaults are `ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305`	`ECDHE-ECDSA-AES128-GCM-SHA256`

override_hostname

Set the hostname for this agent. This appears as the Host resource name in Keysafe 5. The hostname is set by the operating system if not overridden here. This is not related to the hostname used by TLS authentication.

hostname

logging.level

Minimum severity level of log statements to output. Valid values: trace, debug, info, warning, error. The default is to output at info level and above.

info

logging.format

Format of the log statements. Valid values: json, logfmt. The default is to output in json format.

json

logging.file.enabled

To enable log output to file, set to true. The default is to output to file (true).

true

logging.file.path

The absolute path of the file that logs should be written to. The default is /opt/nfast/log/keysafe5-agent.log on Linux and C:\ProgramData\nCipher\Log Files\KeySafe5-agent.log on Windows.

/opt/nfast/log/keysafe5-agent.log

amqp.auth_type

Authentication method for the AMQP connection. Valid values: none, pwd, tls. The default is to use TLS authentication.

tls

amqp.url

The URL points to the AMQP service with its IP address or DNS name, including the port number. For an OVA install, this is the IP address or DNS name of the VM. This parameter is required, there is no default.

127.0.0.1:5671

amqp.disable_tls

To disable Mutual TLS for the AMQP connection, set to true. The default is to use Mutual TLS (false). Entrust recommends that this is always set to false.

false

update_interval

The period of time between publishing data updates. The interval string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". The default is once a minute.

1m

health_interval

The period of time between checking the underlying service health and attempting recovery if necessary. The format is as used for update_interval. The default is once a minute.

1m

kmdata_poll_interval

The rate at which the agent polls the kmdata directory to look for changes. The format is as used for update_interval. The default is once a second.

1s

amqp.min_protocol_version

The minimum TLS protocol version that is used by the AMQP connection of the keysafe5 agent. The default is TLSV1_2.

TLSV1_2

amqp.cipherSuites

The available ciphersuites for the AMQP connection of the keysafe5 agent. The defaults are ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305

ECDHE-ECDSA-AES128-GCM-SHA256

Configure the Keysafe 5 agent’s AMQP connection to use the same RabbitMQ instance used by the central management platform that you want to connect to. In an OVA deployment the address of the RabbitMQ instance is the IP address or the DNS name of a node in the cluster.

AMQP authentication

You can configure the authentication method for the AMQP connection as tls for X.509 certificate authentication.

Entrust recommends restricting access to files containing sensitive authentication details. On Linux, the Keysafe 5 agent installer will create the required files with appropriate permissions.

TLS

You must create the %NFAST_DATA_HOME%/keysafe5/conf/amqp/tls directory manually so that you can store the TLS key and certificates for the agent’s connection to AMQP there in the following files:

ca.crt	The CA certificate.
tls.key	The agent’s private key.
tls.crt	A valid certificate of the key signed by the Certificate Authority.

For instructions to create the files, see Obtaining the Keysafe 5 Agent Certificates.

Your certificates will need to adhere to X.509 v3, sometimes known as a multiple-domain certificates, or SAN certificates. The X.509 extension Subject Alternative Name (SAN) allows specifying multiple hostnames, and has replaced Common Name as the source of the hostname.

Install on Linux

Untar the Keysafe 5 agent install package to the root directory of the machine.
This unpacks the agent and associated scripts into the /opt/nfast/ directory.
$ cd / $ sudo tar -xf /path/to/keysafe5-1.1.1-Linux-keysafe5-agent.tar.gz
Configure this Keysafe 5 agent instance as described earlier in the chapter.
You may run either the nShield install script, or the Keysafe 5 specific install script.
1. Running the nShield install script will restart the hardserver and other services, which may not be desired.
  sudo /opt/nfast/sbin/install
2. Running the Keysafe 5 specific install script requires that the nShield install script has previously been run, but will only start the Keysafe 5 agent.
  sudo /opt/nfast/keysafe5/sbin/install

The agent must point to a working RabbitMQ otherwise it will fail to start.

The installer creates the following items, as required:

Either a SysV-style init script or systemd script for automatically starting and stopping the service.
The keysafe5d user.

This user is dedicated to running the keysafe5-agent service, and is a member of the nfast group.

Install on Windows

The hardserver TCP ports must be enabled. To do so, run config-serverstartup.exe --port 9000 --privport 9001 or by editing the file (located at %NFAST_KMDATA%\config\config) and setting nonpriv_port=9000 and priv_port=9001.

After enabling the hardserver TCP ports, you must restart the hardserver service.

If those ports are not available and different ports are set, then the environment variables NFAST_SERVER_PORT and NFAST_SERVER_PRIVPORT must also be set appropriately as mentioned in the nShield documentation. They may be set globally in System Environment Variables, or only for this service by adding a Multi-String Value named Environment under Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\nShield KeySafe 5 Agent, and to Value data adding the lines NFAST_SERVER_PORT=port-number and NFAST_SERVER_PRIVPORT=port-number. You may need to restart the computer after adding the System Environment Variables.

Launch the Keysafe5-agent.msi installer.

This creates the nShield Keysafe 5 agent service but does not start it.
Populate the Keysafe 5 agent configuration file.

The nShield Keysafe 5 agent service will not start if the certifications are not installed.

For instructions on the agent configuration file, see Obtaining the Keysafe 5 Agent Certificates.

Obtaining the Keysafe 5 Agent Certificates

The Keysafe 5 Agent requires a set of TLS certificates, and a private key for the secure connection with the Keysafe 5 central platform. These certificates can be obtained by following the steps below.

Before You Begin

Generation of an appropriate Certificate Signing Request (CSR) is required prior to following these steps, for more information on generating a CSR please see [agent-csr].

Procedure

Log into the Keysafe 5 Appliance Management UI using an account with Security Admin privileges.
In the top menu bar, click Settings.
In the Application Settings section, click KeySafe5 Settings.
Click nShield KeySafe 5 Agent Certificates.
In the Upload CSR File section, click Load File and select the CSR file you wish to use for certificate generation.
Click Generate and Download Certificate to download the certificate bundle from the cluster node.

The certificate bundle is a .zip file you must unpack. It contains both the CA certificate and Keysafe 5 Agent’s TLS certificate in .pem format.
The downloaded certificates can now be copied to the machine where the Keysafe 5 Agent is installed. For information about the location, see Install on Linux or Install on Windows.

Uninstall

Before uninstalling the nShield Keysafe 5 agent, Entrust recommends that you back up any configuration files and certificates from the install.

Linux

To remove the Keysafe 5 agent from a Linux host run the Keysafe 5 uninstaller:

/opt/nfast/keysafe5/sbin/install -u

Then proceed to remove the following files and directories:

/opt/nfast/keysafe5
/opt/nfast/sbin/keysafe5-agent
/opt/nfast/lib/versions/keysafe5-agent-atv.txt
/opt/nfast/scripts/install.d/12keysafe5-agent
/opt/nfast/log/keysafe5-agent.log

The agent log file will be located in a different location if you have changed the default value of logging.file.path in the agent configuration file.

If required, you can also remove the keysafe5d user that was created as part of the installation.

Windows

To remove the Keysafe 5 agent from a Windows host:

Open the Control Panel and select Programs and Features.
Select the nShield Keysafe 5 Agent package.
Select Uninstall and follow the on-screen instructions.

To remove any configuration files, delete the %NFAST_DATA_HOME%\keysafe5 directory and remove the log file located at C:\ProgramData\nCipher\Log Files\KeySafe5-agent.log

The agent log file will be located in a different location if you have changed the default value of logging.file.path in the agent configuration file.