Procedures

Steps:

Preparatory requirements
Create a Database Vault in the KeyControl Vault Server
Downloading Policy Agent
Create a VMSet in KeyControl Vault
Create Key Set
Link PKCS11 Library
Opening and closing a keystore or KeyControl
Migrating from software wallet to KeyControl (non-multitenant)
Migrating from software keystore to KeyControl (multitenant)
Create master keys directly in KeyControl for non-multitenant database
Create master keys directly in KeyControl for multitenant database
Rekeying or key rotation
Enabling and Disabling Database Connector

Preparatory requirements

Before installing the software, Entrust recommends that you familiarize yourself with:

The Oracle database TDE documentation and setup process.
The Entrust KeyControl Vault documentation.
Entrust recommends that you create a policy for managing SQL scripts that allow use of credentials for the Oracle database. These SQL scripts should only be available to authorized users.

This guide assumes that Oracle database software, and (at least) one Oracle database, is already installed on your system. With Oracle database software already installed, ensure that any required patches have been added.

To integrate an Oracle database with Entrust KeyControl Database Vault, the following steps are required:

Environment configuration.
Install the Entrust KeyControl Database Vault software.
Configure Oracle database software to use the Entrust KeyControl Database Vault.

Details of your installation and configuration will depend on:

Whether you are using a non-multitenant or multitenant database.
Whether you want to migrate encryption keys from an existing Oracle software keystore to Entrust KeyControl, or start directly withEntrust KeyControl.

The default host server user is oracle unless stated otherwise.

For more information on how to configure your Entrust environment, refer to the KeyControl Vault Installation Guide.

For more information on how to configure your Oracle environment, see the Oracle documentation.

Create a Database Vault in the KeyControl Vault Server

The KeyControl Vault appliance supports different type of vaults that can be used by all type of applications. This section describes how to create a Database Vault in the KeyControl Vault Server.

Please refer to Creating a Vault section of the admin guide for more details about it.

Log into the KeyControl Vault Server web user interface:
1. Use your browser to access the IP address of the server.
2. Sign in using the secroot credentials.
Select the user’s drop-down menu and select Vault Management.

This action will take you to the KeyControl Vault Management interface.
In the KeyControl Vault Management interface, select Create Vault.
KeyControl Vault supports the following types of vaults:
- Cloud Key Management - Vault for cloud keys such as BYOK and HYOK.
- KMIP - Vault for KMIP Objects.
- PASM - Vault for objects such as passwords, files, ssh keys, and so on.
- Database - Vault for database keys.
- Tokenization - Vault for tokenization policies.
- VM Encryption - Vault for encrypting VMs.
In the Create Vault page, create a Database Vault:
1. For Type, select Database.
2. For Name, enter the name of the vault
3. For Description, enter the description of the vault.
4. For Admin Name, enter the name of the administrator of the vault.
5. For Admin Email, enter a valid email for the administrator.
  
  A temporary password will be emailed to the administrator’s email address. This is the password that will be used to login for the first time to the Database Vault space in KeyControl.
Select Create Vault.
Select Close when the vault creation completes.

The newly-created vault is displayed in the Vault dashboard. For example:

View Vault’s Details

To view the details on the vault, select View Details when you hover over the vault.

vault details

Edit Vault

To edit the details of the vault, select Edit when you hover over the vault.

vault edit

Managing the Vault

After the Vault has been created, look for the email that was sent with the Vault’s URL and the login information for the Vault. For example:

vault email

Go to the URL and login with the credentials given. When you login for the first time, the system will ask the user to change the password.

Downloading Policy Agent

The nShield DataControl Policy Agent serves as a software module that facilitates encryption of virtual disks and individual files on Windows and Linux operating systems, enabling secure sharing of encrypted data among VMs. When a user attempts to access an encrypted disk, the Policy Agent ensures authorization by verifying the request with KeyControl Vault. Furthermore, the configuration of the Policy Agent includes the setup of the Oracle server to load the EKM provider library, reinforcing the encryption capabilities within the server environment.

