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 a message bus (RabbitMQ or NATS). It is configured in the KeySafe 5 agent configuration file.

Ensure the system clock of the KeySafe 5 agent is synchronized with the central platform.

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, and Connects, 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.

The KeySafe 5 agent will also report on the status of CodeSafe 5 machines/certificates visible to the agent, and allow these resources to be managed via KeySafe 5. The amount of time taken for the agent to publish a CodeSafe 5 update message will increase by several seconds per CodeSafe 5 resource (machine or certificate) in the system. This means that in systems with many CodeSafe 5 machines/certificates present, KeySafe 5 will be slower to reflect local changes in the state of these resources.

If you are upgrading an existing KeySafe 5 Agent install, see Agent Upgrade.

Install on Linux

Untar the KeySafe 5 agent install package to the root directory of the machine. The agent install package can be found in keysafe5-agent directory of the KeySafe 5 release package.
This unpacks the agent and associated scripts into the /opt/nfast/ directory.
sudo tar -C / -xf /path/to/keysafe5-1.4.0-Linux-keysafe5-agent.tar.gz
Configure this KeySafe 5 agent instance as described in Agent Configuration and Message Bus authentication.
Run the appropriate install script depending on the state of the hardserver:
- If the hardserver is running, use the KeySafe 5 specific install script so the hardserver is not restarted.
  sudo /opt/nfast/keysafe5/sbin/install
- When the hardserver is not running, use the nShield install script to install both the KeySafe 5 agent and the hardserver.
  sudo /opt/nfast/sbin/install

The agent must point to a working message bus (either RabbitMQ or NATS) 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 and nfastadmin groups.

The KeySafe 5 agent is not affected by the standard nShield /opt/nfast/sbin/init.d-ncipher script. To stop, start, or restart the KeySafe 5 agent you may either:

Use /opt/nfast/scripts/init.d/keysafe5-agent, or
Use your standard init system scripts, addressing the nc_keysafe5-agent service.

Install on Windows

The KeySafe 5 Agent requires the hardserver TCP ports be enabled. To do this, either:

Run config-serverstartup.exe --port 9000 --privport 9001, or
Edit the file (located at %NFAST_KMDATA%\config\config) and set 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 described 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. The installer is in the keysafe5-agent directory of the KeySafe 5 release package.

This msi creates the nShield KeySafe 5 agent service but does not start it.
Populate the KeySafe 5 agent configuration file as described in Agent Configuration and Message Bus authentication.

The nShield KeySafe 5 agent service will not start if the certificates are not installed.
Populate the messagebus authentication files.
Start the nShield KeySafe 5 agent service using Windows Service Manager.

Agent 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. 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 %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 `%ProgramData%\nCipher\Log Files\KeySafe5-agent.log` on Windows.	`/opt/nfast/log/keysafe5-agent.log`
`message_bus.type`	The type of the message bus connection of the keysafe5 agent. Valid values: `amqp`, `nats`. The default message bus type is `nats`.	`nats`
`message_bus.url`	The URL points to the message bus service with its IP address or DNS name, including the port number. IPv6 addresses must be in the form [host]:port. For RabbitMQ, a virtual host may be specified at the end of the address. This parameter is required, there is no default.	`127.0.0.1:18084`
`message_bus.auth_type`	Authentication method for the message bus connection. Valid values: `none`, `pwd`, `tls`. The default is to use TLS authentication.	`tls`
`message_bus.tls_username_location`	For auth_type 'tls', the message bus username is encoded in a field of the X.509 certificate. When a RabbitMQ server is configured to allow X.509 authentication, it is specified which field to extract the username from within the certificate. This agent configuration item identifies which field of the certificate contains the username and should match the setting on the RabbitMQ server. Valid values: `DistinguishedName`, `CommonName`, `SAN-DNS-Field0` (the first DNS field in the Subject Alternative Name of the certificate). For NATS, this is always `DistinguishedName`	`SAN-DNS-Field0`
`message_bus.disable_tls`	To disable Mutual TLS for the message bus connection, set to `true`. The default is to use Mutual TLS (`false`). Entrust recommends that this is always set to `false`.	`false`
`message_bus.min_protocol_version`	The minimum TLS protocol version that is used by the message bus connection of the keysafe5 agent. The default is `TLSV1_2`.	`TLSV1_2`
`message_bus.cipherSuites`	The available ciphersuites for the message bus 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`
`kmdata_network_mount`	If any directory within the kmdata directory on this machine is mounted as a network share (e.g. NFS or SMB) this configuration should be set to true. For example, if this configuration is set to false, the agent will not be able to detect changes in the kmdata/local directory if the directory is an NFS mount. This setting updates the agent to use a method of detecting file modifications/additions/removals that works for network mounted directories.	`false`
`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`. This value is only used if `kmdata_network_mount` is `true`. The default is once a second.	`1s`
`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`
`max_update_message_response_time`	The maximum amount of time to allow the central platform to pull update messages sent by this agent. Update messages published by this agent will expire after the lower of this time, or the configured update_interval. This setting impacts the freshness of the data processed by the central platform. The default is 1 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`
`recovery_interval`	The recovery_interval specifies how often recovery of the connections to external services should be performed. The default is 5 seconds.	`5s`
`codesafe_update_interval`	The period of time between publishing CodeSafe 5 data updates. The format is as used for `update_interval`. The default is once every 5 minutes.	`3m`
`codesafe_cache_period`	The `codesafe_cache_period` specifies how often the CodeSafe 5 certificate cache will expire. The caching is performed to negate performance impacts of running unnecessary CodeSafe 5 certificate commands. Cache expiry may be performed earlier if approaching a time where a certificates validity status may change, that is, when it is approaching `NotBefore` or `NotAfter`. The cache is invalidated if there is a change in CodeSafe 5 certificates. The format is as used for `update_interval`. The default is 60 minutes.	`60m`

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 %ProgramData%\nCipher\Log Files\KeySafe5-agent.log on Windows.

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

