Oracle Key Vault

Set up Luna HSM

Set up Oracle Key Vault

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later on used by Oracle Key Vault.

Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.

Initialize Crypto Officer and Crypto User roles for the registered partition.

Run the following command to verify that the partition has been successfully registered and configured:

/usr/safenet/lunaclient/bin/lunacm 

Upon successful execution, you should observe an output similar to the example provided below:

lunacm (64-bit) v10.4.0-417. Copyright (c) 2021 Thales Group. All rights reserved. 
Available HSMs:
Slot Id ->                           0
Label ->                             TPA01
Serial Number ->                     1312109862206
Model ->                             LunaSA 7.7.1
Firmware Version ->                  7.7.1
Bootloader Version  ->               1.1.2
Configuration ->                     Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      Non-FM
Current Slot ID:                     0

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

For proper configuration of a PED-based Luna HSM, it is recommended to activate partition policies 22 and 23, allowing for both activation and auto-activation.

Ensure that you possess sudo privileges on the client workstation.

Add a user to the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the actual username you want to include in the hsmusers group.

Confirm that you hold sudo privileges on the client workstation.

Eliminate a user from the hsmusers group using the command:

sudo gpasswd --add <username> hsmusers

Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.

Any user you remove will retain access to the HSM device until the client workstation is rebooted.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Log in to the Oracle Key Vault server via SSH using the support user, and then switch to the root user for administrative privileges.

Skip steps 1-9, if you are using Luna Client v6.x or standalone Luna Cloud HSM with a minimum client package.

Execute the command below to add the Oracle user to the hsmusers group:

gpasswd --add oracle hsmusers

Reboot the Oracle Key Vault to apply the changes.

reboot

Log in to the Oracle Key Vault server via SSH using the support user, and then switch to the root user.

Skip steps 4-9 and start directly from step 10 if you are using Oracle Key Vault v21.2 or lower.

Navigate to the following directory:

cd /usr/local/okv/hsm/generic

Starting from Oracle Key Vault v21.3, Oracle provides an interface to enable Luna HSM using Luna Client other than v6.x.

Open the okv_hsm.conf file using a text editor and make the following changes.

# The vendor name, to be displayed on the HSM page on the management console.
VENDOR_NAME="Thales_Luna"

# The location of the PKCS#11 library. This file must be preserved on upgrade.
PKCS11_LIB_LOC="/usr/safenet/lunaclient/lib/libCryptoki2_64.so"

# A colon-separated list of the full paths of files and directories that must be preserved on upgrade. 
PRESERVED_FILES="/usr/safenet/lunaclient:/etc/Chrystoki.conf:/usr/safenet/lunaclient/lib/libCryptoki2_64.so"

While all the parameters mentioned above are essential, the PRESERVED_FILES parameter will only be applicable during the next major version upgrade.

Open the okv_hsm_env file using a text editor and make the following changes:

# Below is an example. Remove the '#' character to uncomment the line.
EXAMPLE_ENV_VAR_NAME="EXAMPLE_ENV_VAR_VALUE"

ChrystokiConfigurationPath="/etc"

Open the okv_hsm_mid_upgrade file using a text editor and make the following changes:

#######################################################################
Do not make changes above this line
#######################################################################
# For now, this script does nothing, so log it and exit.
logger -t "${LOGTAG}" -p "${LOGDEBUG}" "Adding hsmusers group”

sudo groupadd hsmusers
exit ${DBFW_PM_CHANGED}

# Until changes are added, exit indicating that no changes occurred.
#exit ${DBFW_PM_NO_CHANGE_REQUIRED}

# If changes are made and were successful, you should exit like the commented code below:
#exit ${DBFW_PM_CHANGED}

Reboot the Oracle Key Vault server for the changes to take effect.

reboot

Log in to Oracle Key Vault Management Console through https://, using credentials for a user with system administrator privileges.

The System Admin user credentials are created during Oracle Key Vault installation and configuration.

Navigate to System tab.

Access HSM Settings based on your Oracle Key Vault version.

