KeySafe 5 Agent 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 synchronised 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 synchronised to other client machines in the same Security World.

Configuration

The KeySafe 5 agent configuration file is located at %NFAST_DATA_HOME%/keysafe5/conf/config.yaml. The install contains an example configuration file at %NFAST_DATA_HOME%/keysafe5/conf/config.yaml.example.

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

override_hostname

Set the hostname for this agent. This appears as the Pool name in KeySafe 5. The hostname is set by the operating system if not overriden 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 (IP address or DNS name) along with its port number. 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).

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 default is 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.

AMQP authentication

You can configure the authentication method for the AMQP connection as one of the following options:

  • none No authentication.

  • pwd Username and password authentication.

  • tls 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.

Password authentication

To configure password authentication, set amqp.auth_type to pwd in the configuration file. Locate the plaintext username and password in the following files on disk:

  • %NFAST_DATA_HOME%/keysafe5/conf/amqp/auth/username should contain the username to use for the AMQP connection.

  • %NFAST_DATA_HOME%/keysafe5/conf/amqp/auth/password should contain the password to use for the AMQP connection.

TLS

The TLS key and certificates for the agent’s connection to AMQP should be stored within %NFAST_DATA_HOME%/keysafe5/conf/amqp/tls 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.

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.

Installing on Linux

  1. 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.0.0-Linux-keysafe5-agent.tar.gz

  2. Configure this KeySafe 5 agent instance as described earlier in the chapter.

  3. Run the nShield install script.

    This will restart the hardserver. The agent must point to a working RabbitMQ otherwise it will fail to start. 
    sudo /opt/nfast/sbin/install

    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.

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

  1. Launch the Keysafe5-agent.msi installer.

    This creates the nShield KeySafe 5 agent service but does not start it.

  2. Populate the KeySafe 5 agent configuration file as detailed previously.

  3. Start the nShield KeySafe 5 agent service using Windows Service Manager.