Consult the most recent trace files for more details. Possible causes include providing an invalid or nonexistent token label and the HSM failing to return a list of slots.

Possible reasons for this error could be due to file permission issues or failing to properly deploy the HSM client software on Oracle Key Vault. More details can be found in recent trace files. Oracle looks for the PKCS#11 library at the following locations, depending on the vendor:

• For Thales Luna, /usr/safenet/lunaclient/lib/libCryptoki2_64.so
• For Entrust, /opt/nfast/toolkits/pkcs11/libcknfast.so
• For Utimaco, /opt/utimaco/lib/libcs_pkcs11_R2.so

If this happens, then log into the Oracle Key Vault server using SSH as user support and try manually opening the wallet as follows:

$ ssh support@okv_instance_ip_address
support$ su root 
root# su oracle
oracle$ cd /usr/local/okv/hsm/bin
oracle$ ./hsmclient open_wallet

If the open_wallet command succeeds, the database will open and the management console will appear, unless there is another non-HSM problem. If the command does not succeed, then check the recent log files under /var/okv/log/hsm and check for vendor-specific instructions.

1. Check that the files have been transported to the standby server.

   Execute the command ls -l as root on the standby server:

   root# ls -l /usr/local/okv/hsm/wallet
   -rw------- 1 oracle oinstall 324 May 16 22:57 cwallet.sso
   -rw------- 1 oracle oinstall 176 May 16 22:57 enctdepwd
   root# ls -l /usr/local/okv/hsm/restore
   -rw------- 1 oracle oinstall 320 May 16 22:57 ewallet.p12
   

   You should see cwallet.sso and enctdepwd in the /usr/local/okv/hsm/wallet directory and ewallet.p12 in the /usr/local/okv/hsm/restore directory.

2. Check that the mode is set to HSM on the standby server:

   Open the file okv_security.conf as root on the standby server:

   root# cat /usr/local/okv/etc/okv_security.conf
    Look for the line:
    HSM_ENABLED="1"
   

   You should see the number within double quotes.

3. Check the vendor-specific instructions.

You should check that the pre_restore command has been run on the target as follows:

Execute the command ls -l as root on the Oracle Key Vault server to which you are restoring the backup:

root# ls -l /usr/local/okv/hsm/wallet
-rw------- 1 oracle oinstall 324 May 16 22:57 cwallet.sso

You should see the wallet file cwallet.sso, which indicates that the credential has successfully been set and stored on Oracle Key Vault.

You should also check that you have followed the instructions from the HSM vendor. In addition, check the most recent log files generated by the recent backup restore, which are in the /var/okv/log/db directory.

The HSM credential for Thales Luna is the Thales Luna partition password. For Entrust, the credential is the password that is associated with the Operator Card Set or Softcard. For Utimaco, the credential is the PIN that was initialized when the token was configured.

When using the Set Credential operation, if you enter an incorrect credential or token label, or if Oracle Key Vault is unable to connect to the HSM, then the operation will not succeed and the credential, token label, and vendor provided will not be stored. Ensure that Oracle Key Vault has been enrolled as a client of the HSM and then ensure that the correct credential and token label are entered such that Oracle Key Vault will be able to access the same Root of Trust key that was in use when the backup was taken.

For more information about enrolling Oracle Key Vault as a client of the HSM, see Enrolling Oracle Key Vault as a Client of the HSM.

1. Obtain the Thales Luna client software package, version 6.2 for Linux x64.

2. Transport the Thales Luna client software package to the Oracle Key Vault machine. Oracle recommends using SCP. For example, assuming the Thales Luna client software packages is called safenet.tar:

   $ scp safenet.tar support@okv_instance_ip_address:/tmp

3. Install the Thales Luna client software on Oracle Key Vault.

4. Log in to the Oracle Key Vault Server through SSH as user support, and switch user (su) to root:

   $ ssh support@okv_instance_ip_address
   support$ su root
   root# cd /usr/local/okv/hsm

5. Find the Linux 64-bit packages:

   root# tar -tvf /tmp/safenet.tar | grep 'linux/64/'; Output: "SafeNet_package_version/linux/64/"

6. Only extract the Linux 64-bit packages:

   root# tar -xvf /tmp/safenet.tar SafeNet_package_version/linux/64/
   root# cd SafeNet_package_version/linux/64
   root# ./install.sh

7. Accept the Thales Luna license by typing y at the prompt.

8. Install the Luna SA by entering 1, n, i at the successive prompts.

   This installs the Thales Luna software in the directory /usr/safenet/lunaclient .

9. Delete the safenet.tar file from /tmp directory.

   root# rm -f /tmp/safenet.tar

If you are using Thales Luna as your HSM, then you can use the Thales Luna assignPassword command to assign a password for a partition. However, do not do this when a partition is currently in use by an Oracle Key Vault server, because Oracle Key Vault will no longer be able to access the Root of Trust key as its stored credential will no longer be correct.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Set up the DNS servers.

   When enrolling Oracle Key Vault as a client of a Thales Luna HSM, if the HSM will be registered using a host name, you should first set up DNS using the Oracle Key Vault the management console. To access the DNS settings, select the System tab, and then from the left menu, select System Settings.

   You must configure the DNS servers on each Oracle Key Vault server that you plan to register as a client of the HSM. In a primary-standby environment, configure the DNS servers on both primary and standby server before pairing. For a multi-master cluster, configure DNS on each node in the cluster that will be registered as a client of the HSM.

