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.

Web Services server port number

PORT 18001

Set this to the Web Services server port number.

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 3 (Warning).

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 3

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 is 5 and the maximum number is 256.

    To disable retries, set MAXRETRIES to 0.

  • For RETRYDELAY, the default is 10 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 to 0. 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 private key

KEY <path to private key>

Set this to the file path of the client TLS private key.

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

Enable logging to syslog

You can direct PKCS #11 logs to a syslog server. By default this configuration is disabled. In order to enable this, set LOGSYS to 1 in the configuration file.

LOGSYS 1

Configuration parameters for Windows only

For details on creating certificates, see Server/client mutual authentication with the Web Services PKCS #11 library.

TLS thumbprint

THUMBPRINT <storetype>\<store>\<thumbprint>

Certificate thumbprint.

storetype is LocalMachine or CurrentUser

Example:

THUMBPRINT LocalMachine\My\F46DFD2118E64D0A8E0D5FCD0E0987D5C21BB2D5

For details on finding the thumbprint of a certificate see Server/client mutual authentication with the Web Services PKCS #11 library.

If certificates are stored on LocalMachine, non-administrator users may lose access to their private key.
If a certificate is updated, a new thumbprint will be generated and will need to be copied over to the THUMBPRINT line.

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.

Enable fake session public keys

Entrust Certificate Authority generates key pairs where the public key is a session key with CKA_TOKEN set to false. In normal operation, the PKCS #11 library does not support generation of session keys so this special mode is required.

You can direct PKCS #11 to allow the generation of public keys in a key pair that appear like session keys while the session remains open. By default this feature is disabled. In order to enable this, set ENTRUSTCASUPPORT to 1 in the configuration file.

When this feature is enabled, a fake session public key can be generated with C_GenerateKeyPair if CKA_TOKEN is set to false in the public key template.

ENTRUSTCASUPPORT 1
The fake session keys generated are stored in the database like any other token public key with CKA_TOKEN true. They will be seen as token keys in any other sessions or any future sessions.