Configuring the provider

The cngwebservices.cfg file contains an example provider configuration. Before being able to use the provider, it is necessary to ensure that all mandatory entries in cngwebservices.cfg are correctly specified.

Default provider configuration

The provider is installed with a default configuration. Entrust recommends reviewing and updating the initial configuration before the provider is used to ensure that all configuration settings are appropriate for the deployment environment.

Ensure that the configuration file and certificates have restrictive access control, so that only the application using the provider has access to these.

Mandatory configuration parameters

The following configuration parameters must be set before using the provider.

Web Services server hostname

hostname=ADDR

Set ADDR to the Web Services server hostname.

Web Services server port number

port=18001

Specify the Web Services server port number (port is set to 18001 by default).

Client certificate

client_cert_thumbprint=THUMBPRINT

Set THUMBPRINT to the client certificate thumbprint. This should be specified in the following format: <system_store>\<certificate_store>\<certificate_thumbprint>. For example:

client_cert_thumbprint=LocalMachine\My\6d1ee99b3795338613354751daa351635f8f3fe0

See Server/client mutual authentication for further information on client certificates.

Client library

clientlibrary=C:\Program Files\nCipher\WebServices\CNG\clientlibrary\COpenApiClient.dll

Specify the full path of the Web Services client library (clientlibrary is set to C:\Program Files\nCipher\WebServices\CNG\clientlibrary\COpenApiClient.dll by default).

Protection domain UUID

protection_domain_uuid=DOMAIN_UUID

Set DOMAIN_UUID to the UUID of the protection domain.

Protection domain passphrase

protection_domain_passphrase=PASS

Set PASS to the passphrase of the protection domain.

Optional configuration parameters

The following configuration parameters are optional.

Logging communication with the Web Services server

log_ws_client=0

Set log_ws_client to 1 to enable logging of communication with the Web Services server to a logfile (log_ws_client is set to 0 by default). See Additional logging for information on how to configure logging to a file.

Key group UUID

key_group_uuid=GROUP_UUID

Set GROUP_UUID to the UUID of the desired key group (if unset, the protection domain’s default key group is used).

Number of times to retry an operation

request_retry_max=10

Specify the maximum number of times an operation should be retried should the Web Services server report errors (if unset, request_retry_max is set to 10 by default).

Base delay for request retry

request_retry_delay_base=1000

Specify the base delay for request retry in milliseconds (if unset, request_retry_delay_base is set to 1000 by default).

Maximum delay between retries

request_retry_delay_cap=32000

Specify the maximum delay between retrying operations in milliseconds (if unset, request_retry_delay_cap is set to 32000 by default).

Additional logging

The following environment variables can be used to configure, and acquire, additional logging from the provider:

`WSCNG_LOGFILE`	If set, and specifying a full path and filename, the provider will log - including additional debug level output - to the specified file. Ensure that appropriate permissions have been applied to the file specified by `WSCNG_LOGFILE`. Information and error level output will continue to be sent to Event Viewer.
`WSCNG_LOG_STDERR`	If set to `1`, log output - including debug level output - will be sent to stderr. Information and error level output will continue to be sent to Event Viewer.

Multiple provider configurations

It is possible, on a single client machine, to have multiple provider configuration files in use. This is achieved by setting the following environment variable:

WSCNG_CONFIGFILE

If set, and specifying a full path and filename, the provider configuration specified will be used.