Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

Oracle Transparent Data Encryption (TDE)

Integrating TDE with CipherTrust Manager on Oracle 19c

search

Integrating TDE with CipherTrust Manager on Oracle 19c

This section outlines the following steps to integrate TDE with the CipherTrust Manager on Oracle 19c:

Configuring Keystore Location

After configuring SafeNet ProtectApp PKCS#11 library with Oracle TDE, you need to configure the keystore location.

In the pfile or spfile, set the software wallet location in the WALLET_ROOT parameter and wallet type in the TDE_CONFIGURATION parameter.

Configuring HSM Wallet on Fresh Setup

  1. Create wallet directory for CDB-Root and all PDBs using the following commands:

    1
    2
    mkdir -p <software_wallet_location>
    chown -R oracle:oinstall <software_wallet_location>
    

    After executing the above command, provide appropriate permission to <software_wallet_location>.

  2. Set WALLET_ROOT parameter in the spfile.

    1
    2
    sqlplus / as sysdba
    ALTER SYSTEM SET WALLET_ROOT="<software_wallet_location>" scope=spfile;
    

    Restart the database.

    1
    2
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  3. Set TDE_CONFIGURATION parameter.

    1
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM" scope=spfile;
    
  4. Restart the database and grant the ADMINISTER KEY MANAGEMENT or SYSKM privilege to the desired user (<oracle_database_user>).

    1
    2
    3
    4
    5
    sqlplus / as sysdba
    SHUTDOWN IMMEDIATE;
    STARTUP;
    GRANT ADMINISTER KEY MANAGEMENT TO <oracle_database_user>;
    COMMIT;
    
  5. Check the existing wallets in the Oracle database. Initially, there will be no wallet. To verify this, execute the following command:

    1
    2
    3
    COLUMN WRL_PARAMETER FORMAT A50;
    SET LINES 200;
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    

    Output:

    WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
    HSM UNKNOWN CLOSED

    In following sample command, <cm_user:cm_user_password> represents the NAE user name and its password. NAE user name and password are case-sensitive. They must appear in double-quotes (" ") separated by a colon (:).
    NAE user specified in here is the owner of the encryption key created and stored on the CipherTrust Manager.
    The CipherTrust Manager GUI displays the generated master encryption key.

  6. Connect to the database as <oracle_database_user> and open the hardware keystore.

    1
    2
    connect <oracle_database_user>/<oracle_database_user_password>;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<cm_user:cm_user_password>";
    
  7. Set the hardware keystore TDE master encryption key.

    1
    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<cm_user:cm_user_password>";
    
  8. Check the wallet status by executing the following query:

    1
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    

    Output:

    WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
    HSM HSM OPEN

For Column and Tablespace encryption, refer Tasks.

Configuring Auto-login Wallet

After configuring Manual HSM wallet, you can enable auto-login. Auto-login prevents the need to open the wallet each time you restart the database. To enable auto-login, follow the steps below:

  1. Create the directory for every database and permit the oracle user to access this directory.

    1
    2
    mkdir -p <software_wallet_location>
    chown -R oracle:oinstall <software_wallet_location>
    

    After executing the above command, provide appropriate permission to <software_wallet_location>.

  2. Start new sql session and reset WALLET_ROOT parameter in spfile.

    1
    2
    sqlplus / as sysdba
    ALTER SYSTEM SET WALLET_ROOT="<software_wallet_location>" scope=spfile;
    

    Restart the database.

    1
    2
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  3. Reset TDE_CONFIGURATION parameter.

    1
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" scope=spfile;
    

    In Oracle 19c, keystore is created by default in the location set in WALLET_ROOT environment variable in the pfile or spfile file.

    Restart the database.

    1
    2
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  4. Create the software keystore at the location provided in the spfile file.

    1
    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  5. Open the software keystore.

    1
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<software_keystore_password>";
    
  6. Add the secret to the software keystore. This secret is the hardware security module's password and the client is HSM_PASSWORD. HSM_PASSWORD is an oracle defined client name that represents the HSM password as a secret in the software keystore.

    1
    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_passwordd>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" WITH BACKUP;
    
  7. Enable auto-login.

    1
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  8. Reset TDE_CONFIGURATION parameter.

    1
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    

    Restart the database.

    1
    2
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  9. Check the wallet status.

    1
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    

    Output:

    WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
    FILE AUTOLOGIN OPEN_NO_MASTER_KEY
    HSM HSM OPEN
  10. Access the data from column encrypted table or tablespace encrypted tables.

    1
    2
    3
    connect <oracle_database_user>/<oracle_database_user_password>;
    SELECT * FROM EMPLOYEES;
    SELECT * FROM CUSTOMERS;
    

