Configuration Items

The KeySafe 5 Service configuration file is located at %NFAST_DATA_HOME%/keysafe5/server/config/config.yaml.

The install contains an example configuration file at %NFAST_DATA_HOME%/keysafe5/server/config/config.yaml.example which can be used to revert back to original configuration if needed.

Please ensure that all certificates, private keys and credential files are stored securely and have appropriate permissions set to prevent unauthorized access, as they contain sensitive information.

Unless configured otherwise, %NFAST_DATA_HOME% is located at /opt/nfast on Linux and %ProgramData%\nCipher on Windows.
Time durations are 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". For example, 30s configures a time interval of 30 seconds.
Configuration Key Description Default

server.host

Host used for serving the WebUI and API. Entrust recommends keeping this value as 127.0.0.1, to restrict external connections, until authentication has been configured.

127.0.0.1

server.port

Port used for serving the WebUI and API. If this port is not available, KeySafe 5 will fail to start.

18080

server.read_timeout

Period of time before timing out reading a request.

5m

server.write_timeout

Period of time before timing out writing a response. This should be at least as long as you’d expect the slowest nShield request in your environment to take (e.g. the amount of time to write a card when creating a Security World)

8m

server.cleanup_timeout

Amount of time to wait after each request for the next request before timing out.

30s

server.max_header_bytes

Maximum number of bytes to read while parsing the request header’s keys and values

1048576

server.tls.min_protocol_version

Minimum TLS protocol version allowed. Valid values: TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3.

TLSV1_2

server.tls.cipher_suites

Allowed cipher suites. The default provided here is the list of recommended cipher suites. TLSv1.3 cipher suites are currently not configurable. See Supported TLS Cipher Suites.

ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305

ui.refresh_rate

How often the WebUI will poll the backend. Set 0 to disable auto refresh in the WebUI.

30s

agent_comms.host

Host used for communication with KeySafe 5 Agents.

0.0.0.0

agent_comms.port

Port used for communication with KeySafe 5 Agents. If this port is not available, KeySafe 5 will fail to start.

18084

agent_comms.compatibilityMode

Enable message bus server compatibility mode. If false, this KeySafe 5 Server will only be able to communicate with KeySafe 5 v1.5, or newer, Agents

false

agent_comms.tls.min_protocol_version

Minimum TLS protocol version allowed. Valid values: TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3.

TLSV1_2

agent_comms.tls.cipher_suites

Allowed cipher suites. The default provided here is the list of recommended cipher suites. TLSv1.3 cipher suites are currently not configurable. See Supported TLS Cipher Suites.

ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305

agent_comms.tls.ocsp.enabled

Enable OCSP checks

true

agent_comms.tls.ocsp.

OCSP Stapling Mode - [auto, always, never]. auto staples a status, only if 'status_request' is set in the certificate. always enforces OCSP stapling for certificates even if 'status_request' is not set in the certificate. never disables OCSP stapling even if the certificate has Must-Staple flag

auto

agent_comms.tls.ocsp.override_url

HTTP URL used to get OCSP staples. Overrides the OCSP Responder URI set in certificates.
For example, https://1.2.3.4:5000

``

agent_comms.tls.ocsp.cache_enabled

Cache OCSP staples to local file storage.

true

auth.type

Authentication type applied to the WebUI/API interface. Valid values: none, oauth_oidc. Entrust recommends configuring this section before entering production.

none

auth.oauth_oidc.issuers

Listing of OIDC/OAuth2 issuers configured, each of the following items are per issuer. Please refer to your Identity Provider’s documentation for details, these items are usually returned from its .well-known/openid-configuration endpoint.

``

auth.oauth_oidc.issuers.name

Name for the issuer to be displayed in the WebUI.

Entrust IDaaS

auth.oauth_oidc.issuers.issuer

Identity of the issuer This MUST match the 'iss' payload in any issued JWT by the issuer

https://example.idp.com

auth.oauth_oidc.issuers.jwks_uri

URL of the issuers public key set to validate signature of the JWT. Can only set one of jwk_url or offline_jwks.

https://example.idp.com/jwks

auth.oauth_oidc.issuers.offline_jwks

JWKs of public keys to validate signature of the JWT Can only set one of jwk_url or offline_jwks.

'{"keys":[…​]}'

auth.oauth_oidc.issuers.jwks_cache_refresh

Period of time that the JWKs will be refreshed Will be the largest of either the Cache-Control response header, the Expires header or this value. Not used if offline_jwks is set.

15m

auth.oauth_oidc.issuers.audiences

List of JWT audiences that are allowed access. A JWT containing any of these audiences will be accepted.

https://example.audience.com

auth.oauth_oidc.issuers.client_id

ID of the application to request a JWT for.

33118f7c-2be5-40eb-bf45-60ba091596e3

auth.oauth_oidc.issuers.response_type

Which grant type to execute during authentication.

code

auth.oauth_oidc.issuers.scope

List of scopes to request.

profile, openid, offline_access

auth.oauth_oidc.issuers.logout_redirect_uri

URL that the issuer will redirect to on successful logout.

https://keysafe5.server.com

auth.oauth_oidc.issuers.authorization_endpoint

URL of the issuer to request authentication.

https://example.idp.com/authorize

auth.oauth_oidc.issuers.token_endpoint

URL of the issuer to obtain a token.

https://example.idp.com/token

auth.oauth_oidc.issuers.userinfo_endpoint

URL of the issuer to obtain user information.

https://example.idp.com/userinfo

auth.oauth_oidc.issuers.end_session_endpoint

URL of the issuer to end the session.