Log into the newly created vault:
1. Select the WORKLOADS tab.
2. Select Actions > Download Policy Agent
A list of available downloads appears. For example:
Download the hcs-client-agent-10.1-1010001362.run file.
Return to the Oracle server as root user and install pkcs11-tool for testing:
```
yum install opensc
```
Check if Python is already installed:
```
python --version
```
If Python is already installed, it will display the version number. If not, you can install it using the package manager for your Linux distribution:
```
sudo dnf install python3
```
After installing Python, check that it is in your system path:
```
python --version
```
Navigate to the directory where you downloaded the hcs-client-agent-10.1-1010001362.run file.

Make the file executable:

chmod +x hcs-client-agent-10.1-1010001362.run

Run the installer:

./hcs-client-agent-10.1-1010001362.run

For example:

% ./hcs-client-agent-10.1-1010001362.run

Verifying archive integrity...  100%   All good.
Uncompressing hcs-client-agent-10.1-1010001362.run  100%
x86_64
No HyTrust Agent found on this system
HyTrust Agent will be installed in /opt/hcs
Specify location for installing HyTrust Agent (/opt/hcs):
Created symlink /etc/systemd/system/multi-user.target.wants/hcld.service → /usr/lib/systemd/system/hcld.service.
Platform is rhel

You can now install online encryption driver, the process is described in the Admin Guide
Please see the following section of Admin Guide for details
--- Administration Guide > Data Encryption > Linux Encryption Overview

Installation successful

Verify the installation:

% hcl status

For example:

% hcl status

Summary
--------------------------------------------------------------------------------
KeyControl: None
Status: Not registered
AES_NI: enabled
HTCRYPT: Not Installed

Registered Devices
--------------------------------------------------------------------------------
Disk Name          Cipher       Status                   Clear
--------------------------------------------------------------------------------

Available Devices
--------------------------------------------------------------------------------
Disk Name            Device Node                      Size (in MB)
--------------------------------------------------------------------------------

...

For more information, please refer to Entrust DataControl Policy Agent

Create a VMSet in KeyControl Vault

A VMSet in KeyControl Vault is a logical grouping of virtual machines (VMs) that allows for centralized management and control of encryption policies.

Login to the KeyControl Database Vault for Oracle TDE.
Select the WORKLOADS tab.
Select Actions > Create New Cloud VM Set.
In the Create Cloud VM Set page:
1. Enter a Name for the cloud VM set
2. For Group, select Cloud Admin Group
3. Enter a Description
4. Select No Boundary Controls Available
For example:
Select Create.
When a success message appears, click Close.
The newly-created VM Set is added to the list. For example:

Register the Oracle Server VM to VM Set

To register the Oracle Server VM to VM Set:

In the vault page, click on your user in the top corner and select About.
Copy the Vault ID. For example:

% hcl register -a -v <VAULT-ID> <KEYCONTROL-VAULT-IP>

Enter the number corresponding to the VM created earlier, then enter y to confirm the VM and continue. For example:

% hcl register -a -v <VAULT-ID> <KEYCONTROL-VAULT-IP>

Please provide the Vault login details
username: user@entrust.com
password: ********

Available Cloud VM Sets
--------------------------------------------------------------------------------
1 : OracleTDE
--------------------------------------------------------------------------------

Please select a Cloud VM Set by number to which this VM should be added:
!Error: Not a valid selection


Available Cloud VM Sets
--------------------------------------------------------------------------------
1 : OracleTDE
--------------------------------------------------------------------------------

Please select a Cloud VM Set by number to which this VM should be added: 1

The selected Cloud VM Set is -- OracleTDE
Do you want to continue (y/n)?y
Registered as otde-19c-kc10.1-redhat-8 with KeyControl node(s) **.***.***.***

Completing authentication for otde-19c-kc10.1-redhat-8 on KeyControl node(s) **.***.***.***