message_bus.type

The type of the message bus connection of the keysafe5 agent. Valid values: amqp, nats. The default message bus type is nats.

nats

message_bus.url

The URL points to the message bus service with its IP address or DNS name, including the port number. IPv6 addresses must be in the form [host]:port. For RabbitMQ, a virtual host may be specified at the end of the address. This parameter is required, there is no default.

127.0.0.1:18084

message_bus.auth_type

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

tls

message_bus.tls_username_location

For auth_type 'tls', the message bus username is encoded in a field of the X.509 certificate. When a RabbitMQ server is configured to allow X.509 authentication, it is specified which field to extract the username from within the certificate. This agent configuration item identifies which field of the certificate contains the username and should match the setting on the RabbitMQ server.

Valid values: DistinguishedName, CommonName, SAN-DNS-Field0 (the first DNS field in the Subject Alternative Name of the certificate).

For NATS, this is always DistinguishedName

SAN-DNS-Field0

message_bus.disable_tls

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

false

message_bus.min_protocol_version

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

TLSV1_2

message_bus.cipherSuites

The available ciphersuites for the message bus 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

kmdata_network_mount

If any directory within the kmdata directory on this machine is mounted as a network share (e.g. NFS or SMB) this configuration should be set to true. For example, if this configuration is set to false, the agent will not be able to detect changes in the kmdata/local directory if the directory is an NFS mount. This setting updates the agent to use a method of detecting file modifications/additions/removals that works for network mounted directories.

false

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. This value is only used if kmdata_network_mount is true. The default is once a second.

1s

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

max_update_message_response_time

The maximum amount of time to allow the central platform to pull update messages sent by this agent. Update messages published by this agent will expire after the lower of this time, or the configured update_interval. This setting impacts the freshness of the data processed by the central platform. The default is 1 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

recovery_interval

The recovery_interval specifies how often recovery of the connections to external services should be performed. The default is 5 seconds.

5s

codesafe_update_interval

The period of time between publishing CodeSafe 5 data updates. The format is as used for update_interval. The default is once every 5 minutes.

3m

codesafe_cache_period

The codesafe_cache_period specifies how often the CodeSafe 5 certificate cache will expire. The caching is performed to negate performance impacts of running unnecessary CodeSafe 5 certificate commands. Cache expiry may be performed earlier if approaching a time where a certificates validity status may change, that is, when it is approaching NotBefore or NotAfter. The cache is invalidated if there is a change in CodeSafe 5 certificates. The format is as used for update_interval. The default is 60 minutes.

60m

Configure the KeySafe 5 agent’s message bus connection to use the same instance used by the central management platform that you want to connect to.

Message Bus authentication

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

none No authentication.
pwd Username and password authentication.
tls X.509 certificate authentication.

