Oracle Key Vault

1Set up Luna HSM

2Set up Oracle Key Vault

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

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

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

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

5Run 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

Note

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

Note

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.

1Ensure that you possess sudo privileges on the client workstation.

2Add 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.

1Confirm that you hold sudo privileges on the client workstation.

2Eliminate 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.

Note

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

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

Note

This integration has been certified on the RHEL platform.

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

3Extract 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

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

source ./setenv

Note

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

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

Note

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.

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

Note

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

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

gpasswd --add oracle hsmusers

3Reboot the Oracle Key Vault to apply the changes.

reboot

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

Note

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

5Navigate to the following directory:

cd /usr/local/okv/hsm/generic

Note

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

6Open 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"

Note

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

7Open 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"

8Open 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}

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

reboot

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

Note

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

11Navigate to System tab.

12Access 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.

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

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

15Open 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.

Note

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.

16Provide 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.

Note

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.

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

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

Note

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.

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

lunacm:> par con

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

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

3Create 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

4Create 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

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

/opt/pre-upgrade-luna.sh

Note

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.

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

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

Caution

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.

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

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

8Log 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.

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

/opt/post-upgrade-luna.sh

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

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

Note

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

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

2For 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.

3Click Manage Backup Destinations to view all configured backup destinations.

4Click Create.

5Enter 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.

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

Note

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

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

8Enter 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.

9Click 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.

10Verify the backup files on the backup destination.

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

2For 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.

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

Note

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

4Open 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.

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

Note

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.

6For 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.

7Click 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.

8Click Restore.

9Enter 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.

Note

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.

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

2HSM-enable the first node

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

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

Note

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.

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

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

3Generate 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).

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

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

6Enter 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.

7Click 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.

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

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

2Confirm 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).

3Log 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.

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

5Initiate node addition: Click on the Add option.

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

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

8Enter 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.

9Access 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.

10Configure 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.

11Certificate 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.

Note

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

12Convert 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.

13Certificate 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.

14HSM Credential and Finalization:

• Add the HSM Credential (partition password).

• Click Add Node.

• Confirm by clicking OK in the dialog box.

15Verification: 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.

1HSM-enable the first node

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

3Configure the remaining nodes

Note

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

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

2Click 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.

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

4In 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.

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

6Copy 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

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

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

ssh support@ip_address

2Switch to the root user on each node:

su root

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

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

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

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

5On 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.

Note

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

Note

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

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

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

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