Authentication complete, machine ready to use
Getting KeyControl Mapping information

KeyControl Mappings are not available

Verify the registration:

% hcl status

For example:

% hcl status
Summary
--------------------------------------------------------------------------------
KeyControl: [IP]
KeyControl list: [IP]
Vault ID: [ID]
Status: Connected
Last heartbeat: Wed May 10 15:16:39 2023 (successful)
AES_NI: enabled
Certificate Expiration: May  9 19:16:15 2024 GMT
HTCRYPT: Not Installed

Registered Devices
--------------------------------------------------------------------------------
Disk Name          Cipher       Status                   Clear
--------------------------------------------------------------------------------

Available Devices
--------------------------------------------------------------------------------
Disk Name            Device Node                      Size (in MB)
--------------------------------------------------------------------------------

...

Enable TDE:

hcl tde enable

For example:

% hcl tde status
TDE is  not enabled on this VM

% hcl tde enable
Enabling tde will change permissions of some Files.
Do you want to proceed? (y/n) y

% hcl tde status
TDE is enabled on this VM

Create Key Set

A KeySet in KeyControl Vault serves as a container for managing encryption keys used in various cryptographic operations.

Login to the KeyControl Database Vault.
Select the CLOUD KEYS and then select the Key Sets tab.
Select Actions > Create Key Set. For example:

The Create Key Set dialog appears.
In the Details tab, create the Key Set:
1. Enter a Name.
2. Enter a Description.
3. For Admin Group, select Cloud Admin Group.
4. For Database Type, select Oracle Database Server.
For example:
Select Continue.
In the HSM tab, clear the Enable HSM check box. The KeySet can also be created with HSM enabled, providing administrators with the ability to safeguard the TDE master keys using an HSM. However, prior to creating the KeySet, the HSM must be properly configured within KeyControl.

For more information on HSM configuration with KeyControl, please refer to Hardware Security Modules with KeyControl Vault
Select Apply.

Click Close when a success message appears.
Verify that your KeySet is listed.

Create Database Connector

The Database Connector creates a connection between the KeySet and the registered VM, enabling secure communication. Access credentials are associated with the connector, providing authentication for data access. The connector also allows for controlled access, empowering the controller to manage privileges effectively.

Select the newly created KeySet > Select the Database tab > Select Create Connector Now
Create Database Connector:
1. Select the VM Name
2. Enter a Connector Name
3. Select an Expiration
4. Select Create
Select the newly created database connector > Actions > Generate Access Token
Select Generate Token and it will display the newly generated token.
Copy the access token (Identity and Secret). For example:

In your Oracle Server, create a config file /opt/oracle/entrust/orcl.conf using the copied Access Token (Identity and Secret) that will be used by the database administrators.

The orcl.conf file must be in a JSON format. For example:

{
  "identity": "oracle_connect_1",
  "secret": "TzIegAOfPLnHrD973w33+cWEJqV0PWOZJE9WYdRFoNQ/aCP2MamqolkM2lU2qgLRo9WR+9u2EcVA3w0Dh5tXsyP4QAiyo8Mbe2W3bBz2FxAL7Z/IE/9l5gDcuQQ+riJ+EkTWvnCqd660NvNWhWkXCXzqAYk7ObicE0IazEqSxEfF8/reKuJcSDd0/+gMdbJ2Uk0c4r2VI58S7dp0CMA5DL7CGLppbKwcONq0q0uNa5/AvQd9oYmXCGDzcfinZzAkNJ2yIaDIerLa+ME8gSPtyv4hh+7RtGM+uHnB2TD7MSz88l46nBBxK33u+eXyZBRbDis9K0supoWXoEhgoEV3P5HS9+Hz3KCnQA4PnydgcLqnUbNYZqAboShPSkEHFHQkV2hW5/9tEz3MMaiHCJHT7Tx9hXTsyQpQ6B8O+CqPSHE2Ba0NHTBkdUiu/dnuWJSNTNblvIsrT95lKKIgyCf0VWKH9HFRWmE9DwmZo85Tv0oeCCNbcFlljWTC/hFOGsiBTpcCoQy/KG0oGyy1y/o+ZtCR3O7sW7Hbr4gh0mkXP8ae+JSm2BV4eSACwAKlsYQlh1MqsRrUtJyZhpUpdc9qai7O9u0KwzrGaecN229zQVAHb4VUpiJm9NXnyram46P/SK6MpooPEcHFIVriPfkiPrxdILrKYu2W9bXI53FVtbM="
}

