Configure the Web Services PKCS #11 library
The pkcs11webservices.cfg
file contains an example PKCS #11 configuration.
To use this file, you need to alter it to point to the correct certificate locations.
Default PKCS #11 configuration
The PKCS #11 library is installed with a default configuration. Entrust recommends reviewing and updating the initial configuration before the library is called to ensure that all configuration settings are appropriate for the deployment environment.
Pay special attention to the TLS connection and logging to ensure that the system is used securely.
Ensure that the configuration file and TLS authentication files have restrictive access control, so that only the application using the PKCS #11 client library has access to these files.
Configuration parameters for both Windows and Linux
The following configuration options are shared on both Linux and Windows.
Web Services server hostname
HOST <host name of server>
Set this to the Web Services server host name.
Log level
The LOGLEVEL
field in the configuration file controls the PKCS #11 library logging.
The available log levels are:
-
0(None)
-
1(Fatal)
-
2(Error)
-
3(Warning)
-
4(Debug 1)
-
5(Debug 3)
-
6(Debug 9)
By default, the PKCS #11 logging level is set at 4 (Debug 1).
Higher log levels include all logs from lower levels.
If the logging level is set to 4(Debug 1)
, you only get log events with Debug 1, Warning, Error, and Fatal.
If the logging level is set to 6(Debug 9)
it enables all the log levels.
To turn off logging set LOGLEVEL
to 0(None)
.
LOGLEVEL 4
Logs that are not at DEBUG9 level have the message prefixed with standard fields:
-
Timestamp with format [yyyy-mm-dd hh:mm:ss]
-
Process ID
-
Level (one of DEBUG3 DEBUG1 WARNING ERROR FATAL)
-
PKCS #11 session handle (zero if not used)
-
PKCS #11 library name
Logs at DEBUG9 level add field for thread ID in prefix:
-
Timestamp with format [yyyy-mm-dd hh:mm:ss]
-
Process ID
-
Thread ID
-
Level (DEBUG9)
-
PKCS #11 session handle (zero if not used)
-
PKCS #11 library name
Enable logging to console
By default, PKCS #11 has console logging disabled.
In order to enable this, set LOGSTDOUT
to 1
in the configuration file.
LOGSTDOUT 1
Retry Web Services communication
Since the PKCS #11 library operates over a network connection, it is possible that network fluctuations could cause an internal request to the Web Services server to fail. To ensure the reliability and robustness of PKCS #11 applications, the request can be retried.
You can configure the maximum number of retries for each request and the delay (in seconds) between each retry. For example:
MAXRETRIES 5
RETRYDELAY 10
If you don’t define either of these entries, the PKCS #11 library uses the defaults.
-
For
MAXRETRIES
, the default is5
and the maximum number is256
.To disable retries, set
MAXRETRIES
to0
. -
For
RETRYDELAY
, the default is10
seconds. There is no maximum value but higher values will reduce performance on unstable systems. Only integer values are supported.To disable the retry delay, set
RETRYDELAY
to0
. This will cause retries to occur consecutively without delay.
Configuration parameters for Linux only
For details on creating certificates, see Server/client mutual authentication with the Web Services PKCS #11 library.
TLS certificate
CERT <path to TLS certificate>
Set this to the file path of the client TLS certificate.
TLS client authentication
AUTH <path to TLS CA Certificate for Mutual Authentication>
Set this to the server root certificate, which forms the trust anchor for authenticating the server’s certificates received during TLS handshake.
Log file path on Linux
By default, PKCS #11 outputs the logs to /opt/nfast/webservices/pkcs11/log/pkcs11webservices.log
.
To change the default path set LOGFILEPATH
to any valid existing path.
LOGFILEPATH /opt/nfast/webservices/pkcs11/log/pkcs11webservices.log
To enable logging for a user, change the path to a Linux user path so that the user has write permission to the folder.
LOGFILEPATH /home/<username>/log/pkcs11webservices.log
Configuration parameters for Windows only
For details on creating certificates, see Server/client mutual authentication with the Web Services PKCS #11 library.
TLS certificate name
CERTNAME <name of TLS certificate>
Set this to the common name of the client TLS certificate.
TLS certificate store
CERTSTORE <name of certificate store>
Set this to the name of the certificate store that contains the TLS certificate.
TLS certificate store type
STORETYPE <LocalMachine or CurrentUser>
Set this to the type of the certificate store that contains the TLS certificate.
If certificates are stored on LocalMachine , non-administrator users may lose access to their private key.
|
Log file path on Windows
By default, PKCS #11 outputs the logs to C:\ProgramData\nCipher\WebServices\pkcs11\log\pkcs11webservices.log
.
To change the default path set LOGFILEPATH
to any valid existing path.
LOGFILEPATH C:\ProgramData\nCipher\WebServices\pkcs11\log\pkcs11webservices.log
To enable logging for a user, change the path to a Windows user path so that the user has write permission to the folder.
LOGFILEPATH C:\Users\<username>\log\pkcs11webservices.log
Enable logging to event viewer
You can direct PKCS #11 logs to event viewer.
By default this configuration is disabled.
In order to enable this, set EVENTLOG
to 1
in the configuration file.
EVENTLOG 1
Messages in event viewer are limited to a log level of 2(Error)
and lower.
Higher values will not produce additional events.