Configure the Web Services Option Pack

Web Services Option Pack is configured by configuring the corecrypto service. The configuration file is /opt/nfast/webservices/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 wsopd user shall be granted write access to the /opt/nfast/webservices/corecrypto/conf/ folder and its content.

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

exclude_tls_key: true

If an HSM-protected key is used, when set to true, this option hides the TLS key from queries to prevent access or use of the key through WSOP. The default is true.

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

API Gateway

api_gateway: false

Set to true to enable the Web Services Option Pack server to operate behind an API Gateway.

When api_gateway is set to true:

The Web Services Option Pack server is enabled to operate behind an API Gateway.
The API Gateway should authenticate the WS client and terminate the client’s TLS connection.
On successful client authentication, the received client’s identity information should be passed from the API Gateway to WSOP via a secure channel.
If WS client authentication is disabled in the API Gateway, no client’s identity information will be passed to WSOP.
For more information please refer to Client Authentication.

headers:
    issuer_header:
    subject_header:

This option is only used when Web Services Option Pack is enabled to work behind an API Gateway. By default, the Web Services Option Pack will look into authorization headers passed by the gateway to identify its clients by issuer and subject. If Authorization headers are not provided, then webservices will identify a clients' issuer and subject values from the request headers defined in the issuer_header and subject_header configuration fields.

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/webservices/corecrypto/tls/external/external-ca-cert.pem
crl_directory: /opt/nfast/webservices/corecrypto/tls/external/crls

If the WSOP server is authenticating the client using a client certificate, then the client certificate and authentication parameters are configured via the 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

If using an API Gateway, authorization of client requests is handled by the API Gateway. Set to true, to enable, or false, to disable authentication of the gateway to WSOP. If not using an API Gateway, set to false to disable client authentication. REST clients that are able to connect to your Web Services Option Pack server can 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 the filepath and the activation state in the file subsection:
file: enabled: true filepath: /opt/nfast/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 parameter network, is not set then the logs will be sent to the local syslog daemon. The allowed network parameters values are tcp and udp.

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

Security World options

This configuration resides in the world section of the corecrypto config.yaml file and relates to the Security World used by the WSOP deployment.

HKNSO

The hash of the nShield Security Officer key for the Security World in use. A valid and correct value must be present for successful WSOP installation and operation.

    # Hash of the security world Officer
    # It needs to match the world in the database and needs to be set before starting corecrypto.
    hknso: 0000000000000000000000000000000000000000

Request limiter options

This configuration resides in the request_limiter section of the corecrypto config.yaml file.

RSA key concurrent requests limit

The following option sets the maximum number of concurrent RSA key creation requests allowed by the system. When this limit is exceeded, a TooManyRequests error is sent to the client.

    # Maximum number of concurrent requests for creating RSA keys.
    # Too many concurrent requests can lead to a denial of service.
    rsa_key_concurrent_requests_limit: 10

Caching options

The following configuration options relating to cache behaviour reside in the cache section of the corecrypto config.yaml file.

WSOP key material expiration

In a deployment that uses Client Segregation, key material enabled by a client is loaded on the HSM in a client space that is separate from the key material of other clients. All key material that had been loaded into the client’s space on the HSM is unloaded if the client hasn’t performed any key management activities, for example encrypting or signing, for the period configured in key_manager_inactivity.

When you are changing this value, consider the number of unique clients that WSOP will serve and the amount of keys that each client will use.

    # 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

Key cache capacity

The key_cache_capacity field determines the total capacity of the cache. It is the maximum number of keys that can be stored in the cache before old keys are evicted.

    # Capacity of the key cache. When the number of keys in the cache reaches this
    # capacity, then the keys are evicted based on a least recently used (LRU) policy.
    # Minimum value 100
    key_cache_capacity: 30000

Key TTL period

The key_TTL_period field defines how long a key stays in the cache before it is evicted (regardless of key_cache_capacity).

    # Period of time for which a key stays in the cache before it is evicted
    # Minimum value 1m
    key_TTL_period: 60m

Group cache capacity

The group_cache_capacity field defines the capacity of the cache of groups. It is the maximum number of groups that can be stored in the cache before old groups are evicted.

    # Capacity of the group cache: when the number of groups in the cache reaches the
    # capacity, then the groups are evicted based on least recently used (LRU) policy
    # Minimum value 100
    group_cache_capacity: 20000

Group TTL period

The group_TTL_period field is the time difference between a group being added to the cache and it being evicted regardless of cache capacity.

    # Time to live value for a group in the cache
    # Minimum value 1m
    group_TTL_period: 120m

Maximum number of active protection domains

The max_number_of_active_protection_domains field defines the maximum number of protection domains stored in the cache. Once this limit is reached, any attempts to activate additional protection domains will return the TooManyActiveDomains error.

    # Maximum number of protection domains which are stored in the corecrypto cache
    # Minimum value 100
    max_number_of_active_protection_domains: 10000

Domain TTL period

The domain_TTL_period field defines the time difference between a protection domain being added to the cache and it being evicted regardless of cache capacity. A protection domain is only evicted after it has been deleted or deactivated. Active protection domains are never evicted.

    # Time to live value for protection domains in the cache
    # Minimum value 1m
    domain_TTL_period: 720m

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

Maximum Listed Keys

The listkeys_max_limit field specifies the maximum permitted listed keys at a time for the list keys endpoint, /km/v1/keys. This field is optional, however, if present and the queried limit or keys to be returned exceeds the configured limit, an error will be returned.

    # Maximum returned keys when listing, large queries can hurt the service.
    # If you wish to retrieve more than the maximum limit then you may make multiple API
    # requests and combine the results within your application using the offset and limit.
    listkeys_max_limit : 300000

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

Stand-alone Web Services Option Pack installation

The is_WSOP_standalone flag specifies whether the Web Services Option Pack shares the database with any other services.

    # Disable this option when WSOP is running with KeySafe 5
    is_WSOP_standalone: true

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 the 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 username and password (SCRAM): The value of auth_type is set to pwd.
X.509 certificate authentication: The value of auth_type is set to tls. 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 to none.

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 specify the location of a secure file containing the username and passphrase to use for authentication.

    auth_username_file: /opt/nfast/webservices/corecrypto/pwd-auth/config-username-auth
    auth_password_file: /opt/nfast/webservices/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/webservices/corecrypto/tls/db/db_ca.crt

    # Path to the corecrypto client certificate (used when Mutual Authentication is enabled)
    db_cert_file: /opt/nfast/webservices/corecrypto/tls/db/db_client.pem

    # Path to the corecrypto client private key (used when Mutual Authentication is enabled)
    db_key_file: /opt/nfast/webservices/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 and max_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

Group options

This configuration resides in the group section of the corecrypto config.yaml file.

Allowing all group deletions

When allow_all_group_deletions is set to true, any key group within the database can be deleted. When set to false, users cannot delete any key groups within the Module or Well-Known protection domains that have the same name as their parent protection domain.

    # Allow all group deletions.
    # Disable this option to prevent the deletion of the reserved groups belonging
    # to either the Module Protection or Well-Known Key Protection domains.
    # A reserved group is defined as any group which has the same name as
    # the protection domain it belongs to.
    allow_all_group_deletions: true