Set the following ownership and permissions on the /opt/oracle/entrust directory:
- Owner: oracle
- Group: oinstall
- Permissions: 775
mkdir /opt/oracle/entrust sudo chown oracle:oinstall /opt/oracle/entrust sudo chmod 775 /opt/oracle/entrust

The access credentials will be securely stored on the Oracle server, enabling the creation and utilization of the master key. By leveraging these credentials, you gain the ability to enable robust encryption on the database, making use of the master key for enhanced security.

For more information on creating a KeyControl Vault Key Set for TDE, please refer to KeyControl Vault Key Set for TDE

Link PKCS11 Library

You must now configure the Oracle PKCS#11 Library folder to use the nShield KeyControl PKCS#11 API.

Create a directory path for the nShield API library as the oracle user. Make ownership and permissions on the directory as:

Owner: oracle
Group: oinstall
Permissions: 775

#
# ORACLE_BASE is typically /opt/oracle
#
sudo chown -R oracle:oinstall $ORACLE_BASE
sudo chmod -R 775 $ORACLE_BASE
mkdir -p $ORACLE_BASE/extapi/64/hsm/entrust
chown oracle:oinstall $ORACLE_BASE/extapi/64/hsm/entrust
chmod 775 $ORACLE_BASE/extapi/64/hsm/entrust

Link the PKCS#11 Library into the directory as the oracle user:

ln -s /opt/hcs/lib/libpkcs11.so $ORACLE_BASE/extapi/64/hsm/entrust/libpkcs11.so

Testing the integration

When testing the integration, make sure you use the instructions that are appropriate to your installation. That is:

A non-multitenant database and software wallet.
A multitenant database and software keystore.

For this integration, it is necessary to update the PKCS#11 library for Oracle 19c and 21c Multitenant Database. Failure to do so may lead to the following issues:

Failing at migrating the software wallet to KeyControl.
Failing at opening KeyControl keystore for all containers.

For example:

ERROR at line 1:
ORA-28407: Hardware Security Module failed with PKCS#11 error
CKR_SESSION_HANDLE_INVALID(179)

ERROR at line 1:
ORA-03113: end-of-file on communication channel
Process ID: 148627
Session ID: 379 Serial number: 61809

For the most accurate and updated information regarding the PKCS11 library fix, nShield recommends referring to the KeyControl 10.1 Release Notes.

Opening and closing a keystore or KeyControl

Oracle has a control system that gates access to a software keystore or KeyControl:

If a keystore or wallet is open, then you can access its contents.
If a keystore or wallet is closed, then you cannot access its contents.

You can open or close a software keystore or wallet with the following SQL statements.

Non-multitenant

This section assumes database is open.

CONNECT TESTER@DB or CONNECT sysdba@DB

To open a wallet:

ALTER SYSTEM SET [ENCRYPTION] WALLET OPEN IDENTIFIED BY "<credential>";

To close a wallet, pre-11.2.0.1.0:

ALTER SYSTEM SET [ENCRYPTION] WALLET CLOSE;

To close a wallet, 11.2.0.1.0 or later:

ALTER SYSTEM SET [ENCRYPTION] WALLET CLOSE IDENTIFIED BY "<credential>";

In all of the above, the [ENCRYPTION] clause is optional.

Multitenant

