Skip to main content

Migrate the Master Encryption Key to the HSM

This page is intended for clients who want to migrate their Oracle TDE MEK to an Securosys PrimusHSM or CloudHSM.

info

This document assumes you have already completed the Configuration steps and meet all Prerequisites.

Prerequisites​

Check PKCS#11 Library​

Verify that the Securosys Primus PKCS#11 module is installed and accessible:

ls -l /opt/oracle/extapi/64/hsm/primus/2.3.4/libprimusP11.so

Configure TDE to Support Both HSM and Software​

Change the TDE_CONFIGURATION parameter to cover the software keystore as well the HSM, we will use HSM as first keystore.

ALTER SYSTEM SET TDE_CONFIGURATION = 'KEYSTORE_CONFIGURATION=HSM|FILE' SCOPE=BOTH;

Migrate Master Key to HSM​

Now migrate the current master encryption key from software keystore to the HSM.

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
  IDENTIFIED BY "<HSMPassword>" 
  MIGRATE USING "<KeystorePassword>" 
  WITH BACKUP USING 'migrate_to_HSM';

Verify the key:

SET LINESIZE 160 PAGESIZE 200
ALTER SESSION SET nls_timestamp_tz_format="DD.MM.YYYY HH24:MI:SS";
COL key_id FOR A52
COL tag FOR A10
COL creation_time FOR A19
COL activation_time FOR A19
COL creator FOR A10
COL user FOR A10
COL key_use FOR A7
COL creator_dbname FOR A10
COL backed_up FOR A8
SELECT key_id, tag, creation_time, activation_time, creator, user, key_use, backed_up, creator_dbname FROM v$encryption_keys;

Create EXTERNAL STORE for HSM Password​

Determine admin directory and get the corresponding directory path as a SQL*Plus variable for later use:

COLUMN wallet_root NEW_VALUE wallet_root NOPRINT
SELECT value AS wallet_root FROM v$parameter WHERE name = 'wallet_root';

Create an EXTERNAL STORE for the HSM password:

ADMINISTER KEY MANAGEMENT ADD SECRET '<HSMPassword>' 
  FOR CLIENT 'HSM_PASSWORD' 
  TO LOCAL AUTO_LOGIN KEYSTORE '&wallet_root/tde_seps';

Restart the database to make sure the HSM keystore is now the primary wallet. As we do not have autologin configured the HSM based keystore has to be opened manually.

SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY EXTERNAL STORE;
ALTER DATABASE OPEN;

Check if the library has been successfully loaded by the Oracle process:

host pmap $(pgrep -f ora_gen0_.*) | grep -v " grep " | grep libprimusP11

This will output a list of Oracle processes that load the libprimusP11 library.

Check the current status of the Software Keystore:

SET LINESIZE 160 PAGESIZE 200
COL wrl_type FOR A10
COL wrl_parameter FOR A50
COL status FOR A20
COL wallet_type FOR A20
COL wallet_order FOR A20
SELECT wrl_type, wrl_parameter, status, wallet_type,wallet_order FROM v$encryption_wallet;

Check the status of Encryption Keys:

SET LINESIZE 160 PAGESIZE 200
ALTER SESSION SET nls_timestamp_tz_format="DD.MM.YYYY HH24:MI:SS";
COL key_id FOR A52
COL tag FOR A10
COL creation_time FOR A19
COL activation_time FOR A19
COL creator FOR A10
COL user FOR A10
COL key_use FOR A7
COL creator_dbname FOR A10
COL backed_up FOR A8

SELECT key_id, tag, creation_time, activation_time, creator, user, key_use, backed_up, creator_dbname FROM v$encryption_keys;

At this point, your MEK is now migrated to a Securosys HSM.

Migrate Master Key to Software Wallet​

On rare occasions, users may want to migrate their MEKs from HSM to Software Wallet. For example, when an HSM is being decommissioned, platform migrations, testing non-productive environments, etc.

warning

Securosys always recommends to store your keys on a PrimusHSM.

These exceptional activities should be done with caution and with the necessary backups taken place.

Temporarily Enable Dual Keystore Mode​

Switch the Keystore Configuration to be FILE|HSM, with FILE as primary keystore:

ALTER SYSTEM SET TDE_CONFIGURATION = 'KEYSTORE_CONFIGURATION=FILE|HSM' SCOPE=SPFILE;

Reverse Migrate the Master Key to Software Keystore​

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<KeystorePassword>" REVERSE MIGRATE USING "<HSMPassword>"
WITH BACKUP USING 'reverse_migrate_from_HSM';
info

This will copy the current master encryption key from the HSM to the local software keystore.

Switch to Software Keystore Only​

Allow only software wallet to access the Keystore:

ALTER SYSTEM SET TDE_CONFIGURATION = 'KEYSTORE_CONFIGURATION=FILE' SCOPE=SPFILE;

Restart the Database to apply the configuration change:

SHUTDOWN IMMEDIATE;
STARTUP;

And lastly, verify the Software Keystore:

SET LINESIZE 160 PAGESIZE 200
COL wrl_type FOR A10
COL wrl_parameter FOR A50
COL status FOR A20
COL wallet_type FOR A20
COL wallet_order FOR A20
SELECT wrl_type, wrl_parameter, status, wallet_type,wallet_order FROM v$encryption_wallet;

And the status of the Encryption Keys:

SET LINESIZE 160 PAGESIZE 200
ALTER SESSION SET nls_timestamp_tz_format="DD.MM.YYYY HH24:MI:SS";
COL key_id FOR A52
COL tag FOR A10
COL creation_time FOR A19
COL activation_time FOR A19
COL creator FOR A10
COL user FOR A10
COL key_use FOR A7
COL creator_dbname FOR A10
COL backed_up FOR A8

SELECT key_id, tag, creation_time, activation_time, creator, user, key_use, backed_up, creator_dbname FROM v$encryption_keys;

At this point, the MEK has been migrated from HSM to Software Keystore and can be used locally, without a dependency on the HSM.

Last updated on