Oracle Configuration

Configure the Oracle PKCS#11 library folder

This will configure Oracle to use the Entrust WSOP PKCS#11 API.

After creating the Oracle database, you will have to:

  1. Create the following directory path for the Entrust API library as the oracle user.

    Make ownership and permissions on the directory as:

    • owner=oracle

    • group=oinstall

    • permissions=775.

      % mkdir -p $ORACLE_BASE/extapi/64/hsm/nCipher/13.4.5
% chown oracle $ORACLE_BASE/extapi/64/hsm/nCipher/13.4.5
% chgrp oinstall $ORACLE_BASE/extapi/64/hsm/nCipher/13.4.5
% chmod 775 $ORACLE_BASE/extapi/64/hsm/nCipher/13.4.5

  2. Copy the WOP PKCS#11 library into the directory as the oracle user.

    % cp /opt/nfast/webservices/pkcs11/lib/libpkcs11webservices.so $ORACLE_BASE/extapi/64/hsm/nCipher/13.4.5
    The Entrust WSOP PKCS#11 API library is the only means by which the Oracle database system can communicate with the Entrust WSOP system. If this interface is not set up correctly, you will not be able to get these two systems to operate together.

  3. Configure Oracle keystore folder.

    You only need to provide a keystore-folder if encryption key migration is required. Do this as the oracle user. If a keystore-folder is required, then create a folder as follows:

    % mkdir -p $ORACLE_BASE/admin/FREE/keystore-folder

    Make sure ownership/permissions on the 'keystore-folder' allow the 'oracle' OS user to use it.

  4. Make sure that the environment variable ORACLE_SID is set to FREE.

    Edit the oracle user .bashrc file and change the variable. Log out and log back in as oracle.

    FREE is the database that automatically comes installed for you when you install Oracle 23ai. Set ORACLE_SID according to the database used in your environment.

Configure Oracle database software to use the Entrust WSOP.

Before proceeding, it is assumed that:

  • You have followed the set up and configuration instructions in this guide. That is:

    • The Oracle database software is installed with at least one database instance. This guide uses the FREE database already provided by Oracle 23ai.

    • The Entrust WSOP Server, Security World software and HSM are installed and configured.

    • THE Entrust WSOP Client software has been installed and configured in each Oracle Database Server.

    • Your protection method has been prepared. (softcard created)

    • OCS Cards have been created to provide FIPS authorization if a FIPS Level 3 world file is going to be used.

  • The target container database (CDB) is open, and all PDBs are open. The target container database in this guide is the FREE database that comes with Oracle 23ai installation.

You can use the following instructions to configure your Oracle database software to function using the Entrust WSOP server in one of the following scenarios:

  • Migration from keystore to WSOP: One or more database instances are already using TDE encryption, each instance with its own software keystore, and you want to continue using TDE encryption after migrating the TDE master keys from at least one keystore to the Entrust WSOP server.

  • Create keys directly in the WSOP server: One or more database instances are not using TDE encryption, and you want to start using TDE encryption for at least one database, using the Entrust WSOP server.

Before attempting key migration, see Key migration and legacy keys.

The SQL commands that will be used later in this document might:

  • Require more than one user with suitable database privileges to make the specific database connections, and run the SQL commands in the sequences as shown. Respect the connections shown in order to satisfactorily run SQL on your target. See Database connections. Your system administrator should have sufficient knowledge to create users and associated privileges according to your organization’s security policies.

  • Need to be run as a certain user. If you are instructed in this guide to make a connection as a particular user, continue with that connection until instructed otherwise.

  • Use <credential> to denote your chosen protection method. When a protection method has been invoked, you must continue with the same protection method unless you decide to alter it as described in About the HSM credential.

Oracle documentation uses the <credential-name>|<credential-passphrase> order. However, tests showed that the ordering <credential-passphrase>|<credential-name> works. In SQL, the credential used to open a keystore must match the credential used to create an encryption key.

Opening and closing a keystore or HSM

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

  • If a keystore or HSM is open, then you can access its contents.

  • If a keystore or HSM is closed, then you cannot access its contents.

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

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

  • To open/close keystore for the container (CDB) only.

    CONNECT C##TESTER@FREE

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

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

    CONNECT C##TESTER@FREE

    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 keystore for a single PDB, you must use same credential as used by the containing CDB.

    CONNECT PDB<k>TESTER@FREEPDB<k>

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

Issues closing keystores

During migration from Software Wallet to HSM 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

Active credentials

