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.

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.
$ cd / $ sudo tar -xf /path/to/keysafe5-1.2.0-Linux-keysafe5-agent.tar.gz
Configure this KeySafe 5 agent instance as described in Agent Configuration and AMQP 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 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 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 AMQP authentication.

The nShield KeySafe 5 agent service will not start if the certificates are not installed.

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

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`
`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. IPv6 addresses must be in the form [host]:port. If required, a virtual host may be specified at the end of the address. This parameter is required, there is no default.	`127.0.0.1:5671/nshieldvhost`
`amqp.auth_type`	Authentication method for the AMQP connection. Valid values: `none`, `pwd`, `tls`. The default is to use TLS authentication.	`tls`
`amqp.tls_username_location`	For auth_type 'tls', the AMQP 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).	`SAN-DNS-Field0`
`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`
`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`
`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`
`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`
`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

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. IPv6 addresses must be in the form [host]:port. If required, a virtual host may be specified at the end of the address. This parameter is required, there is no default.

127.0.0.1:5671/nshieldvhost

amqp.auth_type

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

tls

amqp.tls_username_location

For auth_type 'tls', the AMQP 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).

SAN-DNS-Field0

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

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

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

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

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

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

The username extracted from the TLS client certificate (tls.crt) is defined by the agent configuration item amqp.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/amqptls.

For instructions to create the files using a bespoke CSR file, see Obtaining the KeySafe 5 Agent Certificates.

Generate the agent’s private key

On Linux:

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

When configuring AMQP TLS for this KeySafe 5 agent, the key should be saved to /opt/nfast/keysafe5/conf/amqp/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\amqp\tls\tls.key is:

%NFAST_HOME%\bin\amqptls.exe -keypath=C:\ProgramData\nCipher\keysafe5\conf\amqp\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/amqptls -keypath=/opt/nfast/keysafe5/conf/amqp/tls/tls.key -csrgen CSR has been generated and saved to ks5agent_demohost.csr
On Windows the command is:
%NFAST_HOME%\bin\amqptls.exe -keypath=C:\ProgramData\nCipher\keysafe5\conf\amqp\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
1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.
2. In the top menu bar, click Settings.
3. In the Application Settings section, click KeySafe5 Settings.
4. Click Downloads > nShield KeySafe 5 Agent Certificates.
5. In the Upload CSR File section, click Load File and select the CSR file you wish to use for certificate generation.
6. 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 a TLS certificate.
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/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.

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 [amqp.url=x.x.x.x:5671]
          ks5agent resetcfg
          ks5agent amqpcsr
          ks5agent amqptls [ca.crt|tls.crt] [data]
          ks5agent amqpuser
          ks5agent amqppwd


        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
          amqpcsr     Generate a Certificate Signing request for creation of KeySafe 5 agent TLS certificate
          amqptls     Show/set the TLS certificates for the KeySafe 5 Agent AMQP connection
          amqpuser    Show the agent's username for AMQP password or TLS based authentication
          amqppwd     Configure the password for the agent to use for AMQP 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
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_poll_interval: 1s
update_interval: 1m
max_update_message_response_time: 1m
health_interval: 1m
codesafe_update_interval: 3m
codesafe_cache_period: 60m

(cli)ks5agent cfg amqp.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
amqp:
  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_poll_interval: 1s
update_interval: 2m
max_update_message_response_time: 1m
health_interval: 1m
codesafe_update_interval: 3m
codesafe_cache_period: 60m

The agent configuration values for override_hostname and logging.file 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 amqp.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 amqp.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.

AMQP authentication for ks5agent

The AMQP authentication method is configured using the ks5agent cfg command and setting the amqp.auth_type configuration item.

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

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

(cli)ks5agent amqpuser
ks5agent_nshield_module_AAAA-AAAA-AAAA

Password authentication

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

(cli)ks5agent amqppwd
Configuring password to use for KeySafe 5 agent AQMP user 'ks5agent_nshield_module_AAAA-AAAA-AAAA'
This should match the passphrase configured for the user on the RabbitMQ 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 amqpcsr Serial Console command on the nShield Connect.
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 AMQP authentication for ks5agent.
Store the TLS certificate for this agent and the CA certificate using the ks5agent amqptls 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 amqpcsr
<output will contain the CSR>

# Obtain a TLS certificate for the above CSR

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

(cli)ks5agent amqptls 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.2.0-2752f5de

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.

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 KeySafe 5 Agent CSR Generation.

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:

Stop the KeySafe 5 agent service using Windows Service Manager.
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.