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

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

logging.journal.enabled

To enable logging to journal (Linux only), set to true. The default is false.

true

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. 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, tls. The default is to use TLS authentication.

tls

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.

  • 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 Windows, the KeySafe 5 agent installer will create the required files with appropriate permissions.

TLS

The directory %NFAST_DATA_HOME%/keysafe5/conf/messagebus/tls is used to store the TLS key and certificates for the agent’s connection to the message bus 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 IP addresses, and has replaced Common Name as the source of the hostname.

The username extracted from the TLS client certificate (tls.crt) is the certificate’s Distinguished Name.

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.

  1. Generate the agent’s private key

    On Linux ensure the directory /opt/nfast/keysafe5/conf/messagebus/tls exists, then:

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

  2. 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 ks5_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 ks5_<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).

  3. 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 the Service deployment of KeySafe 5, run %NFAST_HOME%/bin/keysafe5-server-admin on the machine running the KeySafe 5 Service deployment:

    $ /opt/nfast/bin/keysafe5-server-admin sign ks5_demohost.csr 365
Successfully signed CSR ks5_demohost.csr for 365 days
Saved certificates tls.crt and ca.crt in the current directory

    If using the demo Kubernetes deployment of KeySafe 5, run the agentcert.sh script that is shipped alongside the deployment scripts from the preserved directory in which the script was run.

    ./agentcert.sh ks5_demohost.csr 365
Successfully signed CSR ks5_demohost.csr for 365 days
Saved certificates ks5_demohost.crt and ca.crt in the current directory

    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 may append the export KUBECONFIG=${HOME}/.kube/config to your shell’s configuration file.

  4. 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 nShield Connect 5c/XC

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.

By default, a KeySafe 5 1.5.0 central platform deployment will only be able to communicate with version 1.5 or later KeySafe 5 Agents. If your Connect has a v1.4 or earlier KeySafe 5 Agent then you must enable Agent Compatibility Mode when configuring the KeySafe 5 central platform installation.

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:18084]
          ks5agent resetcfg
          ks5agent mbcsr
          ks5agent mbtls [ca.crt|tls.crt] [data]


        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

        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:
  url: 127.0.0.1:18084
  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>:18084 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>:18084
  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:18084 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:18084

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=none
TLS

TLS certificate authentication is configured with the following workflow:

  1. Generate a CSR for this agent using the ks5agent mbcsr Serial Console command on the nShield Connect.

  2. Generate a TLS certificate using this CSR.

  3. 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.5.0-de64c594

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.

KeySafe 5 agent on nShield Connect 5c 10G

A KeySafe 5 agent is installed on the nShield Connect 5c 10G for nShield Connect images released with Security World v14.0 and later software.

The agent must be configured to communicate with the central KeySafe 5 platform to allow configuration and management of the nShield Connect 5c 10G.

Initial agent configuration must be done via the nShield Connect serial console. Once the agent is connected to a KeySafe 5 central platform then the agent configuration may be updated via KeySafe 5.

This KeySafe 5 agent is for platform management of the nShield Connect 5c 10G and will create a HSM resource of HSM type Platform in KeySafe 5. It will allow you to perform management operations on the nShield Connect 5c 10G from within KeySafe 5 (including network configuration, syslog configuration and HSM tenancy configuration/creation). See the KeySafe 5 User Guide. for more details.

ks5agent command

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

(cli)help ks5agent
usage: ks5agent [-h] {restart,version,cfg,resetcfg,log,mbcsr,mbtls} ...

Manage the Platform KeySafe 5 agent.

options:
  -h, --help            show this help message and exit

ks5agent subcommands:
  {restart,version,cfg,resetcfg,log,mbcsr,mbtls}
    restart             Restart the KeySafe 5 agent.
    version             Show version information for the KeySafe 5 agent.
    cfg                 Configure the KeySafe 5 agent, or display the current
                        configuration.
    resetcfg            Restore the KeySafe 5 agent configuration file to the
                        default values.
    log                 Display the most recent log messages from the KeySafe
                        5 agent.
    mbcsr               Generate a Certificate Signing Request for the KeySafe
                        5 agent TLS certificate.
    mbtls               Show/set the TLS certificates for the KeySafe 5 Agent
                        message bus connection.

ks5agent cfg

The agent configuration can be displayed and set using the ks5agent cfg command. Updating the configuration will prompt to restart the KeySafe 5 agent.

(cli)ks5agent cfg
logging.level=info
logging.format=json
logging.file.enabled=false
logging.file.path=/opt/nfast/log/keysafe5-agent.log
logging.journal.enabled=true
message_bus.url=127.0.0.1:18084
message_bus.auth_type=tls
message_bus.disable_tls=false
message_bus.minProtocolVersion=TLSV1_2
message_bus.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
override_hostname=hsm_AAAA-AAAA-AAAA

(cli)ks5agent cfg message_bus.url=<IPADDRESS>:18084
logging.level=info
logging.format=json
logging.file.enabled=false
logging.file.path=/opt/nfast/log/keysafe5-agent.log
logging.journal.enabled=true
message_bus.url=<IPADDRESS>:18084
message_bus.auth_type=tls
message_bus.disable_tls=false
message_bus.minProtocolVersion=TLSV1_2
message_bus.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
override_hostname=hsm_AAAA-AAAA-AAAA

Restart KeySafe 5 agent to apply new configuration (y|n): y
Restarting KeySafe 5 agent.
Success.
The following agent configuration values are fixed and can not be set: - override_hostname - logging.file.enabled - logging.file.path - logging.journal.enabled - kmdata_network_mount - kmdata_poll_interval

The value for override_hostname will be set to hsm_{esn}.

Multiple configuration items may be set with a single command.

ks5agent cfg message_bus.url=0.0.0.0:18084 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:18084

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=none
TLS

TLS certificate authentication is configured with the following workflow:

  1. Generate a CSR for this agent using the ks5agent mbcsr Serial Console command on the nShield Connect.

  2. Generate a TLS certificate using this CSR.

  3. 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 Base64 encoded data to ca.crt.

(cli)ks5agent mbtls tls.crt <base64encoded_data>
Saved Base64 encoded data to tls.crt.

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

(cli)ks5agent version
1.5.0-e4687903

Logging

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

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

(cli)ks5agent logs
(cli)ks5agent logs -n 20

If the nShield Connect is configured to send logs to a Remote Syslog server, then the KeySafe 5 agent logs will be sent with these logs.

The agent logs are also available via the KeySafe 5 API or WebUI.