Entrust recommends tls as the message bus authentication method. 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 message_bus.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/messagebus/auth/username should contain the username to use for the message bus connection.
%NFAST_DATA_HOME%/keysafe5/conf/messagebus/auth/password should contain the password to use for the message bus connection.

The username must contain the KeySafe 5 agent’s hostname (set either by override_hostname in the agent configuration file, or defaults to the machine’s hostname). If the username does not contain the KeySafe 5 agent’s hostname then the agent will not start.

TLS

You must create the %NFAST_DATA_HOME%/keysafe5/conf/messagebus/tls directory manually so that you can store the TLS key and certificates for the agent’s connection to the message bus 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.

The username extracted from the TLS client certificate (tls.crt) is defined by the agent configuration item messageBus.tls_username_location. By default, this is set to SAN-DNS-Field0 (the first DNS field in the Subject Alternative Name of the certificate) but can optionally be set to Distinguished Name or CommonName to match the TLS authentication settings on the RabbitMQ server.

The extracted certificate username must contain the KeySafe 5 agent’s hostname (set either by override_hostname in the agent configuration file, or defaults to the machine’s hostname). If the username does not contain the KeySafe 5 agent’s hostname then the agent will not start.

Generating a KeySafe 5 agent private key and TLS certificate

To generate a private key and certificate signing request (CSR) for a specific KeySafe 5 agent, use %NFAST_HOME%/keysafe5/bin/ks5agenttls.

Generate the agent’s private key

On Linux:

$ /opt/nfast/keysafe5/bin/ks5agenttls -keypath=/opt/nfast/keysafe5/conf/messagebus/tls/tls.key -keygen
Private key has been generated and saved to /opt/nfast/keysafe5/conf/messagebus/tls/tls.key

When configuring message bus TLS for this KeySafe 5 agent, the key should be saved to /opt/nfast/keysafe5/conf/messagebus/tls/tls.key with file permissions and ownership as documented in the KeySafe 5 Installation Guide

On Windows the command to write to %NFAST_DATA_HOME%\keysafe5\conf\messagebus\tls\tls.key is:

%NFAST_HOME%\bin\ks5agenttls.exe -keypath=C:\ProgramData\nCipher\keysafe5\conf\messagebus\tls\tls.key -keygen

This will generate an ECDSA P-521 private key and save it to the file pointed to by the keypath option. If keypath is not specified the file tls.key is saved to the current directory.

Generate the CSR
On Linux:
/opt/nfast/keysafe5/bin/ks5agenttls -keypath=/opt/nfast/keysafe5/conf/messagebus/tls/tls.key -csrgen CSR has been generated and saved to ks5agent_demohost.csr
On Windows the command is:
%NFAST_HOME%\bin\ks5agenttls.exe -keypath=C:\ProgramData\nCipher\keysafe5\conf\messagebus\tls\tls.key -csrgen
This will generate a certificate signing request and save it to ks5agent_<agent_hostname>.csr (where <agent_hostname> is the value of override_hostname in the KeySafe 5 agent configuration file, if set, or the host machines host name). Alternatively, the CSR can be printed to the console, rather than saved to a file, by specifying -csr-stdout.

The generated CSR requests a certificate that contains the agent hostname as the CommonName and as a DNS SubjectAlternativeName (SAN).

Create a TLS Certificate for this KeySafe 5 agent

The CSR should be provided to a KeySafe 5 administrator who, in a secure location/environment, creates a message bus service client TLS certificate using the CA trusted by the message bus server.

If using a RabbitMQ instance installed by the deploy.sh script then the agent certificate can be generated on the central platform on which the deploy.sh script was run. Run the agentcert.sh script that is shipped alongside the deployment scripts from the preserved directory in which the script was run.

./agentcert.sh ks5agent_demohost.csr 365
Certificate generated to ks5agent_demohost.crt. Valid for 365 days
CA Certificate available at /path/to/internalCA/cacert.pem

RabbitMQ will need to be configured to allow access for the user 'ks5agent_demohost':
   export RUN_RABBIT="kubectl -n rabbitns exec rabbit-chart-rabbitmq-0 -c rabbitmq -- "
   ${RUN_RABBIT} rabbitmqctl add_user ks5agent_demohost ephemeralpw
   ${RUN_RABBIT} rabbitmqctl set_permissions -p nshieldvhost ks5agent_demohost '.*' '.*' '.*'
   ${RUN_RABBIT} rabbitmqctl clear_password ks5agent_demohost