https://example.idp.com/endsession

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 directory to which logs should be written. The default is /opt/nfast/log on Linux and %ProgramData%\nCipher\Log Files on Windows.

/opt/nfast/log

database.type

Type of database to use for KeySafe 5. Valid values: [sqlite, mongodb]

sqlite

database.timeout

Timeout for database requests.

60s

database.sqlite.database_directory

Absolute path of the directory in which KeySafe 5 will store its database files. KeySafe 5 must have permission to read and write to this directory. If not specified, it defaults to $NFAST_KMDATA/databases

/opt/nfast/kmdata/databases

database.mongodb.hosts

MongoDB database hosts list, comma separated. IPv6 addresses must be in the form [host]:port Only applied if database.type==mongodb

``

database.mongodb.replica_set

Name of the MongoDB replica set. Only applied if database.type==mongodb

``

database.mongodb.database_name_prefix

Database name prefix. Use this setting if you are pointing multiple KeySafe 5 instances at the same MongoDB server to avoid database conflict. Only applied if database.type==mongodb

``

database.mongodb.auth.type

Authentication method for the MongoDB connection. Valid values: [none, pwd, x509] none: No authentication required for connections pwd: SCRAM authentication x509: x.509 certificate authentication Only applied if database.type==mongodb

x509

database.mongodb.auth.auth_database

The name of the Authentication Database for MongoDB. See https://docs.mongodb.com/manual/core/security-users/#std-label-authentication-database Only applied if database.type==mongodb

``

database.mongodb.auth.username_file

File containing the MongoDB username - only applicable if auth.type=pwd Only applied if database.type==mongodb

/opt/nfast/keysafe5/server/database/username

database.mongodb.auth.password_file

File containing the MongoDB password - only applicable if auth.type=pwd Only applied if database.type==mongodb

/opt/nfast/keysafe5/server/database/password

database.mongodb.auth.client_cert_file

x.509 client certificate - only applicable when auth.type=x509 Only applied if database.type==mongodb

/opt/nfast/keysafe5/server/database/tls.crt

database.mongodb.auth.client_key_file

x.509 client private key - only applicable when auth.type=x509 Only applied if database.type==mongodb

/opt/nfast/keysafe5/server/database/tls.key

database.mongodb.tls.enabled

Set to false to disable use of TLS for the MongoDB connection. Only applied if database.type==mongodb

true

database.mongodb.tls.ca_cert_file

Server CA certificate. Only applied if database.type==mongodb

/opt/nfast/keysafe5/server/database/ca.crt

database.mongodb.tls.min_protocol_version

Minimum TLS protocol version allowed. Valid values: TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3. Only applied if database.type==mongodb

TLSV1_2

database.mongodb.tls.cipher_suites

Allowed cipher suites. The default provided here is the list of recommended cipher suites. TLSv1.3 cipher suites are currently not configurable. See Supported TLS Cipher Suites. Only applied if database.type==mongodb

ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305

database.mongodb.connect_timeout

Timeout for connection to the MongoDB server. Only applied if database.type==mongodb

30s

database.mongodb.selection_timeout

Timeout for selecting a connection from the connection pool. Only applied if database.type==mongodb

30s

database.mongodb.socket_timeout

Timeout waiting for read/write in the socket. Only applied if database.type==mongodb

30s

database.mongodb.min_pool_size

Minimum connections to use in the MongoDB connection pool. Only applied if database.type==mongodb

1

database.mongodb.max_pool_size

Maximum connections to use in the MongoDB connection pool. Only applied if database.type==mongodb

100

health.update_period

Period of time between health checks.

30s

health.timeout_period

Time before a running health check should fail.

10s

health.liveness_failure_period

Period of time before a liveness check is marked as failing.

5m

health.allowed_clock_skew

Maximum amount of time a clock on a KeySafe 5 agent can differ from this service before the host clockSkew health check fails.

2m

filestore

Absolute path of the directory in which KeySafe 5 will store large files. These may be gigabytes in size. KeySafe 5 must have permission to read and write to this directory. If not specified, it defaults to $NFAST_KEYSAFE5/server/filestore

%NFAST_DATA_HOME%/keysafe5/server/filestore

monitoring.metric_samples_storage_retention_time

Duration to retain metric samples in storage. Supported time units: y (years), w (weeks), d (days), h (hours), m (minutes), s (seconds), ms (milliseconds)
For example, 12h

1y

monitoring.metric_samples_storage_retention_size

Maximum total size of storage blocks to retain. When the limit is reached, the oldest data is deleted first. Set to 0 to disable size-based retention. Supported units: B, KB, MB, GB, TB, PB, EB (using binary prefixes, for example, 1KB = 1024B)
For example, 512GB

0

monitoring.database_directory

Absolute path to the directory where databases containing metric samples and alerts are stored. KeySafe 5 must have read and write permissions for this directory. If not specified, the default is $NFAST_KMDATA/databases

%NFAST_DATA_HOME%/kmdata/databases

monitoring.email_smarthost

SMTP server used for sending alert notifications.
For example, smtp.example.com:465

``

monitoring.email_from

Sender address used in alert notification emails.

noreply@entrust.com

monitoring.email_auth_enabled

Enable authenticated sending for the SMTP server. Note: For authenticated email, the SMTP server must support TLS, and its CA certificate must be in the operating system trust store.

false

monitoring.email_auth_username_filepath

Absolute path to the file containing the SMTP username for authentication.

``

monitoring.email_auth_password_filepath

Absolute path to the file containing the SMTP password for authentication.

``

monitoring.host_address

Address of the host the email footer to link to. If not specified, the default is "" and the footer will not be displayed.
For example, https://127.0.0.1:18080

``