This section assumes the respective CDB and PDB databases are open:

To open/close a keystore for the container (CDB) only:

CONNECT C##TESTER@CDB<n>

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>";
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "<credential>";

To open/close a keystore for the container (CDB) and all PDBs it holds:

CONNECT C##TESTER@CDB<n>

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>" CONTAINER=ALL;
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "<credential>" CONTAINER=ALL;

If you want to close all keystores, use the following SQL:

ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE CONTAINER=ALL;

To open/close a keystore for a single PDB, you must use same credential as used by the containing CDB.
CONNECT PDB<k>TESTER@CDB<n>PDB<k>
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>"; ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "<credential>";
During migration from Software Wallet to the KeyControl Keystore, you may experience issues closing the keystore. To resolve this, disable the auto-login keystore to close all keystores. See How To Disable Auto-Login Keystore for full details.
sudo -u oracle mv <path-to-keystorefolder>/<keystore-folder>/tde/cwallet.sso <path-to-keystorefolder>/<keystore-folder>/tde/cwallet.sso.backup

Migrating from software wallet to KeyControl (non-multitenant)

The following procedure applies when the target database is non-multitenant, and you are already using a software wallet with TDE encryption. If your target database is multitenant, see Migrating from software keystore to KeyControl (multitenant).

Entrust strongly recommends you back up your software wallet as an independent operation before attempting migration to KeyControl. Keep the backup folder in a safe place separated from the associated database files. Only users with authorization should be able to access the backup folder.

Repeat the following procedure for each database software wallet from which you want to migrate. Each independent database instance can use its own Entrust key protection method or credential if required.

Once an Entrust key protection method has been activated for a particular database instance, then you must continue to use that same credential for any further keys you want to protect for that instance.

Use the WALLET_ROOT and TDE_CONFIGURATION parameters. It is assumed the WALLET_ROOT parameter has already been set for Oracle keystore use.

In the following steps, use the orcl.conf file to utilize the access credentials for the KeyControl Database Vault.

Prepare for key migration by running the following SQL script:

CONNECT sysdba@DB

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

Migrate from the keystore to KeyControl:

CONNECT sysdba@DB

ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" MIGRATE USING <keystore-passphrase>;

The cloud key is created. For example:

Return to the Oracle Server in the SQL database and run the following command:

select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

For example:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         0 HSM                  OPEN

Migrating from software keystore to KeyControl (multitenant)

The following procedure applies when the target database is multitenant, and you are already using a software wallet with TDE encryption. If your target database is non-multitenant, see Migrating from software wallet to KeyControl (non-multitenant).

Repeat the following procedure for each software keystore from which you want to migrate. Each container database (CDB) can use its own Entrust key protection method (credential) if required. However, once a Entrust key protection method has been activated for a particular database instance (CDB), then you must continue to use that same credential for any further keys you want to protect for that instance.

Use the WALLET_ROOT and TDE_CONFIGURATION parameters.

In the following steps, use the orcl.conf file to utilize the access credentials for the KeyControl Database Vault.

Back up your software keystore before attempting key migration to KeyControl:

CONNECT sysdba@CDB<n>

ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE USING '<PreMigrationBackupString>' IDENTIFIED BY "<keystorepassphrase>";

Prepare for key migration by running the following SQL script:

CONNECT sysdba@CDB1ROOT

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

Migrate from the keystore to KeyControl:

CONNECT sysdba@CDB1ROOT

ALTER SESSION SET CONTAINER = CDB$ROOT;
SHOW con_name;

--Open all the PDBs.
ALTER PLUGGABLE DATABASE ALL OPEN;

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" MIGRATE USING <keystore-passphrase> WITH BACKUP;

For Oracle 21c Database, you must open PDB$SEED with read write permissions to successfully bounce the database after migrating from the keystore to KeyControl:

CONNECT sysdba@CDB1ROOT

ALTER SESSION SET CONTAINER = CDB$ROOT;
SHOW con_name;