The first time you open a keystore or HSM using a credential for a particular database instance, it activates the credential you are referencing. You should then be able to create master encryption keys, or use (any) existing master encryption keys, that are protected by that credential. You cannot have more than one active credential at the same time for the same instance. You must close the keystore or HSM to deactivate the credential.

You can simultaneously use different credentials for different database instances on the same host server. For a container database only its CDB is a real instance. All PDBs within the same CDB must use the same active credential.

See About the HSM credential if you want to change a credential.

Migrating from software keystore to HSM

The following procedure applies when you are already using a software wallet with TDE encryption.

Repeat the following procedure for each software keystore from which you want to migrate.

See About the HSM credential if you want to change a credential.

Use the WALLET_ROOT and TDE_CONFIGURATION parameters.

  1. Back up your software keystore before attempting key migration to the HSM:

    CONNECT sysdba@FREE

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

  2. Prepare for key migration by running the following SQL script:

    CONNECT sysdba@FREEROOT

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

  3. Create an auto-login keystore where <credential> is the HSM credential you want to use:

    CONNECT sysdba@FREEROOT

    ALTER PLUGGABLE DATABASE ALL OPEN;
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY <keystore-passphrase> CONTAINER = ALL;
ADMINISTER KEY MANAGEMENT ADD SECRET "<credential>" FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY <keystore-passphrase> WITH BACKUP;
ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE <path-to-keystorefolder>/<keystore-folder>/tde' IDENTIFIED BY KeystorePassword1;

  4. Migrate from the keystore to HSM:

    CONNECT sysdba@FREEROOT

    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<credential>" MIGRATE USING <keystore-passphrase> WITH BACKUP;
    Use the Entrust WSOP cklist-dynamic utility to check that your encryption keys have been created in the WSOP server before proceeding. 
    % sudo -u oracle /opt/nfast/webservices/pkcs11/bin/cklist-dynamic -p SOFTCARD_PASSPHASE --library /opt/nfast/webservices/pkcs11/lib/libpkcs11webservices.so | grep CKA_LABEL

Create master keys directly in an HSM keystore

The following procedure applies when there is no preexisting software keystore.

Repeat the following procedure for each database in which you want to create keys.

See About the HSM credential if you want to change a credential.

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

  1. 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@FREEROOT

    ALTER SYSTEM SET WALLET_ROOT = '<path-to-keystore>' scope=SPFILE;

  2. Bounce the database after setting up the WALLET_ROOT parameter.

  3. Run the following command:

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

  4. Bounce the database after setting up the TDE_CONFIGURATION parameter.

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

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

    CONNECT C##TESTER@FREE

    ALTER PLUGGABLE DATABASE ALL OPEN;

--This will activate the credential
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>" CONTAINER=ALL;

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

    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP CONTAINER=ALL;
    Use the Entrust WSOP cklist-dynamic utility to check that your encryption keys have been created in the WSOP server before proceeding. 
    % sudo -u oracle /opt/nfast/webservices/pkcs11/bin/cklist-dynamic -p SOFTCARD_PASSPHASE --library /opt/nfast/webservices/pkcs11/lib/libpkcs11webservices.so | grep CKA_LABEL

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

Create the CDB master key and a single PDB master key

  1. Create the CDB master key:

    CONNECT C##TESTER@FREE

    1. 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 "<credential>";
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;

    2. Once you have created the CDB master key, you can repeat the following commands for creating a single PDB master key, for any PDB you select.

  2. Create a single PDB master key:

    CONNECT PDB<k>TESTER@FREEPDB<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 FREEPDB<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 "<credential>";

--Make the master key for the PDB you should be currently connected to.
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;
    Use the Entrust WSOP cklist-dynamic utility to check that your encryption keys have been created in the WSOP server before proceeding. 
    % sudo -u oracle /opt/nfast/webservices/pkcs11/bin/cklist-dynamic -p SOFTCARD_PASSPHASE --library /opt/nfast/webservices/pkcs11/lib/libpkcs11webservices.so | grep CKA_LABEL

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

Rekeying or key rotation

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

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

Rekey when sharing keys between clients

Reconnect all users/applications on the client that are using the database encryption facilities.

Test your rekey arrangements in a safe environment before committing to a production environment. Transactions restricted to unencrypted data will not be affected by rekey operations.

Rekey with CDB and all the PDBs in one operation

CONNECT TESTER@FREE

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

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP CONTAINER=ALL;

Rekey with CDB only

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

CONNECT TESTER@FREE

ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;

Rekey for a single PDB only

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

CONNECT PDB<k>TESTER@FREEPDB<k>

--Make the master key for the PDB you should be currently connected to
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;