PKCS 11

The Web Services PKCS #11 Library allows you to run PKCS #11 applications from a WSOP client.

The client machine that the PKCS #11 tar is installed to does not require any existing WSOP or Security World Software to be present.

Installation

To install PKCS #11:

Sign in as a user with root privileges.
Change to the root directory.
Extract the PKCS #11 tar to the root directory. This installs all the files required by PKCS #11 to /opt/nfast/wsop/pkcs11.
```
tar –xzf /path/to/pkcs11-1.0.0.tar.gz
```
If you are installing the PKCS #11 library for the first time, go to the /opt/nfast/wsop/pkcs11/conf folder and copy the example_pkcs11wsop.cfg file to pkcs11wsop.cfg.

If you are reinstalling or updating the PKCS #11 library and do not want to overwrite your existing pkcs11wsop.cfg file, you can skip this step.
If required, change the log file destination or grant permission to the appropriate user to write to the default log folder: /opt/nfast/wsop/pkcs11/log. For help changing the logging path, see Change log to file destination.

Configuration

Configure PKCS #11 using the /opt/nfast/wsop/pkcs11/conf/pkcs11wsop.cfg file.

The pkcs11wsop.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 the certificate, root certificate, and key files have restrictive access control, so that only the application using the PKCS #11 client library has access to these files.

Server listening host

HOST <host name of server>

Set this to the WSOP server host name.

Server listening port

PORT 18001

Set this to the WSOP server port number.

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.

Logging level

The LOGLEVEL field in the configuration file controls the PKCS #11 library logging. The available log levels are:

0(None)
1(Panic)
2(Error)
3(Warning)
4(Info)
5(Debug)
6(Trace)

By default, the PKCS #11 logging level is set at 4 (Info).

Higher log levels include all logs from lower levels. If the logging level is set to 4(Info), you only get log events with Info, Warning, Error, and Panic. If the logging level is set to 6(Trace) it enables all the log levels. To turn off logging set LOGLEVEL to 0(None).

LOGLEVEL 4

Logs that are not at TRACE level have the message prefixed with standard fields:

Timestamp with format [yyyy-mm-dd hh:mm:ss]
Level (one of DEBUG INFO WARNING PANIC)
PKCS #11 library name
Process ID

Logs at TRACE level add fields for thread ID and session handle in prefix:

Timestamp with format [yyyy-mm-dd hh:mm:ss]
Level (TRACE)
PKCS #11 library name
Process ID
Thread ID
PKCS #11 session handle (zero if not used)

Change log to file destination

By default, PKCS #11 outputs the logs to /opt/nfast/wsop/pkcs11/log/pkcs11wsop.log. To change the default path set LOGFILEPATH to any valid path.

LOGFILEPATH pkcs11wsop.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/pkcs11wsop.log

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

Enable logging to syslog

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

LOGSYS 1

Retry WSOP communication

Since the PKCS #11 library operates over a network connection, it is possible that network fluctuations could cause an internal request to the WSOP 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 either entry is not provided, its default will be used.

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.

Server/client mutual authentication

For details on the TLS connection setup, see WSOP TLS setup.

Utility tools

In WSOP 3.0 and later versions, you can use four example programs to obtain information about Softcards:

`ckinfo`	Version of the PKCS#11 library.
`cklist`	Objects created on the Softcard.
`ckmechinfo`	Supported mechanisms.
`softcardtool`	Version of the tool that generated the Softcard. Run these programs with the following commands:

/opt/nfast/wsop/pkcs11/bin/ckinfo-dynamic --library /opt/nfast/wsop/pkcs11/lib/libpkcs11wsop.so
/opt/nfast/wsop/pkcs11/bin/ckmechinfo-dynamic --library /opt/nfast/wsop/pkcs11/lib/libpkcs11wsop.so
/opt/nfast/wsop/pkcs11/bin/cklist-dynamic --library /opt/nfast/wsop/pkcs11/lib/libpkcs11wsop.so
/opt/nfast/wsop/pkcs11/bin/softcardtool -g --name=<new-softcard-name>

Softcard generation tool

Because PKCS #11 does not directly support Softcard generation, a command line tool is available at /opt/nfast/wsop/pkcs11/bin/softcardtool

The Softcard tool uses the same configuration file as the PKCS #11 library for the WSOP server secure connection. For more information, see Configuration.

To generate a new Softcard, navigate to the /opt/nfast/wsop/pkcs11 folder and run the following command:

./bin/softcardtool -g --name=<new-softcard-name>

When prompted, enter a new passphrase for the Softcard.

Special characters for name and passphrase are not supported.

To verify the WSOP server connection, run the tool with the verbose and list options:

./bin/softcardtool -vl

To delete a softcard, remove all keys associated with the softcard and use the following command:

./bin/softcardtool -d --ID=<deleted-softcard-ID>

To see all the available options, run

./bin/softcardtool --help

Usage softcardtool [OPTION]
Options:
    -g,	--generate 		generate a new softcard
	-d,	--delete   		delete softcard by ID
	-l,	--list     		list softcards
	-v,	--verbose  		verbose output
	-n,	--name NAME		name of softcard to generate
	-i,	--id ID    		ID of softcard to delete

Supported functions

The following sections list the PKCS #11 functions supported by the PKCS #11 library. For a list of supported mechanisms, see Mechanisms.