Install the Entrust WSOP Client software on each client.

Each Oracle server needs to have the WSOP client software installed so it can use the WSOP PKCS#11 API library. Make sure you are logged into the Oracle database server as you follow these instructions. To install and configure the WSOP PKCS#11 library, you will have to:

Download and install software.

Untar the WSOP tar file so you can access the Web Services PKCS #11 library

% mkdir wsop
% cd wsop
% tar zxvf /path/to/wsop-p11-3.3.0-714-5306bc4.tar.gz

Sign in as a user with root privileges and extract the PKCS#11 tar to the root directory.

This installs all the files required by PKCS#11 to /opt/nfast/webservices/pkcs11.
```
% sudo su - root
% cd /
% tar zxvf /path/to/wsop/nShield-WebServicesClient-Linux-1.3.0-431-bb1eab8.tar.gz
```

Configure WSOP configuration parameters.

Create the configuration file.

Go to the /opt/nfast/webservices/pkcs11/conf folder and copy the example_pkcs11webservices.cfg file to pkcs11webservices.cfg.
```
% cd /opt/nfast/webservices/pkcs11/conf
% cp example_pkcs11webservices.cfg pkcs11webservices.cfg
```
If required, change the log file destination or grant permission to the appropriate user to write to the default log folder:
```
/opt/nfast/webservices/pkcs11/log
```
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.

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.

The following configuration options are available:
1. Web Services server hostname
  HOST <host name of server>
  Set this to the Web Services server host name.
2. Log level
  LOGLEVEL 4
  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).
3. 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
4. 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.
5. TLS certificate.
  CERT <path to TLS certificate>
  Set this to the file path of the client TLS certificate.
6. TLS private key.
  KEY <path to private key>
  Set this to the file path of the client TLS private key.
7. 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.
8. 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
9. 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

Server / client authentication with the Web Services PKCS #11 library.

The Web Services PKCS #11 Library can only communicate securely with a WSOP Server if the following certificates are installed:

The WSOP Server`s CA certificate.
An appropriate client certificate (with each PKCS #11 client using its own client certificate).
Any intermediate CA certificates that are to be used to form a complete chain to verify the client certificate on the WSOP Server.

The following guidance should be followed when installing the PKCS #11 Library’s certificates in a Linux platform:

If intermediate certificates are used in the PKCS #11 library`s client certificate hierarchy, they should be included in the same file as the client certificate. The root client certificate should not be included in this file.
The recommended format for the client certificate file is PEM.
The recommended format for the client certificate key file is PEM.

Proceed with the following Setup:

Add the WSOP utilities to the PATH.

% export PATH=$PATH:/opt/nfast/webservices/pkcs11/bin

Import client certificates.

These steps copy the client certificates created in the Entrust nShield WSOP server to the application server:

Make a directory where the client certificates will reside.
```
% sudo mkdir -p /opt/ssl/wsop_client
```

Copy the client certificates created in the Entrust nShield WSOP server.

…Copy the CA certificate.

% sudo scp root@WSOP_SERVER_IP_ADDRESS:/opt/nfast/webservices/corecrypto/tls/db/myCA.pem /opt/ssl/wsop_client/.

Copy the Certificate Key.

% sudo scp root@WSOP_SERVER_IP_ADDRESS:/opt/nfast/webservices/corecrypto/tls/external/wsop_client.key /opt/ssl/wsop_client/.

Copy the Client Certificate.

% sudo scp root@WSOP_SERVER_IP_ADDRESS:/opt/nfast/webservices/corecrypto/tls/external/wsop_client.pem /opt/ssl/wsop_client/.

Set the permissions to the certificates so the oracle user owns it.
```
% sudo chown oracle /etc/ssl/wsop_client/*
```

Edit web services option pack configuration file so it can communicate with the WSOP server.

Go to the /opt/nfast/webservices/pkcs11/conf folder and edit the pkcs11webservices.cfg file.
- Set HOST to WSOP_SERVER_IP_ADDRESS
- Set CERT to /opt/ssl/wsop_client/wsop_client.pem
- Set KEY to /opt/ssl/wsop_client/wsop_client.key
- Set AUTH to /opt/ssl/wsop_client/myCA.pem

Open up the permissions to the log file so the application can write to it.

% sudo touch /opt/nfast/webservices/pkcs11/log/pkcs11webservices.log
% sudo chmod 777 /opt/nfast/webservices/pkcs11/log/pkcs11webservices.log

Create a softcard

Because PKCS#11 does not directly support Softcard generation, a command line tool is provided. The Softcard tool uses the same configuration file as the PKCS#11 library for the Web Services server secure connection. It does not support any logging.

To generate a new Softcard run the following command:

% /opt/nfast/webservices/pkcs11/bin/softcardtool -g --name=testSC

When prompted, enter a new passphrase for the Softcard.

If using FIPS Level 3 world make sure an OCS card is available in the WSOP Server to provide FIPS authorization, otherwise the following message will show:

% /opt/nfast/webservices/pkcs11/bin/softcardtool -g --name=mysoftcard
New softcard generation
Enter softcard pass phrase:
Verifying - Enter softcard pass phrase:

Failed to generate softcard errorcode WSOP_ERROR_HTTP_RESPONSE
Error message: BadRequest: fips auth required for operation but not available: card not in slot

Check WSOP Web Server connection.

Become the oracle user and test the connection. To verify the Web Services server connection, run the tool with the verbose and list options:

% /opt/nfast/webservices/pkcs11/bin/softcardtool -vl

Connecting to xxx.xxx.xxx.xxx port 18001 with:
Client Certificate File /opt/ssl/wsop_client/wsop_client.pem
Client Private Key File /opt/ssl/wsop_client/wsop_client.key
Certificate Authority file /opt/ssl/wsop_client/myCA.pem
Server connection health check passed

Softcard list
ID                                   "Name"

You can also use the following curl command to check the connection:

% curl -X GET --cacert /opt/ssl/wsop_client/myCA.pem \
	    --cert /opt/ssl/wsop_client/wsop_client.pem \
	    --key /opt/ssl/wsop_client/wsop_client.key \
	    --header 'Content-Type: application/json' \
	    --header 'Accept: application/json' 'https://WSOP_SERVER_IP_ADDRESS:18001/km/v1/groups' | jq

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   496  100   496    0     0   4769      0 --:--:-- --:--:-- --:--:--  4769
{
  "groups": [
    {
      "groupid": "ad319421-031f-5261-a1e6-6f04849be23e",
      "keys": "/km/v1/groups/ad319421-031f-5261-a1e6-6f04849be23e/keys",
      "name": "Module Protection",
      "protection": "/km/v1/protectiondomains/ad319421-031f-5261-a1e6-6f04849be23e",
      "type": "Module"
    },
    {
      "groupid": "2bd40730-85b1-5deb-8417-fb78a7735743",
      "keys": "/km/v1/groups/2bd40730-85b1-5deb-8417-fb78a7735743/keys",
      "name": "Well-Known Key Protection",
      "protection": "/km/v1/protectiondomains/2bd40730-85b1-5deb-8417-fb78a7735743",
      "type": "WellKnown"
    }
  ]
}

Deleting a softcard and its keys.

If you need to delete a Softcard, and remove all keys associated with the Softcard and use the following command:

% /opt/nfast/webservices/pkcs11/bin/softcardtool -d -i <deleted-softcard-ID>