--Open all the PDBs.
ALTER PLUGGABLE DATABASE ALL OPEN;

-- open PDB$SEED with read write perm show pdbs;
alter pluggable database pdb$seed close;
alter pluggable database pdb$seed open read write;
show pdbs;

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" MIGRATE USING <keystore-passphrase> WITH BACKUP;

For example:

Return to the Oracle Server in the SQL database and run the following command:

select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

For example:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         1 HSM                  OPEN
         2 HSM                  OPEN
         3 HSM                  OPEN
         4 HSM                  OPEN

Create master keys directly in KeyControl for non-multitenant database

The following procedure applies when the target database is non-multitenant, and there is no pre-existing software wallet. If your target database is multitenant, see Create master keys directly in KeyControl for multitenant database.

Repeat the following procedure for each database in which you want to create keys. Each database can use its own Entrust key protection method (credential) if required. However, once an Entrust key protection method has been activated for a particular database instance, then you must continue to use that same credential for any further keys you want to protect for that instance.

Use the WALLET_ROOT and TDE_CONFIGURATION parameters

Set up the WALLET_ROOT and TDE_CONFIGURATION parameters as follows. You must set up the WALLET_ROOT parameter even if you do not use a keystore.

CONNECT sysdba@DB
```
ALTER SYSTEM SET WALLET_ROOT = "/opt/oracle/entrust" scope=SPFILE;
```

Bounce the database after setting up the WALLET_ROOT parameter.

CONNECT sysdba@DB

ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=HSM" SCOPE=BOTH SID='*';

Bounce the database after setting up the TDE_CONFIGURATION parameter.

Create the encryption keys

In the following steps, use the orcl.conf file to utilize the access credentials for the KeyControl Database Vault to enable the creation and utilization of the master key.

Select the protection method (credential) that you require below, and run the SQL.

CONNECT TESTER@DB or CONNECT sysdba@DB

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf";

Run this command to see the status change:

select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

For example:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         0 HSM                  OPEN

The encryption key is created. For example:

After you created the master encryption keys in KeyControl as above, proceed to encrypt your database by using tablespace encryption, column encryption, or both, as usual.

Create master keys directly in KeyControl for multitenant database

The following procedure applies when the target database is multitenant, and there is no preexisting software keystore. If your target database is non-multitenant, see Create master keys directly in KeyControl for non-multitenant database.

Repeat the following procedure for each database in which you want to create keys. Each database instance can use its own Entrust key protection method (credential) if required. However, once an Entrust key protection method has been activated for a particular database instance (CDB), then you must continue to use that same credential for any further keys you want to protect for that instance.

You must create the container (CDB) master key first. After the CDB master key has been created you have a choice of creating master keys for all the PDBs it contains in one operation, or else for each PDB individually.

The PDB(s) must use the same protection credential as the CDB.

Use the WALLET_ROOT and TDE_CONFIGURATION parameters

To set and use the WALLET_ROOT and TDE_CONFIGURATION parameters:

Set up the WALLET_ROOT and TDE_CONFIGURATION parameters as follows. You must set up the WALLET_ROOT parameter even if you do not use a keystore.

CONNECT sysdba@CDB1ROOT
```
ALTER SYSTEM SET WALLET_ROOT = "/opt/oracle/entrust" scope=SPFILE;
```
Bounce the database after setting up the WALLET_ROOT parameter.

Run the following command:

ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=HSM" SCOPE=BOTH SID='*';

Bounce the database after setting up the TDE_CONFIGURATION parameter.

Create the CDB and then all PDB master keys in one operation

In the following steps, use the orcl.conf file to utilize the access credentials for the KeyControl Database Vault to enable the creation and utilization of the master key.

Run the following SQL:

CONNECT C##TESTER@CDB<n>

ALTER SESSION SET CONTAINER = CDB$ROOT;
SHOW con_name;