Configuring Manual HSM Wallet with PDB in United Mode

Whenever you restart any of the databases, you must run alter pluggable command as shown below:
ALTER PLUGGABLE DATABASE <pdb_name>/<ALL> OPEN READ WRITE;
• Do not configure HSM auto-login for CBD until you generate the master key for PDB (All PDBs in case multiple PDBs are using TDE). After generating the master key for all PDBs, you can configure the CDB for auto-login and it will work for all PDBs as well.
• To plug a PDB from one CDB to another, simply unplug the PDB from one Container and plug into another Container Database and open the wallet in PDB. It would start working.

To configure an HSM wallet with a PDB in United mode:

  1. Edit the tnsnames.ora file to add a new service for the newly created PDB. By default, the tnsnames.ora file is located at $ORACLE_HOME/network/admin.

    For example:

    1
    2
    3
    4
    5
    6
    7
    8
    PDB2 =
    (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = localhost.localdomain)(PORT = 1521))
    (CONNECT_DATA =
    (SERVER = DEDICATED)
    (SERVICE_NAME = pdb2)
    )
    )
    
  2. Restart the listener service.

    1
    2
    lsnrctl stop
    lsnrctl start
    
  3. Start the sqlplus session and open the pluggable database in read-write mode.

    1
    2
    3
    sqlplus / as sysdba
    ALTER PLUGGABLE DATABASE <pdb_name>/<ALL> OPEN READ WRITE;
    ALTER SESSION SET CONTAINER=<pdb_name>;
    
  4. Grant the administrator privilege to pdbuser.

    1
    2
    3
    4
    5
    6
    7
    8
    GRANT ADMINISTER KEY MANAGEMENT TO <pdbuser>;
    GRANT CREATE SESSION TO <pdbuser>;
    GRANT CONNECT TO <pdbuser>;
    GRANT DBA TO <pdbuser>;
    GRANT CREATE ANY TABLE TO <pdbuser>;
    GRANT UNLIMITED TABLESPACE TO <pdbuser>;
    ALTER USER <pdbuser> PROFILE DEFAULT;
    COMMIT;
    
  5. Connect to the pluggable database as pdbuser.

    1
    Connect <pdbuser>/<pdb_password>@Pluggable_Database_Service_name;
    
  6. Reset TDE_CONFIGURATION parameter and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  7. Connect to the container database (CDB) first.

    1
    connect <oracle_database_user>/<oracle_database_user's_password>;
    
  8. Open the HSM wallet in CDB.

    1
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<cm_user:cm_user_password>";
    
  9. Set the HSM master encryption key in CDB.

    1
    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<cm_user:cm_user_password>";
    
  10. Connect to PDB and open the wallet.

    1
    2
    3
    ALTER SESSION SET CONTAINER=<pdb_name>;
    Connect <pdbuser>/<pdb_password>@Pluggable_Database_Service_name;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<cm_user:cm_user_password>";
    
  11. Set the HSM master encryption key in PDB.

    1
    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<cm_user:cm_user_password>";
    
  12. Check the mode of pluggable database.

    1
    SELECT KEYSTORE_MODE FROM V$ENCRYPTION_WALLET;
    

For Column and Tablespace encryption, refer Tasks.

Configuring Auto-login HSM Wallet with PDB‌