• For Oracle Key Vault v21.1 or above, click Settings in the left sidebar. Under Network Services, click HSM.

• For Oracle Key Vault v18.5 or below, click Hardware Security Module in the left sidebar.

Check the HSM initialization status. If the HSM is not initialized, a red arrow pointing down will be visible in the Status field.

Click Initialize. The Initialize HSM dialog will appear on the screen.

Open the Vendor drop-down menu and select vendor:

• For Oracle Key Vault v21.3 onwards using Luna Client other than v6.x, choose the Vendor as defined in the okv_hsm.conf file.

• For Oracle Key Vault v21.2 or below, choose Thales as the Vendor listed at the top.

In earlier versions of Oracle Key Vault (18.4 or lower), select SafeNet in the Vendor drop-down menu. Thales is available from Oracle Key Vault v18.5 onwards.

Provide the HSM Credential (partition password) and the Recovery Passphrase (set during the post-installation setup of Oracle Key Vault). Check the Use Token Label checkbox and enter the Token Label.

Beginning with Oracle Key Vault 18.4, use the Token Label, especially in scenarios where multiple partitions are registered. The Token Label functionality is not supported for Oracle Key Vault versions earlier than 18.4.

Click the Initialize button. On success, you will receive a confirmation message.

Check the HSM Status after initialization. A green arrow pointing up with HSM partition details should be visible.

If you've changed the HSM credential post-initialization, it is essential to synchronize the updated HSM credential with the Oracle Key Vault server. To achieve this, use the Set Credential option.

Execute the following command in lunacm to verify the master encryption key generated on the partition:

lunacm:> par con

Ensure Oracle Key Vault is version 21.3 or above and integrated with Luna Client other than v6.x.

Log in to the Oracle Key Vault server through SSH as the support user and switch to the root user for administrative privileges.

Create a script named pre-upgrade-luna.sh in the /opt directory with the followng content. The script checks the connectivity of Oracle Key Vault with the Luna HSM before proceeding with the upgrade.

#!/bin/bash
chown -R root:root /etc/Chrystoki.conf
chmod 644 /etc/Chrystoki.conf
chmod -R g-s /usr/safenet/lunaclient/cert
chown -R root:root /usr/safenet/lunaclient/cert
chmod -R 755 /usr/safenet/lunaclient/cert
chmod -R g-s /usr/safenet/lunaclient/configData
chown -R root:root /usr/safenet/lunaclient/configData
chmod -R 755 /usr/safenet/lunaclient/configData
chmod -R g-s /usr/safenet/lunaclient/data
chown -R root:root /usr/safenet/lunaclient/data
chmod -R 777 /usr/safenet/lunaclient/data
sudo -u oracle /usr/safenet/lunaclient/bin/vtl listslots

Create a script named post-upgrade-luna.sh in the /opt directory with the following content. The script checks the connectivity of Oracle Key Vault with the Luna HSM after the upgrade.

