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 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.
|
If you are upgrading an existing Keysafe 5 Agent install, see Upgrade.
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 |
---|---|---|
|
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. |
|
|
Minimum severity level of log statements to output.
Valid values: |
|
|
Format of the log statements.
Valid values: |
|
|
To enable log output to file, set to |
|
|
The absolute path of the file that logs should be written to.
The default is |
|
|
Authentication method for the AMQP connection.
Valid values: |
|
|
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. |
|
|
To disable Mutual TLS for the AMQP connection, set to |
|
|
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. |
|
|
The period of time between checking the underlying service health and attempting recovery if necessary.
The format is as used for |
|
|
The rate at which the agent polls the |
|
|
The minimum TLS protocol version that is used by the AMQP connection of the keysafe5 agent.
The default is |
|
|
The available ciphersuites for the AMQP connection of the keysafe5 agent.
The defaults are |
|
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. |
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.
-
Running the nShield install script will restart the hardserver and other services, which may not be desired.
sudo /opt/nfast/sbin/install
-
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 thenfast
group.
Install on Windows
The hardserver TCP ports must be enabled.
To do so, run 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 |
-
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.
-
Populate the
amqp
authentication files. -
Start the nShield Keysafe 5 agent service using Windows Service Manager.