Configuration
Web Services Option Pack is configured by configuring the corecrypto
service.
The configuration file is /opt/nfast/wsop/corecrypto/conf/config.yaml
.
Use this file to set the WSOP external interface, corecrypto logging and database settings.
Entrust does not recommend changing the default permissions of the configuration file. Only |
Default web services configuration
The service is installed using a default configuration. Entrust recommends reviewing and updating the initial configuration before the WSOP service is brought into service to ensure all configuration settings are appropriate for the deployment environment.
Special attention needs to be given to TLS connection and logging so that the system is used securely.
Server listening host
host: 0.0.0.0
This should be set to the interface that WSOP will listen for client requests on. It can be an IP address of the interface or a host name which must be available in the local system.
Location: The external_tls
section of the corecrypto config.yaml
file.
Server listening port
Port: 18001
Web Services Option Pack server runs as a low-privileged user and, in typical environments, is unable to bind to "privileged" ports (port numbers in the range of 1 to 1023). To use a low numbered port number, yet continue using a low-privileged user, a firewall can be configured to enable port forwarding. Consult the user guides of your internal/external firewall for further information.
Location: The external_tls
section of the corecrypto config.yaml
file.
WSOP TLS server configuration
This section contains details of Web Services Option Pack’s TLS server certificate and private key. If using Security World to protect your private key, the named key will be corresponding to a Security World key.
All the settings refer to the external_tls
section of the corecrypto config.yaml
file.
WSOP TLS certificate
cert_file: /opt/nfast/wsop/corecrypto/tls/external/server-corecrypto-cert.pem
This contains the name of the file the server TLS certificate. If the user has a chain of certificates they must be packed together.
WSOP TLS private key
key_appname_ident: appname:ident
This directive contains the name of the Security World TLS server key. This is an HSM-protected key and Entrust recommends that you enable this option when possible, because it offers a higher level of security.
If it is decided that the WSOP server’s TLS private key is not to be protected by an HSM, this option can be disabled by either deleting the line, or by commenting it out.
Entrust recommends the use of HSM-protected keys. |
An alternative to the HSM-protected TLS key is to provide a file based TLS private key. The confidentiality and integrity of this TLS private key file is protected by the Operating Systems access controls/permissions.
key_file: /opt/nfast/wsop/corecrypto/tls/external/server-corecrypto-privkey.pem
key_file
and key_appname_ident
directives are mutually exclusive.
key_file
specifies the location of the WSOP server TLS private key (when it is not protected by the HSM).
Entrust does not recommend changing the default permissions of the TLS private key files.
The TLS private key file should be restricted such that only the wsopd user has read access.
|
Entrust recommends excluding the TLS private key files from any back-ups of the system and for the TLS private key to not be stored in any shared location. |
TLS server ciphersuites configuration
It is possible for the WSOP administrator to control the acceptable ciphersuites and the order the TLS handshakes negotiate them.
cipher_suites:
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
…
The cipher_suites
directives control the order the ciphersuite is chosen during the TLS connection initialization.
Entrust does not recommend adding weaker TLS ciphersuites as this will reduce the security provided by WSOP’s TLS secure channel. |
TLS client authentication
All the settings refer to the external_tls
section of the corecrypto config.yaml
file.
ca_certificate_file: /opt/nfast/wsop/corecrypto/tls/external/external-ca-cert.pem
crl_directory: /opt/nfast/wsop/corecrypto/tls/external/crls
Client certificate and authentication parameters are configured via external_tls
section in the corecrypto
service config file.
The ca_certificate_file
contains the Web Services client root certificate, which forms the trust anchor for authenticating the client certificates received during TLS handshake.
REST clients, as part of the same handshake, will need to present a client certificate that can be verified using this client root certificate.
The crl_directory
contains the certificate revocation list, used to blacklist the certificates no longer valid.
client_auth_enabled: true
Set to false to disable client authentication. REST clients that are able to connect to your Web Services Option Pack server will be able to use your Security World keys without any authentication or authorization.
Entrust recommends that client authentication is always enabled within a production environment. |
Logging
corecrypto
service allows setting of the log level separately for server
and for database driver
integration.
Corecrypto service logging
The corecrypto logging is controlled from logging
section within corecrypto
configuration file.
corecrypto
is able to output logs simultaneously to console, log file and syslog daemon.
corecrypto
server logging is controlled by configuring loglevel
field from the logging
section:
loglevel: Warning
Available log levels are:
-
Trace
-
Debug
-
Info
-
Warning
-
Error
This will set the logging level for the logger independent of the output method chosen.
Info, Debug, and Trace logging levels are very verbose — it is recommended that such logs are sent to an external syslog server with sufficient capacity to store the logs.
This parameter sets the logging level for all logging outputs.
Database driver logging level
corecrypto
server logging is controlled by configuring loglevel
field from database driver
integration:
# Database Options
database:
...
# The loglevel of the database driver component
# Valid values: Trace, Debug, Info, Warning, Error
loglevel: Info
The loglevel
field specifies the logging level for the database driver.
The database driver is a module of the WSOP server which handles the database connectivity and requests to the database.
You have the following logging options:
-
Logging to console.
By default,
corecrypto
service has console logging enabled. In order to disable this, update the following parameter in the console subsection:console: output: discard
-
Logging to file.
By default,
corecrypto
service outputs the logs to a file on the local file system. In order to configure set thefilepath
and the activation state in thefile
subsection:file: enabled: true filepath: /opt/nfast/wsop/corecrypto/log/corecrypto.log
-
Logging to Syslog.
syslog: enabled: false network: udp host: localhost:514
corecrypto
service logs can be directed to a syslog server. The configuration directives provide a means to activate the output to syslog, set the host, port, and type of transport. If the transport, set via parameternetwork
, is not set then the logs will be sent to the local syslog daemon. The allowednetwork
parameters values aretcp
andudp
.
WSOP health endpoint
The health endpoint checks the availability of the WSOP service.
This configuration resides in the health
section of the corecrypto config.yaml
file.
The estate health check configuration options relate to the modules belonging to the security world
# Interval in seconds between estate health check
# Estate means the modules which belong of the security world
estate_check_interval: 5s
# Period in seconds after which the estate health check will timeout
estate_check_timeout: 30s
The security world health check configuration value should be a multiple of the estate_check_interval
as the security world check will also execute an estate check.
# Interval in seconds between each security world check
# Its value is a multiple of the estate_check_interval value
# Note: each time a security world check takes place, an estate
# health check also takes place
sworld_check_interval: 300s
The database check can be set to different intervals and timeout values than the estate and security world checks with the following options.
# Interval in seconds between each database health check
database_check_interval: 5s
# Period in seconds after which a database health check will timeout
database_check_timeout: 30s
Access to the health check endpoint can be controlled with the following configuration option.
# Allow unauthenticated clients to probe the health check endpoint.
# Only applicable when tls.client_auth_enabled is true
allow_unauthenticated_clients: false
The health check endpoint can be extended to also probe the availability of FIPS-authentication.
# Extend health check status to include whether the service can acquire FIPS-authentication
include_fips_ready_check: false
WSOP key material expiration
In a deployment where Client Segregation is being used, key material that has been enabled by a particular client is loaded on the HSM in a separate client space to other client’s key material. After a period of inactivity from a client, all key material loaded in its associated space on the HSM is unloaded.
This configuration value allows the tuning of the period of inactivity from a client, and consideration should be made in regards to the number of unique clients that WSOP will serve and the amount of keys that each client will use.
This configuration resides in the cache
section of the corecrypto config.yaml
file.
# Caching Options
cache:
# Period of inactivity in minutes after which a key manager will be closed
# Only applicable when tls.client_auth_enabled is true
# Setting of 0 is used to disable closing an inactive key manager.
key_manager_inactivity: 1440m
Database configuration
This configuration resides in the database
section of the corecrypto config.yaml
file.
Hosts
hosts
field specifies the addresses and ports of the database hosts:
# List of database hosts
hosts:
- database1.ncipher.com:30001
- database2.ncipher.com:30002
- database3.ncipher.com:30003
Logging level
The loglevel
field specifies the logging level for the database driver.
The database driver is a module of the WSOP server which handles the database connectivity and requests to the database.
# The loglevel of the database driver component
# Valid values: Trace, Debug, Info, Warning, Error
loglevel: Info
Possible log levels are:
-
Trace
-
Debug
-
Info
-
Warning
-
Error
Timeout
Each database request from the WSOP server is executed with a timeout.
If the request is not served in the time specified by the timeout parameter, then an error is returned.
The timeout
field from the database
section specifies the respective timeout.
# Time before a database request should fail
timeout: 5s
Database name
The db_name
field specifies the name of the database.
This field is mandatory, meaning that the WSOP server will not start until a database name is provided in the corecrypto config.yaml
file.
# Database name
db_name : nshield-corecrypto
Virtual Partitioning database
The segregation_db_name
field specifies the name of the Virtual Partitioning database.
segregations_db_name: segregation_db
Virtual Partitioning collection
The segregations_collection_name
field specifies the collection inside Virtual Partitioning database that contains the mappings of the virtual partitions
segregations_collection_name: segregations
Authentication method
WSOP supports the following authentication mechanisms when connecting to the database:
-
By user name and password (SCRAM): The value of
auth_type
is set topwd
. -
X.509 certificate authentication: The value of
auth_type
is set totls
. For this type of authentication, the Certificate Authority (CA) files for TLS must be also provided in the configuration file. -
No authentication: The value of
auth_type
is set tonone
.
Entrust doesn’t recommend setting the auth_type to none for production deployments.
|
For details regarding database authentication see Authentication Methods.
# Authentication method with database. Valid values: [none, pwd, tls]
# none - no authentication
# pwd - username and password authentication using mongodb SCRAM
# tls - x509 authentication
auth_type: tls
If the authentication is performed by username and password, then the auth_username_file
and auth_password_file
fields specifies the location of a secure file containing the username and passphrase to use for authentication.
auth_username_file: /opt/nfast/wsop/corecrypto/pwd-auth/config-username-auth
auth_password_file: /opt/nfast/wsop/corecrypto/pwd-auth/config-password-auth
The auth_source
field specifies the name of the authentication database.
The username and password provided by the file name specified by the auth_username_file
and auth_password_file
fields are verified against the username and password stored in the authentication database.
auth_source: userdb
Disable TLS
The disable_tls
field from database
section specifies if TLS for database connection is on or off as follows: value true
means that TLS is not used while value false
means that TLS is used.
# Transport Layer Security. Default is false.
disable_tls: false
Certificate Authority (CA) files for TLS
When TLS option is used as method of authentication, then db_ca_file
, db_cert_file
and db_key_file
specify the Certificate Authority (CA) files for TLS.
# Path to the mongoDB TLS certificate
db_ca_file: /opt/nfast/wsop/corecrypto/tls/db/db_ca.crt
# Path to the corecrypto client certificate (used when Mutual Authentication is enabled)
db_cert_file: /opt/nfast/wsop/corecrypto/tls/db/db_client.pem
# Path to the corecrypto client private key (used when Mutual Authentication is enabled)
db_key_file: /opt/nfast/wsop/corecrypto/tls/db/db_client.key
Database type
The db
field from database
section specifies the type of the database management system.
Currently the only supported value is mongodb
.
# Type of database. Supported values: mongodb
db: mongodb
MongoDB configuration
MongoDB configuration is specified in the mongodb
section of the corecrypto config.yaml
file:
-
Replication set name:
The
replica_set
field specifies the name of the MongoDB replica set used for WSOP server. The default value must be changed to the correct replica set for your configuration.# Name of the Replication Set replica_set: rs1
-
Connection timeout:
The
connect_timeout
specifies the number of seconds WSOP server will wait before the database connection attempt is aborted.# Timeout for connection to the database server connect_timeout: 5s
-
Selection timeout:
The
selection_timeout
specifies the number of seconds the WSOP server will wait to select a server for a database operation before giving up and raising an error.# Timeout for selecting a connection from the pool selection_timeout: 5s
-
Read/write timeout:
socket_timeout
specifies the number of seconds that a read or a write operation from or to the database can take before the operation is timed out. This setting is a socket specific setting.# Timeout waiting for read/write in the socket socket_timeout: 5s
-
Minimum and maximum pool size:
The
min_pool_size
andmax_pool_size
specify the minimum and maximum number of connections, respectively, of the connection pool.# Minimum and maximum connections to use in mongodb's connection pool min_pool_size: 1 max_pool_size: 100