4 Support Guidance
The support guidance provides information about troubleshooting and vendor specific notes.
- General Troubleshooting
Oracle Key Vault provides general troubleshooting help. Vendor-specific notes cover vendor-specific troubleshooting. - Vendor Specific Notes for Thales Luna
Oracle Key Vault supports Oracle Key Vault integration with Thales Luna (formerly Safenet Luna) SA Hardware Security Modules from Thales Luna version 7000, but does not support Host Trust Link (HTL) for Thales Luna HSM. - Vendor Specific Notes for Entrust
You can integrate Oracle Key Vault release 12.2 BP 3 and later with the HSM from Entrust nShield Connect + and XC models. - Vendor Specific Notes for Utimaco
Oracle Key Vault supports Oracle Key Vault integration with Utimaco SecurityServer 4.31.1.
4.1 General Troubleshooting
Oracle Key Vault provides general troubleshooting help. Vendor-specific notes cover vendor-specific troubleshooting.
- Trace Files for Diagnosing Issues
Oracle Key Vault provides trace files so that you can better diagnose issues that may arise. - HSM Alert
Oracle Key Vault provides an alert mechanism that periodically monitors the HSM configuration to check for Root of Trust key availability and file health. - Could Not Get Slot for HSM Error
TheCould Not Get Slot for HSM
error indicates that Oracle Key Vault could not get a slot from the HSM. - Could Not Load PKCS#11 Library Error
TheCould Not Load PKCS#11 Library
error indicates that Oracle Key Vault could not load the PKCS#11 library. - Oracle Key Vault Management Console Does Not Start After Restarting HSM-Enabled Oracle Key Vault Server
The Oracle Key Vault management console may not appear after you restart the HSM-enabled Oracle Key Vault server. - Primary-Standby Errors
Theokv_security.conf
file contains settings that can help you diagnose primary-standby errors. - Errors from HSM-Enabled Oracle Key Vault Backups
You can use thecwallet.sso
file to diagnose HSM-enabled Oracle Key Vault backup errors. - Restoring an HSM-Enabled Backup
Before you restore a backup that was taken on an HSM-enabled Oracle Key Vault, ensure that you have set the same HSM credential and token label that were used when the backup was taken.
Parent topic: Support Guidance
4.1.1 Trace Files for Diagnosing Issues
Oracle Key Vault provides trace files so that you can better diagnose issues that may arise.
Use these trace files to more finely diagnose issues when you attempt hardware security module operations. These trace files are located in the /var/okv/log/hsm/
directory on the Oracle Key Vault server. To see the most recently failed operation, you can sort the trace files by their last modified time. For example, ls -ltr /var/okv/log/hsm
lists the most recently modified trace files at the bottom of the list.
Parent topic: General Troubleshooting
4.1.2 HSM Alert
Oracle Key Vault provides an alert mechanism that periodically monitors the HSM configuration to check for Root of Trust key availability and file health.
When an Oracle Key Vault server is HSM-enabled, Oracle Key Vault contacts the HSM every five minutes (or whatever you have set the monitoring interval to on the Configure Alerts page) to ensure that the Root of Trust key is available and the TDE wallet password can be decrypted. When a problem in the HSM configuration arises (for example, the HSM cannot be reached or if there are conflicting keys in the HSM with the same ID), then the up arrow on the Hardware Security Module page (accessed by selecting the System tab, then Settings, then in the Network Services area, clicking HSM) switches to a down arrow and an alert is raised. The down arrow signifies that the HSM is not configured or the HSM configuration has a problem. When an alert has been raised, the following error message appears: HSM configuration error. Please refer to the HSM Alert section in the Oracle Key Vault Root of Trust HSM Configuration Guide
.
If this alert appears, then follow these steps:
- Log in as root as follows:
$ ssh support@okv_instance_ip_address support$ su - root
- Back up the SSO wallet. For example:
root# cp /mnt/okvram/cwallet.sso /var/lib/oracle/cwallet_hsm_backup.sso
- Diagnose the source of the alert.
The following
verify
command should show why the alert was raised. Thels -ltrh
command shows the most recent log file at the bottom of the output.root# su - oracle oracle$ /usr/local/okv/hsm/bin/hsmclient verify oracle$ cd /var/okv/log/hsm oracle$ ls -ltrh
- If you cannot resolve this problem, then contact Oracle Support.
Parent topic: General Troubleshooting
4.1.3 Could Not Get Slot for HSM Error
The Could Not Get Slot for HSM
error indicates that Oracle Key Vault could not get a slot from the HSM.
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.
Parent topic: General Troubleshooting
4.1.4 Could Not Load PKCS#11 Library Error
The Could Not Load PKCS#11 Library
error indicates that Oracle Key Vault could not load the PKCS#11 library.
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
Parent topic: General Troubleshooting
4.1.5 Oracle Key Vault Management Console Does Not Start After Restarting HSM-Enabled Oracle Key Vault Server
The Oracle Key Vault management console may not appear after you restart the HSM-enabled Oracle Key Vault server.
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.
Parent topic: General Troubleshooting
4.1.6 Primary-Standby Errors
The okv_security.conf
file contains settings that can help you diagnose primary-standby errors.
-
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
andenctdepwd in
the/usr/local/okv/hsm/wallet
directory andewallet.p12
in the/usr/local/okv/hsm/restore
directory. -
Check that the mode is set to HSM on the standby server:
Open the file
okv_security.conf
asroot
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.
-
Check the vendor-specific instructions.
Parent topic: General Troubleshooting
4.1.7 Errors from HSM-Enabled Oracle Key Vault Backups
You can use the cwallet.sso
file to diagnose HSM-enabled Oracle Key Vault backup errors.
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.
Parent topic: General Troubleshooting
4.1.8 Restoring an HSM-Enabled Backup
Before you restore a backup that was taken on an HSM-enabled Oracle Key Vault, ensure that you have set the same HSM credential and token label that were used when the backup was taken.
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.
Parent topic: General Troubleshooting
4.2 Vendor Specific Notes for Thales Luna
Oracle Key Vault supports Oracle Key Vault integration with Thales Luna (formerly Safenet Luna) SA Hardware Security Modules from Thales Luna version 7000, but does not support Host Trust Link (HTL) for Thales Luna HSM.
- Installing the HSM Client Software on the Oracle Key Vault Server for Thales Luna
You must use the Thales Luna (formerly Safenet Luna) client version 6.2 for Linux x64 for the installation. - HSM Credential for Thales Luna
The HSM credential is the Thales Luna partition password. - Token Label for Thales Luna
The token label for Thales Luna is the name of the partition. - Enrolling Oracle Key Vault as a Client of a Thales Luna HSM
To perform the enrollment, you use the Oracle Key Vault management console and the command-line interface. - HSM Provider Value for Thales Luna
For Thales Luna, the provider value is 1. - HSM Vendor Specific Checks for Thales Luna
You should check the Thales Luna vendor-specific settings.
Parent topic: Support Guidance
4.2.1 Installing the HSM Client Software on the Oracle Key Vault Server for Thales Luna
You must use the Thales Luna (formerly Safenet Luna) client version 6.2 for Linux x64 for the installation.
Parent topic: Vendor Specific Notes for Thales Luna
4.2.2 HSM Credential for Thales Luna
The HSM credential is the Thales Luna partition password.
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.
Parent topic: Vendor Specific Notes for Thales Luna
4.2.3 Token Label for Thales Luna
The token label for Thales Luna is the name of the partition.
Parent topic: Vendor Specific Notes for Thales Luna
4.2.4 Enrolling Oracle Key Vault as a Client of a Thales Luna HSM
To perform the enrollment, you use the Oracle Key Vault management console and the command-line interface.
Parent topic: Vendor Specific Notes for Thales Luna
4.2.5 HSM Provider Value for Thales Luna
For Thales Luna, the provider value is 1.
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.
Parent topic: Vendor Specific Notes for Thales Luna
4.2.6 HSM Vendor Specific Checks for Thales Luna
You should check the Thales Luna vendor-specific settings.
Parent topic: Vendor Specific Notes for Thales Luna
4.3 Vendor Specific Notes for Entrust
You can integrate Oracle Key Vault release 12.2 BP 3 and later with the HSM from Entrust nShield Connect + and XC models.
- Installing the HSM Client Software on the Oracle Key Vault Server for Entrust
The Entrust HSM requires a separate non-HSM computer on the network to use as the remote file system. - HSM Credential for Entrust
The HSM credential for Entrust is the password that is associated with the Operator Card Set or Softcard. - Token Label for Entrust
The token label for Entrust is the name of the Operator Card Set or Softcard. - Enrolling Oracle Key Vault as a Client of an Entrust HSM
You use both the Entrust user interface and the command line to enroll Oracle Key Vault as a client of an Entrust HSM. - HSM Provider Value for Entrust
For Entrust, the provider value is 2.
Parent topic: Support Guidance
4.3.1 Installing the HSM Client Software on the Oracle Key Vault Server for Entrust
The Entrust HSM requires a separate non-HSM computer on the network to use as the remote file system.
Parent topic: Vendor Specific Notes for Entrust
4.3.2 HSM Credential for Entrust
The HSM credential for Entrust is the password that is associated with the Operator Card Set or Softcard.
The HSM-credential if they use an Operator Card Set is the Operator Card Set password. If they use a Softcard, then the password is the Softcard password.
Parent topic: Vendor Specific Notes for Entrust
4.3.3 Token Label for Entrust
The token label for Entrust is the name of the Operator Card Set or Softcard.
Parent topic: Vendor Specific Notes for Entrust
4.3.4 Enrolling Oracle Key Vault as a Client of an Entrust HSM
You use both the Entrust user interface and the command line to enroll Oracle Key Vault as a client of an Entrust HSM.
Parent topic: Vendor Specific Notes for Entrust
4.3.5 HSM Provider Value for Entrust
For Entrust, the provider value is 2.
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.
Parent topic: Vendor Specific Notes for Entrust
4.4 Vendor Specific Notes for Utimaco
Oracle Key Vault supports Oracle Key Vault integration with Utimaco SecurityServer 4.31.1.
- Installing the HSM Client Software on the Oracle Key Vault Server for Utimaco
The setup files for Utimaco are provided in theSecurityServerEvaluation-V4.31.1.0.zip
file from Utimaco. - HSM Credential for Utimaco
The HSM credential for Utimaco is the PIN that was initialized when the token was configured. - Token Label for Utimaco
The token label for Utimaco is the name of the token that was set up for the HSM. - HSM Provider Value for Utimaco
For Utimaco, the provider value is 3. - HSM Vendor Specific Checks for Utimaco
You should check the Utimaco vendor-specific settings.
Parent topic: Support Guidance
4.4.1 Installing the HSM Client Software on the Oracle Key Vault Server for Utimaco
The setup files for Utimaco are provided in the SecurityServerEvaluation-V4.31.1.0.zip
file from Utimaco.
Parent topic: Vendor Specific Notes for Utimaco
4.4.2 HSM Credential for Utimaco
The HSM credential for Utimaco is the PIN that was initialized when the token was configured.
See the Utimaco documentation for more details.
Parent topic: Vendor Specific Notes for Utimaco
4.4.3 Token Label for Utimaco
The token label for Utimaco is the name of the token that was set up for the HSM.
Parent topic: Vendor Specific Notes for Utimaco
4.4.4 HSM Provider Value for Utimaco
For Utimaco, the provider value is 3.
If you are setting this value manually for primary-standby, set HSM_PROVIDER="3"
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.
Parent topic: Vendor Specific Notes for Utimaco
4.4.5 HSM Vendor Specific Checks for Utimaco
You should check the Utimaco vendor-specific settings.
p11tool2 GetSlotInfo
and csadm ListUsers
commands, you can also check to see that a key was created after completing the HSM Initialize operation. Note that more keys may be created after subsequent HSM initialize commands.root# /opt/utimaco/bin/p11tool2 LoginUser=HSM_Credential ListObjects
The output should look similar to the following output:CKO_DATA:
+ 1.1
CKA_LABEL = OKV 18.1 HSM Key Number
CKO_SECRET_KEY:
+ 2.1
CKA_KEY_TYPE = CKK_AES
CKA_SENSITIVE = CK_TRUE
CKA_EXTRACTABLE = CK_FALSE
CKA_LABEL = OKV 18.1 HSM Root Key
CKA_ID = 0x00000001 ()
Parent topic: Vendor Specific Notes for Utimaco