ALTER DATABASE OPEN;
ALTER PLUGGABLE DATABASE ALL OPEN READ WRITE;

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" CONTAINER = ALL;

Activate master keys for the CDB and all the PDBs in one operation:

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP CONTAINER = ALL;

Run this command to see the status change:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         1 HSM                  OPEN
         2 HSM                  OPEN
         3 HSM                  OPEN
         4 HSM                  OPEN

The master key is created. For example:

Encrypt your database using tablespace encryption, column encryption, or both.

Create the CDB master key and a single PDB master key

To create the CDB master key and a single PDB master key:

Create the CDB master key:

CONNECT C##TESTER@CDB<n>

Select the protection method you require below, and run the SQL:

--This will activate the credential if it isn't already
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf";
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP;

Repeat the following step to create a single PDB master key for any PDB you select.

CONNECT PDB<k>TESTER@CDB<n>PDB<k>

You must use the same protection method (credential) as the containing CDB.

Run the SQL:

--If the PDB is already open, you don't need to do this.
ALTER PLUGGABLE DATABASE <CDB<n>PDB<k>> OPEN READ WRITE;

--If the keystore is already open, you don't need to do this.
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf";

--Make the master key for the PDB you should be currently connected to.
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP;

Encrypt your database using tablespace encryption, column encryption, or both.

Rekeying or key rotation

After you have established your KeyControl Database Vault as the primary protector for your master encryption keys, for security reasons you may want to periodically replace the keys, or re-key. For your particular system, you can do this by following the instructions below.

The following subsections show how to perform a re-key in Oracle multitenant environments. After re-key, the new encryption keys should be immediately available and usable by the client that initiated the re-key.

Rekey for a non-multitenant database

The orcl.conf file is used to utilize the access credentials for the KeyControl Database Vault, enabling the creation and utilization of the master key.

The following instructions begin by assuming the KeyControl (wallet) is already open.

CONNECT TESTER@DB, or CONNECT sysdba@DB

--Assumes KeyControl is already open
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf";

Rekey for a multitenant database with CDB and all the PDBs in one operation

CONNECT TESTER@CDB<n>

The following instructions begin by assuming the required CDB has started, and required PDBs and KeyControl (keystore) to be already open.

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP CONTAINER = ALL;

Rekey for a multitenant database with CDB only

The following instructions begin by assuming the required CDB has started and KeyControl (keystore) to be already open.

CONNECT TESTER@CDB<n>

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP;

Rekey for a multitenant database with a single PDB only

The orcl.conf file is used to utilize the access credentials for the KeyControl Database Vault, enabling the creation and utilization of the master key.

The following instructions begin by assuming the required CDB has started, the required PDB and KeyControl (keystore) to be already open.

CONNECT PDB<k>TESTER@CDB<n>PDB<k>

--Make the master key for the PDB you should be currently connected to
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf" WITH BACKUP;

Enabling and Disabling Database Connector

To disable the Database Connector:

Log into the KeyControl Vault and navigate to CLOUDKEYS > Key Sets.
Select the desired Key Set and proceed to Database Connectors.
Choose the appropriate Database connector and access its settings.
Under Actions, locate the option to Disable Connector.
Select Disable.
When a confirmation message appears, select Close.
Confirm that the state is DISABLED.
Return to the Oracle Server in the SQL logged in as sysdba.
When you run the commands to verify the tables, you will notice that it shows the wallet is not open:
```
ERROR at line 1:
ORA-28365: wallet is not open
```

Confirm the wallet is closed with the following command:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         0 HSM                  CLOSED

To enable the Database Connector:

Log into the KeyControl Vault and navigate to CLOUDKEYS > Key Sets.
Select the desired Key Set and proceed to Database Connectors.
Choose the appropriate Database connector and access its settings.
Under Actions, locate the option to Enable Connector.

Open the keystore:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:/opt/oracle/entrust/orcl.conf";

Verify the opened keystore:

SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         0 HSM                  OPEN