#!/bin/bash
gpasswd --add oracle hsmusers
chown -R root:hsmusers /etc/Chrystoki.conf
chmod 660 /etc/Chrystoki.conf
chmod -R 755 /usr/safenet/lunaclient/bin
chmod -R 755 /usr/safenet/lunaclient/lib
chmod -R 755 /usr/safenet/lunaclient/plugins
chown -R root:hsmusers /usr/safenet/lunaclient/cert
chmod -R 2770 /usr/safenet/lunaclient/cert
chmod 664 /usr/safenet/lunaclient/cert/client/*
chmod 664 /usr/safenet/lunaclient/cert/server/*
chown -R root:hsmusers /usr/safenet/lunaclient/configData
chmod -R 2770 /usr/safenet/lunaclient/configData
chmod 664 /usr/safenet/lunaclient/configData/token/001/*
chown -R root:hsmusers /usr/safenet/lunaclient/data
chmod -R 2770 /usr/safenet/lunaclient/data
chmod -R 2777 /usr/safenet/lunaclient/data/*
sudo -u oracle /usr/safenet/lunaclient/bin/vtl listslots

Execute the pre-upgrade script to check Luna HSM connectivity before upgrading.

/opt/pre-upgrade-luna.sh

Ensure that the output of pre-upgrade-luna.sh command displays information about the available slots on the Luna HSM. If the command executes successfully and returns information about the slots, it indicates that the Oracle Key Vault can communicate with the Luna HSM and that the HSM is responsive. On the other hand, if there are any issues with connectivity, the command might produce an error message or not provide the expected slot information. In such cases, administrators would need to troubleshoot and resolve any connectivity issues before proceeding with the upgrade to ensure the proper functioning of the integrated Oracle Key Vault and Luna HSM system.

Execute the upgrade command, as mentioned in the Oracle Key Vault Upgrade documentation

/usr/bin/ruby /images/upgrade.rb --confirm

Running the upgrade without the pre-upgrade script may result in failure. It is crucial to perform a pre-upgrade backup following the instructions provided in the Oracle Key Vault Upgrade documentation. Ensure that all necessary precautions are taken to safeguard your data and ensure a smooth upgrade process.

Follow the Oracle Key Vault Upgrade documentation to complete the upgrade successfully.

/usr/bin/ruby /images/upgrade.rb --confirm

Log in to the Oracle Key Vault management console and navigate to Settings > Hardware Security Module to verify that Luna HSM is enabled in the upgraded version.

Execute the post-upgrade script to check Luna HSM information after the upgrade.

/opt/post-upgrade-luna.sh

Ensure that the output of post-upgrade-luna.sh displays Luna HSM information.

Proceed with the post-upgrade steps as per the Oracle Key Vault documentation.

If post-upgrade-luna.sh fails to display Luna HSM information, contact Thales Customer Support without restarting the Oracle Key Vault server.

Log in to the Oracle Key Vault management console using a user account with System Administrator privileges.

For Oracle Key Vault v21.1 or later, navigate to System > Settings and click Backup and Restore under System Configuration. For versions v18.5 or below, go to the System tab and click on System Backup in the left sidebar. This will display a list of scheduled and completed backups.

Click Manage Backup Destinations to view all configured backup destinations.

Click Create.

Enter the following information for the backup location:

a. Destination Name: Specify a name for the destination.

b. Transfer Method: By default, set to SCP for secure file copying.

c. Hostname: Enter the IP address of the backup destination. If DNS is configured, provide the hostname.

d. Port: Specify the Port number for SCP. The default is 22.

e. Destination Path: Enter the actual path on the backup destination.

f. Username: Enter the username with read-write permission for the destination path.

g. Authentication Method: Choose between key-based or password-based authentication. For key-based authentication, enter the public key. For password-based authentication, enter the password.

Click Save. Oracle Key Vault will verify the specified destination. If the validation process fails, the destination will not be created.

You can adjust these settings at any time, with the exception of when performing a restoration from a backup.

Click on System Backup > Backup once the destination is created.

Enter the following information for the backup:

a. Name: Assign a name for easy identification of the backup.

b. Start Time: Opt for a specific time for the backup to commence. If immediate, select Now.

c. Destination: Select between a local or remote destination.

d. Type: Choose between One-Time or Periodic. If Periodic is selected, specify the scheduled backup time.

Click Schedule. This enables real-time monitoring of the backup status, categorized as ACTIVE, ONGOING, PAUSED, or DONE. When the backup is in progress, the status will be ONGOING, and upon completion, it will change to DONE.

Verify the backup files on the backup destination.

Log in to the Oracle Key Vault management console as a user with System Administrative privileges.

For Oracle Key Vault v21.1 or above, navigate to Settings. Under Network Services, click HSM. For Oracle Key Vault v18.5 or below, in the left sidebar, click Hardware Security Module.

Validate the HSM status. If the status appears as disabled, click Set Credential to open the Prepare for HSM Restore dialog.

Skip steps 4-6 if the HSM status is already enabled with a Green Arrow pointing UP.

Open the Vendor drop-down menu and select the Vendor.

• For Oracle Key Vault v21.3 onwards, when using Luna Client other than v6.x, choose the Vendor as per the VENDOR_NAME defined in the okv_hsm.conf file.

• For Oracle Key Vault v21.2 or below, choose Thales as the Vendor listed at the top.

• For versions 18.4 or lower, select SafeNet in the Vendor drop-down menu. Thales is available since Oracle Key Vault v18.5 onwards.

Enter the partition password in the HSM Credential field. Select Use Token Label and input the token label. Click Set Credential.

In earlier versions of Oracle Key Vault (v18.3 or below), the option to select token label is not available. With token label, you can choose any token if multiple tokens are registered.

For Oracle Key Vault v21.1 or above, navigate to Settings from the left sidebar, and select Backup and Restore under System Configuration. For Oracle Key Vault v18.5 or below, click System Backup in the left sidebar.

Click Restore. Choose the source where the backup files are stored. The available backups on the source will be listed. Select the backup you want to restore.

Click Restore.

Enter the recovery passphrase set during the Post Installation Step of Oracle Key Vault and click Restore. The restore process will commence, and the status will be displayed as ONGOING.

During the restore process, the Oracle Key Vault management console may not be functional. Avoid making any configuration changes until the restore is completed. The system will be restored from the backup and then restarted. The system will be available after the completion of the restore process.

Convert an existing Oracle Key Vault Server into the first node of the cluster

HSM-enable the first node

HSM-enable the candidate node before adding it to the cluster

Add the HSM-enabled candidate node to the cluster using HSM-enabled (first) controller node

If any node in the cluster is already HSM-enabled, adding a new node that lacks HSM-enablement is not permitted. The Add Node to Cluster page on the controller node will necessitate HSM credentials of the controller node.

Ensure data integrity by performing a backup of the Oracle Key Vault server.

Log in to the Oracle Key Vault Management console with System Administrator credentials.

Generate and activate a new certificate if the Oracle Key Vault server was upgraded from a release earlier than Oracle Key Vault release 12.2 (bundle patch 8).

Navigate to the Cluster tab in the Oracle Key Vault management console.

Access the Configure as Candidate Node page, where the IP address of the current server is shown in the Current Server IP field.

Enter the following information:

• First Node of Cluster: Choose Yes.

• Node Name: Assign a unique name for this node.

• Cluster Name: Specify a name for this cluster of nodes.

• Cluster Subgroup: Provide a name for this subgroup of nodes, such as a data center name or logical group name.

Click the Convert to Candidate Node button. After the conversion process is complete, the Cluster Management page will appear, indicating that the node is now operating in read-only restricted mode.

Confirm the successful conversion by checking the Cluster Details on the Cluster Management page.

Perform a backup: Prior to proceeding, ensure a backup of the controller node is completed.

Confirm the following network prerequisites:

• Ensure robust connectivity between the servers hosting the controller and candidate nodes.

• Verify that the required ports for Oracle Key Vault are open in the network firewall (Refer to Network Port Requirements in Oracle Key Vault Documentation).

Log into the first (controller) node: Access the Oracle Key Vault Management Console on the first (controller) node using credentials with the System Administrator role. Any existing node, including the first node without a read-write peer, can serve as the controller for this operation. Add a read-only node if needed.

Navigate to the cluster tab: Select the Cluster tab to initiate the node addition process.

Initiate node addition: Click on the Add option.

Enter Recovery Passphrase: Provide the recovery passphrase of the cluster. This passphrase will be utilized during the pairing process with the candidate node.

Specify Read-Write Peer: Choose Yes to designate the added node as a read-write peer during the addition process.

Enter Candidate Node Details:

a. Node ID: Choose a unique ID for the candidate node. Note that this ID is permanent.

b. Node Name: Input a distinctive name for the candidate node. This name is permanent once created.

c. Cluster Subgroup: Enter the subgroup name for the candidate node. Use an existing subgroup or create a new one. Subgroup selection is permanent after the node joins the cluster.

d. IP Address: Specify the IP address of the candidate node. Do not save or click the Add Node button yet.

Access Oracle Key Management Console:

• Log into the Oracle Key Vault management console of the candidate node as a user with the System Administrator role.

• Select the Cluster tab to display the Configure as Cluster Candidate page.

Configure Candidate Node:

a. First Node of Cluster: Select No.

b. Recovery Passphrase of the Cluster: Enter the recovery passphrase of the cluster created earlier for the controller node.

c. IP Address: Enter the IP address of the controller node.

Certificate Handling:

• Scroll to the bottom of the controller node's screen, select and copy the entire node certificate.

• In the candidate node's window, paste the certificate copied from the controller node into the Certificate of the Controller Node field.

Verify the recovery passphrase, IP address, and the pasted certificate carefully. Any errors may require Oracle Key Vault reinstallation.

Convert to Candidate Node: Click the Convert to Candidate Node button. Once the process is finished, the screen will refresh and Adding Candidate Node to Cluster page will appear, displaying the certificate of the candidate node. This step might take several minutes to complete.

Certificate Exchange:

• Select and copy the entire candidate node certificate.

• In the controller node's browser window, paste the certificate copied from the candidate node into the Certificate of Candidate Node box.

HSM Credential and Finalization:

• Add the HSM Credential (partition password).

• Click Add Node.

• Confirm by clicking OK in the dialog box.

Verification: Ensure that both nodes display an ACTIVEstatus with Read-Write Peer mode after the pairing process is finished. The duration of this process may vary depending on server speed, network quality, and cluster data volume. It's normal for network interfaces to restart during this period, and you may encounter momentary internal server error on the controller node and bad gateway error on the candidate node. These issues are expected, and the status of both nodes should eventually stabilize as ACTIVE in Read-Write Peer mode.

HSM-enable the first node

Create and copy the bundle after HSM-enabling the first node

Configure the remaining nodes

Before moving on to the primary steps, it is essential to have a multi-master cluster set up ready with multiple nodes.

Log in to the Oracle Key Vault management console as a user with the System Administrator role.

Click the System tab:

• For Oracle Key Vault v21.1 or above, click Settings. Under Network Services, select HSM.

• For Oracle Key Vault v18.5 or below, in the left sidebar, click Hardware Security Module.

On the HSM-enabled node, navigate to the HSM page and click Create Bundle.

In the Create Bundle dialog box, make the following changes:

• In the HSM Credential field, enter the HSM password.

• In the Recovery Passphrase field, enter the recovery passphrase.

• Click the Create Bundle button.

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

Copy the bundle to the /usr/local/okv/hsm location on all the other nodes using the IP address:

scp /usr/local/okv/hsm/hsmbundle support@ip_address:/tmp

Ensure to perform these steps diligently to complete the bundle creation and copying process.

Log in to each node in the cluster using the IP address (excluding the original HSM-enabled node):

ssh support@ip_address

Switch to the root user on each node:

su root

Copy the /tmp/hsmbundle file to /usr/local/okv/hsm/:

cp /tmp/hsmbundle /usr/local/okv/hsm/

Change the ownership of the hsmbundle file to user oracle and group oinstall:

chown oracle:oinstall /usr/local/okv/hsm/hsmbundle

On each node, excluding the original HSM-enabled node, perform the following steps:

a. Navigate to the HSM page and click Apply Bundle.

b. In the Recovery Passphrase field, enter the recovery passphrase.

c. Click the Apply Bundle button.

Ensure that you repeat these steps on each applicable node to complete the bundle application process.

Apply the bundle immediately on all nodes before reverse-migrating the original HSM-enabled node.

Proceed to HSM-enable each of the remaining nodes in the cluster using the steps outlined in Integrate Oracle Key Vault with Luna HSM.

Verify that the HSM is enabled on every node in the cluster in Cluster Settings State.

After the HSM is enabled on all nodes and replication between nodes is verified, remove the hsmbundle file from all nodes.