To enable auto-login with PDB, you need to enable auto-login in the container database only. Once you enable auto-login in CDB, it would automatically work for PDB. To configure auto-login in CDB, follow the below steps:

  1. Set WALLET_ROOT Parameter in the spfile and restart the database.

    1
    2
    3
    4
    sqlplus / as sysdba
    ALTER SYSTEM SET WALLET_ROOT="<software_wallet_location>" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  2. Reset TDE_CONFIGURATION parameter in the spfile and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  3. Create a keystore.

    1
    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  4. Open the software keystore.

    1
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<software_keystore_password>";
    
  5. Add a secret to the software keystore. This secret is the hardware security module's password and the client is HSM_PASSWORD. HSM_PASSWORD is an Oracle defined client name that represents the HSM password as a secret in the software keystore.

    1
    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_passwordd>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" WITH BACKUP;
    
  6. Enable auto-login.

    1
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  7. Reset TDE_CONFIGURATION parameter and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  8. Alter the pluggable database.

    1
    ALTER PLUGGABLE DATABASE <pdb_name>/<ALL> OPEN READ WRITE;
    
  9. Connect to the pluggable database.

    1
    2
    ALTER SESSION SET CONTAINER=<pdb_name>;
    CONNECT <pdb_user>/<pdb_user_password>@<pdb_name>;
    
  10. Check the wallet status and access the data from the encrypted tablespace and tables.

    1
    2
    3
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    SELECT * FROM EMPLOYEES;
    SELECT * FROM CUSTOMERS;
    

Migrating from Software Wallet to HSM Wallet

This section covers the following topics:

Migrating Manual Software Wallet to HSM Wallet‌‌

You can migrate the already configured software-based wallet to hardware-based wallet. If you have a software wallet configured already, wallet information will look like below:

1
2
sqlplus / as sysdba
SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;

Output:

WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
FILE <software_wallet_location> PASSWORD OPEN

To migrate a software wallet to an HSM wallet:

  1. Set the software-based wallet's password as the HSM wallet's password.

    1
    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY "<software_keystore_password>" SET "<cm_user:cm_user_password>" WITH BACKUP;
    
  2. Set TDE_CONFIGURATION parameter.

    1
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    
  3. Restart the database.

    1
    2
    SHUTDOWN IMMEDIATE;
    STARTUP;
    

    It is recommended to restart the database whenever you make any change in the spfile file.

  4. Run the command to migrate the key from the software wallet to the HSM wallet.

    1
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<cm_user:cm_user_password>" MIGRATE USING "<cm_user:cm_user_password>" with backup using 'migration_backup';
    

Migrating Manual Software Wallet to Auto-login HSM Wallet‌

You can migrate the already configured manual software-based wallet to auto-login hardware-based wallet. If you have a software wallet configured already, wallet information will look like below:

  1. Check the wallet status:

    1
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    

    Output:

    WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
    FILE <software_wallet_location> PASSWORD OPEN
  2. Add the secret to the software keystore. This secret is the hardware security module's password and the client is HSM_PASSWORD.

    HSM_PASSWORD is an oracle defined client name that represents the HSM password as a secret in the software keystore.

    You must include the <cm_user:cm_user_password> and HSM_PASSWORD in single quotes. It will not work if you do not do this.

    1
    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_password>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" with backup;
    
  3. Create a new auto-login keystore using the password of the Oracle software wallet.

    1
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  4. Restart the database and check the wallet status.

    1
    2
    3
    SHUTDOWN IMMEDIATE;
    STARTUP;
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    
  5. Reset TDE_CONFIGURATION parameter. Restart the database and check the wallet status.

    1
    2
    3
    4
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    
  6. Migrate the manual software wallet to auto-login HSM wallet.

    1
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<cm_user:cm_user_password>" FORCE KEYSTORE MIGRATE USING "<software_keystore_password>";
    
  7. Access the data from the encrypted tablespace and tables.

    1
    2
    3
    connect <oracle_database_user>/<oracle_database_user_password>;
    SELECT * FROM EMPLOYEES;
    SELECT * FROM CUSTOMERS;
    

Migrating Auto-login Software Wallet to Auto-login HSM Wallet‌

You can directly migrate a software-based auto-login enabled wallet to an auto-login enabled HSM wallet. If you have a software wallet configured already, the content of the spfile file and wallet information will have the following structure:

1
WALLET_ROOT=<software_wallet_location>

Output:

WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
FILE <software_wallet_location> AUTOLOGIN OPEN
  1. Rename or move the cwallet.sso file from the location specified above to any other location.

  2. Restart the database and open the software keystore.

    1
    2
    3
    SHUTDOWN IMMEDIATE;
    STARTUP;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<software_keystore_password>";
    
  3. Add the secret to the software keystore. This secret is the hardware security module's password and the client is HSM_PASSWORD.

    HSM_PASSWORD is an oracle defined client name that represents the HSM password as a secret in the software keystore.

    You must include the <cm_user:cm_user_password> and HSM_PASSWORD in single quotes. It will not work if you do not do this.

    1
    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_password>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" with backup;
    
  4. Create a new auto-login keystore using the password of the Oracle software wallet.

    1
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "<software_keystore_password>";
    
  5. Restart the database and check the wallet status.

    1
    2
    3
    SHUTDOWN IMMEDIATE;
    STARTUP;
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    
  6. Reset TDE_CONFIGURATION parameter and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  7. Migrate the auto-login software wallet to auto-login HSM wallet.

    1
    2
    connect <oracle_database_user>/<oracle_database_user_password>;
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<cm_user:cm_user_password>" FORCE KEYSTORE MIGRATE USING "<software_keystore_password>";
    
  8. Access the data from the encrypted tablespace and tables.

    1
    2
    SELECT * FROM EMPLOYEES;
    SELECT * FROM CUSTOMERS;
    

Migrating Software Wallet to HSM Wallet in PDB‌

If you are using PDB with software wallet, you can migrate to a hardware-based HSM wallet. Your spfile file and wallet status for both CDB and PDB will have the following structure:

CDB:

1
SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_ WALLET;

Output:

WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
FILE <software_wallet_location> PASSWORD OPEN

PDB:

1
SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_ WALLET;

Output:

WRL_TYPE WRL_PARAMETER WALLET_TYPE STATUS
FILE PASSWORD OPEN
  1. Perform migration to HSM.

    Change the wallet password to same as the HSM password.

    1
    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY "<software_keystore_password> SET "<cm_user:cm_user_password>" WITH BACKUP [USING 'backup_identifier'];
    
  2. Reset TDE_CONFIGURATION parameter and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  3. Set the encryption key.

    1
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<cm_user:cm_user_password>" MIGRATE USING <software_keystore_password> [WITH BACKUP [USING 'backup_identifier']];
    
  4. Check the wallet status.

    1
    SELECT WRL_TYPE, WRL_PARAMETER, WALLET_TYPE, STATUS FROM V$ENCRYPTION_WALLET;
    
  5. Restart the database, login with CDB and open the wallet.

    After restarting any of the databases, you must run alter pluggable command as shown below:
    ALTER PLUGGABLE DATABASE <pdb_name>/<ALL> OPEN READ WRITE;

  6. Log on to the pluggable database and open the wallet. HSM wallet will open and retrieve the data from the encrypted tables.

Migrating Back from HSM Wallet to Software Wallet

If you want to switch from a hardware keystore to a software keystore then you can use reverse migration of the keystore.

It is recommended to keep the HSM. Earlier backup files may rely on TDE master encryption keys present in the HSM.

  1. Reset TDE_CONFIGURATION parameter and restart the database.

    1
    2
    3
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE|HSM" scope=spfile;
    SHUTDOWN IMMEDIATE;
    STARTUP;
    
  2. Log on to the database instance as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

    1
    2
    3
    4
    sqlplus / as sysdba
    GRANT ADMINISTER KEY MANAGEMENT to system;
    commit;
    Connect <oracle_database_user>/<oracle_database_user_password>;
    
  3. Run Reverse Migration command.

    1
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<cm_user:cm_user_password>" reverse migrate using "<cm_user:cm_user_password>" with backup;
    

After you complete the migration, you do not need to restart the database or manually re-open the software keystore.

The migration process automatically reloads the keystore keys in the memory. The hardware keystore may still be required after reverse migration because the old keys are likely to be used for encrypted backups or by tools such as Oracle Data Pump and Oracle Recovery Manager. You should cache the hardware keystore credentials in the keystore so that the HSM can be opened with the software keystore.