If you get a message about a lack of permissions opening /etc/rancher/k3s/k3s.yaml you can set up kubectl access by running:

mkdir -p $\{HOME}/.kube
sudo /usr/local/bin/k3s kubectl config view --raw > $\{HOME}/.kube/config
chmod 600 $\{HOME}/.kube/config
export KUBECONFIG=$\{HOME}/.kube/config

You many append the export KUBECONFIG=${HOME}/.kube/config to your shell’s configuration file.

The KeySafe 5 administrator should then configure the RabbitMQ server to allow the user specified in this TLS certificate to access the appropriate virtual host in RabbitMQ.
rabbitmqctl add_user ks5agent_demohost ephemeralpw rabbitmqctl set_permissions -p nshieldvhost ks5agent_demohost '.*' '.*' '.*' rabbitmqctl clear_password ks5agent_demohost
Configure the KeySafe 5 agent
The resulting TLS certificate and accompanying CA certificate, along with the agent’s private key should be stored within %NFAST_DATA_HOME%/keysafe5/conf/messagebus/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.

KeySafe 5 agent on network-attached HSMs

A KeySafe 5 agent is installed on the nShield Connect for nShield Connect images released with Security World v13.4 and later software. This agent allows an nShield Connect to be monitored and managed without, or in addition to, the Connect being enrolled to a nShield host machine (a machine with nShield Security World software installed) which also has a KeySafe 5 agent installed.

By default, the KeySafe 5 agent on the nShield Connect is disabled. It must be configured to communicate with the central KeySafe 5 platform, and enabled. The agent can only be configured via the nShield Connect serial console.

ks5agent command (only on serial console network-attached HSMs)

The KeySafe 5 agent is configured and managed on the Connect using the ks5agent Serial Console command.

(cli)help ks5agent

        Manage the KeySafe 5 agent

        USAGE
          ks5agent
          ks5agent enable
          ks5agent disable
          ks5agent version
          ks5agent logs [tail [linecount]]
          ks5agent cfg [message_bus.url=x.x.x.x:5671]
          ks5agent resetcfg
          ks5agent mbcsr
          ks5agent mbtls [ca.crt|tls.crt] [data]
          ks5agent mbuser
          ks5agent mbpwd


        OPTIONS
          enable      Start the KeySafe 5 agent (setting will persist on reboot)
          disable     Stop the KeySafe 5 agent
          version     Show version information for the KeySafe 5 agent
          logs        Display the KeySafe 5 agent log file
          cfg         Configure the KeySafe 5 agent
          resetcfg    Restore the KeySafe 5 agent configuration file back to the default values for this Connect
          mbcsr     Generate a Certificate Signing request for creation of KeySafe 5 agent TLS certificate
          mbtls     Show/set the TLS certificates for the KeySafe 5 Agent message bus connection
          mbuser    Show the agent's username for message bus password or TLS based authentication
          mbpwd     Configure the password for the agent to use for message bus password-based authentication

        If no action is specified, the current status of the KeySafe 5 agent will be
        displayed.

ks5agent cfg

The agent configuration can be displayed and set using the ks5agent cfg command.

(cli)ks5agent cfg
override_hostname: nshield_module_AAAA-AAAA-AAAA
logging:
  level: info
  format: json
  file:
    enabled: false
    path: /opt/nfast/log/keysafe5-agent.log
message_bus:
  type: amqp
  url: 127.0.0.1:5671
  auth_type: tls
  tls_username_location: SAN-DNS-Field0
  disable_tls: false
  minProtocolVersion: TLSV1_2
  cipherSuites:
  - 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
kmdata_network_mount: false
kmdata_poll_interval: 1s
update_interval: 1m
max_update_message_response_time: 1m
health_interval: 1m
recovery_interval: 5s
codesafe_update_interval: 3m
codesafe_cache_period: 60m

(cli)ks5agent cfg message_bus.url=<IPADDRESS>:5671/nshieldvhost update_interval=2m
override_hostname: nshield_module_AAAA-AAAA-AAAA
logging:
  level: info
  format: json
  file:
    enabled: false
    path: /opt/nfast/log/keysafe5-agent.log
message_bus:
  url: <IPADDRESS>:5671/nshieldvhost
  auth_type: tls
  tls_username_location: SAN-DNS-Field0
  disable_tls: false
  minProtocolVersion: TLSV1_2
  cipherSuites:
  - 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