3. Exchange certificates between Oracle Key Vault and the Thales Luna SA HSM.

   Log in to the Oracle Key Vault Server through SSH as user support, and switch user (su) to root:

   $ ssh support@okv_instance_ip_address
   support$ su root 
   root# cd /usr/safenet/lunaclient/bin 
   root# scp admin@hsm_hostname:server.pem . 
   root# ./vtl addServer -n hsm_hostname -c server.pem 
   root# ./vtl createCert -n okv_hostname 
   root# scp /usr/safenet/lunaclient/cert/client/okv_hostname.pem admin@hsm_hostname:

   You must enter the HSM administrative password when using SCP with the HSM.

4. Register Oracle Key Vault as a client of the Thales Luna SA.

   This assumes that you have a partition set up on the Thales Luna SA HSM. You can use any client name that is not yet taken. Oracle recommends using a descriptive name that will identify the Oracle Key Vault instance.

   Access the HSM administrative console by using SSH to admin@hsm_hostname and providing the administrative password:

   $ client register -client client_name -hostname okv_hostname
   $ client hostip map -c client_name -i okv_ip_address
   $ client assignPartition -client client_name -partition partition_name

5. Verify the enrollment as follows:

   Log in to Oracle Key Vault as the support user using SSH:

   $ ssh support@okv_instance_ip_address
   support$ su root 
   root# cd /usr/safenet/lunaclient/bin 
   root# ./vtl verify

   The following output appears:

   The following Luna SA Slots/Partitions were found:
   
   Slot    Serial #        Label
   ====    ==========      =====
    1      serial_number   partition_name
    

If you are setting this value manually for a primary-standby configuration, then set HSM_PROVIDER="1" in the okv_security.conf file. For more information about enabling HSM in a primary-standby deployment, see Enabling HSM in a High Availability Deployment.

You can verify the connection to the HSM for every Oracle Key Vault server as follows:

Log in to the Oracle Key Vault server as user support using SSH:

$ ssh support@okv_instance_ip_address
support$ su root
root# cd /usr/safenet/lunaclient/bin
root# ./vtl verify

The following output appears when the HSM is set up properly:

The following Luna SA Slots/Partitions were found:

Slot    Serial #        Label
====    ========        =====
 1      [serial #]      [partition name]

If you do not see this output, then it means that the HSM is not set up properly. You can diagnose further as follows:

1. Log into the Thales Luna SA administrative console.

2. Type the command: client show -client client_name

3. Verify that the expected client exists and is assigned a partition.

4. If it does not exist, register the client with the command:

   client register -client client_name-hostname host_name

5. If no partition is assigned, assign a partition with the command:

   client assignPartition -client client_name -partition partition_name

6. Verify that all client IP addresses are mapped correctly. If entries are missing, run the command:

   client hostip map -c client_name -i ip_address

7. Verify that Oracle Key Vault can reach the HSM using the vtl verify command:

   $ su root
   root# cd /usr/safenet/lunaclient/bin
   root# ./vtl verify

   The output should look similar to the following output:

   The following Luna SA Slots/Partitions were found:
   
   Slot    Serial #        Label
   ====    ========        =====
    1      [serial #]      [partition name]

   If the command fails, then it means that the Oracle Key Vault server is unable to contact the HSM. Check the vendor’s other troubleshooting sections for instructions to restore vtl verify functionality. Contact your HSM administrator and confirm that Oracle Key Vault's access to the HSM has not been revoked. If you are unable to resolve the problem, then contact Oracle Support.

After setting up the remote file system, you can proceed with the following steps:

1. Log in to the Oracle Key Vault server as support user using SSH:

   $ ssh support@okv_instance_ip_address

2. Switch to root:

   support$ su root

3. Go to the root directory and create the directories ctls, hwsp, and pkcs11:

   root# cd /root
   root# mkdir ctls
   root# mkdir hwsp
   root# mkdir pkcs11

4. Transfer the Entrust software installation files using the Secure Copy (SCP) protocol as follows:

   For example:

   root# scp user@remote_file_system_computer:/source_directory/ncipher/nfast/ctls/agg.tar ctls
   root# scp user@remote_file_system_computer:/source_directory/ncipher/nfast/hwsp/agg.tar hwsp
   root# scp user@remote_file_system_computer:/source_directory/ncipher/nfast/pkcs11/user.tar pkcs11
   

5. Install these files as follows:

   root# cd /
   root# tar xvf /root/ctls/agg.tar
   root# tar xvf /root/hwsp/agg.tar
   root# tar xvf /root/pkcs11/user.tar
   root# /opt/nfast/sbin/install
   

6. As root, perform additional edits on the Oracle Key Vault server:

   root# usermod -a -G nfast oracle
   root# cd /etc/rc.d/rc5.d
   root# mv S50nc_hardserver S40nc_hardserver
   root# cd /etc/rc.d/rc3.d
   root# mv S50nc_hardserver S41nc_hardserver

7. Switch to user oracle and verify the installation:

   root# su oracle
   oracle$ PATH=/opt/nfast/bin:$PATH
   oracle$ export PATH
   oracle$ enquiry

   The state should say operational in the output.

8. Restart Oracle Key Vault for the group change to take effect.

   In the Oracle Key Vault management console, log in as a user with the System Administrator role. Select the System tab, and then select System Settings. Then click the Reboot button.

If you are setting this value manually for the primary-standby, then set HSM_PROVIDER="2". For more information about enabling HSM in a primary-standby deployment, see Enabling HSM in a High Availability Deployment.