kmdata_network_mount: false
kmdata_poll_interval: 1s
update_interval: 2m
max_update_message_response_time: 1m
health_interval: 1m
recovery_interval: 5s
codesafe_update_interval: 3m
codesafe_cache_period: 60m

The agent configuration values for override_hostname, logging.file and kmdata_network_mount are fixed and can not be set on nShield Connect. The value for override_hostname will be set to nshield_module_{esn}.

Multiple configuration items may be set with a single command.

ks5agent cfg message_bus.url=0.0.0.0:5671/nshieldvhost update_interval=5m

If no configuration update is provided, the contents of the KeySafe 5 agent config file are displayed.

To update a configuration item, use the format key=value using a . character for nested configuration items. Examples:

ks5agent cfg update_interval=5m
ks5agent cfg logging.level=debug
ks5agent cfg message_bus.url=0.0.0.0:5672

If the agent is currently running, it will be restarted to pick up the change in configuration.

By default, you can only set values for keys that already exist in the configuration file. To force setting a key that does not currently exist in the configuration file, specify --force.

ks5agent cfg newkey=value --force

Running the ks5agent resetcfg command will reset the agent configuration to the default configuration for this agent on the nShield Connect.

Message bus authentication for ks5agent

The message bus authentication method is configured using the ks5agent cfg command and setting the message_bus.auth_type configuration item.

ks5agent cfg message_bus.auth_type=tls
ks5agent cfg message_bus.auth_type=pwd
ks5agent cfg message_bus.auth_type=none

The username for password or TLS based authentication can be displayed using the ks5agent mbuser command.

(cli)ks5agent mbuser
ks5agent_nshield_module_AAAA-AAAA-AAAA

Password authentication

To configure password based authentication, use the ks5agent mbpwd command. This command will display the username that will be used for message bus authentication, and then prompt for the password to be input.

(cli)ks5agent mbpwd
Configuring password to use for KeySafe 5 agent message bus user 'ks5agent_nshield_module_AAAA-AAAA-AAAA'
This should match the passphrase configured for the user on the message bus server
New passphrase:
Confirm passphrase:
passphrase set

TLS

TLS certificate authentication is configured with the following workflow:

Generate a CSR for this agent using the ks5agent mbcsr Serial Console command on the nShield Connect.
Generate a TLS certificate using this CSR.
- If using a RabbitMQ instance installed by the deploy.sh script, then the agent certificate can be generated using the agentcert.sh script that is shipped alongside the deployment scripts. See Generating a KeySafe 5 agent private key and TLS certificate.
- If using the NATS server with KeySafe 5 Local, the agent certificate may be generated using keysafe5-local-admin. See see Adding KeySafe 5 Agents to KeySafe 5 Local
Store the TLS certificate for this agent and the CA certificate using the ks5agent mbtls Serial Console command on the nShield Connect. These certificates must be entered in base64 encoded format. To create suitable input on a Unix system you can run base64 --wrap=0 tls.crt.

(cli)ks5agent mbcsr
<output will contain the CSR>

# Obtain a TLS certificate for the above CSR

(cli)ks5agent mbtls ca.crt <base64encoded_data>
Saved ca.crt

(cli)ks5agent mbtls tls.crt <base64encoded_data>
Saved tls.crt

Status

To show the current status of the KeySafe 5 agent on the nShield Connect, run the ks5agent Serial Console command with no arguments.

(cli)ks5agent
KeySafe 5 agent is disabled

The agent can be enabled and disabled using the ks5agent enable and ks5agent disable commands. This setting will persist over reboots.

To identify the version of agent installed on the Connect, use the ks5agent version command.

(cli)ks5agent version
1.4.0-4fa2054c

Logging

The agent logs of the KeySafe 5 agent running on the nShield Connect may be obtained by using the ks5agent logs Serial Console command.

By default, this will print the entire contents of the agent log file to the console. To display just the last 10 lines of the log file, use ks5agent logs tail. To display the last n lines of the log file, use ks5agent logs tail <n> where <n> is the number of lines to display.

(cli)ks5agent logs
(cli)ks5agent logs tail
(cli)ks5agent logs tail 20

If the nShield Connect is configured to append logs to the RFS, or configured to send logs to a Remote Syslog server, then the KeySafe 5 agent logs will be sent with these logs. For more information about configuring logging on the Connect, see the nShield Connect User Guide.