Procedures

Preparatory requirements

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

  • The Oracle database TDE documentation and setup process.

  • The Entrust documentation.

Entrust also recommends that you have an agreed organizational Certificate Practice Statement and a Security Policy or Procedure in place covering administration of the HSM. In particular, these documents should cover the following aspects of HSM administration:

  • Whether the Security World must comply with FIPS 140 Level 3 or Common Criteria restrictions.

    • If you want to use a FIPS 140 Level 3 Security World, you must create an OCS card set for FIPS authorization. This is true even if you want to use module or Softcard protection.

    • If you are running multiple database instances on the same host, the same FIPS-authorizing OCS card set can be used for all database instances.

    • If you want to use OCS protection, the OCS card set used for key protection can also be used for FIPS authorization.

  • The number and quorum of Administrator Cards in the Administrator Card Set (ACS), and a policy for managing those cards.

  • Which of the following Entrust encryption key protection methods you want to use:

    • Module protection

    • Softcard protection

    • Operator Card Set (OCS) protection.

      If OCS cards are to be used, decide on the number of Operator Cards in the OCS card set. K/N functionality is not currently supported, so you must create 1/N OCS card sets. The number of OCS cards in a card set must be at least equal to the number of HSMs in your configuration, plus extras in case of card loss or failure.

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

  • A policy for managing the passphrases for your:

    • ACS

    • Module protection

    • Softcard protection

    • OCS protection

      For information on passphrases, see About the HSM credential.

  • A policy for managing the physical security of the smartcards used for the ACS and OCS, and their deployment to authorized users.

As part of your preparation, Entrust also recommends that you read Security Worlds key protection and failure recovery.

This guide assumes that the Oracle database software, and at least one Oracle database, are already installed on your system. Ensure that any required patches have been applied.

To integrate an Oracle database with a Entrust HSM, perform the following steps:

  1. Configure the environment.

  2. Install the Entrust HSM and Security World software.

  3. Configure the Oracle database software to use the Entrust HSM.

The details of your installation and configuration depend on whether you want to migrate encryption keys from an existing Oracle software keystore to an Entrust HSM or start directly with an Entrust HSM.

The default host server user is oracle unless stated otherwise.

For more information on how to configure your Entrust environment, see the User Guide for your HSM. For more information on how to configure your Oracle environment, see the Oracle documentation.

For more detail or suggestions on setting up your system, see the following appendixes:

Basic setup

  1. Install the Entrust Security World software on each client in accordance with its accompanying documentation. If you are using nShield network-attached HSMs with a separate RFS, the Entrust Security World software must also be installed on the RFS.

  2. Create or edit the cknfastrc file located in the NFAST_HOME directory for each client and, depending on how you want to protect the master encryption keys, set the following PKCS #11 environment variables:

    • For OCS or Softcard key protection and for HSM load sharing:

      CKNFAST_LOADSHARING=1
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all

    • For module key protection:

      CKNFAST_FAKE_ACCELERATOR_LOGIN=1
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all

      For more information, see the description of the PKCS #11 library environment variables in the PKCS #11 Reference Guide for nShield Security World.

  3. If you are using nShield network-attached HSMs, configure them to operate with your selected RFS and clients as described in your HSM documentation. Typically the clients are the host servers on which your Oracle database is running.

  4. Configure the Oracle PKCS #11 library folder to use the Entrust PKCS #11 API.

    After creating the Oracle database:

    1. Create the following directory path for the Entrust API library as the oracle user. Set ownership and permissions on the directory to owner=oracle; group=oinstall; permissions=775:

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

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

      cp /opt/nfast/toolkits/pkcs11/libcknfast.so $ORACLE_BASE/extapi/64/hsm/nCipher/13.6.16
      The Entrust PKCS #11 API library is the only means by which the Oracle database system can communicate with the Entrust system. If this interface is not set up correctly, the two systems cannot operate together.

  5. Add the oracle user to the nfast group:

    sudo usermod -a -G nfast oracle

Security World creation

  1. Create or load the Security World using a client or an nShield network-attached HSM. If you are using RA for the ACS cards, you must do so through a registered client. Ensure the Security World data is copied to the NFAST_KMDATA/local folder on all clients and on the RFS, and that it is loaded onto each nShield network-attached HSM used in the configuration.

  2. Check the Security World on the various components as follows:

    • Client: Use the Entrust nfkminfo utility to check the Security World and configuration on each client. In each case, the Security World must be shown as Initialized and Usable.

    • RFS: Use the Entrust nfkminfo utility to check the Security World and configuration. The Security World must be shown as Initialized.

    • nShield network-attached HSM:

      • Front panel: MENU > Security World mgmt. > Display World Info.

        The Security World must be shown as Initialized and Usable.

Prepare protection method

  1. If your Security World does not already contain the required protection method, proceed as follows:

    • If you want to use module protection, no action is required at this point. You will complete the required module-protection steps later in this integration process.

    • If you want to use Softcard protection, create the required number of Softcards, each with its own passphrase.

    • If you want to use 1/N OCS card set protection, create the required number of card sets now, using the same passphrase for each card within the same card set. See About the HSM credential.

  2. If you are using module or Softcard protection in a FIPS 140 Level 3 environment, you also need an OCS card set (1/N) to provide FIPS authorization. If a suitable OCS card set is not already available in the Security World, create one for this purpose.

Configuring Oracle database software to use the Entrust HSM

This section assumes that:

  • You have followed the setup and configuration instructions in this guide, including:

    • The Oracle database software is installed with at least one database instance.

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

    • Your protection method has been prepared.

  • The target container database (CDB) is open, and all PDBs are open.

You can use the following instructions to configure your Oracle database software to operate with the Entrust HSM and Security World software, in one of the following scenarios:

  • Migration from keystore to HSM: One or more database instances are already using TDE encryption, each 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 HSM.

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

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

The SQL commands used later in this document might:

  • Require more than one user with suitable database privileges to make specific database connections and run the SQL commands in the sequence shown. Follow the connection sequence shown to run the SQL successfully on your target system. See Database connections. Your system administrator should have sufficient knowledge to create users and assign privileges according to your organization’s security policies.

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

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

When using a Softcard or OCS card, the <credential> is a string containing the passphrase and card name of the card being used, in the form <credential-passphrase>|<credential-name>.

In SQL, the credential used to open a keystore must match the credential used to create an encryption key.

Whenever you have finished migrating or creating encryption keys in an HSM, Entrust recommends that you back up your Security World data. See the User Guide for your HSM.

Use the instructions appropriate to whether you are using:

  • A non-multitenant database and software wallet.

  • A multitenant database and software keystore.

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, you can access its contents.

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

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

Non-multitenant

This section assumes the database is open.

  • To open or close the wallet:

    CONNECT TESTER@DB or CONNECT sysdba@DB

    --To open the wallet
ALTER SYSTEM SET [ENCRYPTION] WALLET OPEN IDENTIFIED BY "<credential>";

--To close the wallet, pre-11.2.0.1.0
ALTER SYSTEM SET [ENCRYPTION] WALLET CLOSE;

--To close the wallet, 11.2.0.1.0 onward
ALTER SYSTEM SET [ENCRYPTION] WALLET CLOSE IDENTIFIED BY "<credential>";

    The [ENCRYPTION] clause is optional.

Multitenant

This section assumes that the respective CDB and PDB databases are open.

  • To open or close the 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 or close the keystore for the container (CDB) and all the 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;

    To close all keystores, use:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE CONTAINER=ALL;

  • To open or close the keystore for a single PDB, you must use the same credential as the containing CDB:

    CONNECT CDB<n>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>";

Issues closing keystores

During migration from a software wallet to an HSM keystore, you might experience issues closing the keystore. To resolve this, disable the auto-login keystore so that all keystores can be closed:

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, that credential is activated. You can then create master encryption keys, or use any existing master encryption keys, 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 use different credentials simultaneously for different database instances on the same host server. For a container database, only the 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 wallet to HSM (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 HSM (multitenant).

Entrust strongly recommends that you back up your software wallet as a separate operation before attempting migration to the HSM. Keep the backup folder in a safe place, separated from the associated database files. Only authorized users should be able to access the backup folder.

Repeat the following procedure for each database software wallet you want to migrate. Each 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, you must continue to use that same credential for any further keys you want to protect for that instance.

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

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

  1. Prepare for key migration by running the following SQL:

    CONNECT sysdba@DB

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

  2. Migrate from the keystore to the HSM:

    CONNECT sysdba@DB

    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<credential>" MIGRATE USING <keystore-passphrase> WITH BACKUP;

Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding.

Migrating from software keystore to HSM (multitenant)

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

Repeat the following procedure for each software keystore you want to migrate. Each container database (CDB) 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), you must continue to use that same credential for any further keys you want to protect for that instance.

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@CDB<n>

    ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE USING '<PreMigrationBackupString>' IDENTIFIED BY "<keystore-passphrase>";

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

    CONNECT sysdba@CDB1$ROOT

    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@CDB1$ROOT

    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 the HSM:

    CONNECT sysdba@CDB1$ROOT

    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<credential>" MIGRATE USING <keystore-passphrase> WITH BACKUP;

Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding.

Create master keys directly in an HSM for a 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 an HSM for a 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, you must continue to use that same credential for any further keys you want to protect for that instance.

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

Use the WALLET_ROOT and TDE_CONFIGURATION parameters

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

    CONNECT sysdba@DB

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

  2. Bounce the database after setting the WALLET_ROOT parameter.

    CONNECT sysdba@DB

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

  3. Bounce the database after setting the TDE_CONFIGURATION parameter.

Create the encryption keys

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

    CONNECT TESTER@DB or CONNECT sysdba@DB

    ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "<credential>";

Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding.

After you have created the master encryption keys in the HSM, proceed to encrypt your database using tablespace encryption, column encryption, or both.

Create master keys directly in an HSM for a multitenant database

The following procedure applies when the target database is multitenant and there is no pre-existing software keystore. If your target database is non-multitenant, see Create master keys directly in an HSM for a 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), you must continue to use that same credential for any further keys you want to protect for that instance.

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

You must create the container (CDB) master key first. Once the CDB master key has been created, you can choose to create master keys for all the PDBs it contains in a single operation, or for each PDB individually.

The PDBs 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 the WALLET_ROOT parameter even if you do not use a keystore.

    CONNECT sysdba@CDB1$ROOT

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

  2. Bounce the database after setting 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 the TDE_CONFIGURATION parameter.

Create the CDB and all PDB master keys in a single operation

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

    CONNECT C##TESTER@CDB<n>

    ALTER PLUGGABLE DATABASE ALL OPEN;

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

  2. Activate the master keys for the CDB and all its PDBs in a single operation:

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

Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding.

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@CDB<n>

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

      --This activates the credential if it isn't already active
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 to create a single PDB master key for any PDB you select.

  2. Create a single PDB master key:

    CONNECT CDB<n>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 "<credential>";

--Create the master key for the PDB you are currently connected to.
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;

Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding.

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, you may want to periodically replace the keys (rekey) for security reasons. You can do so by following the instructions below.

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

Rekey when sharing keys between clients

When encryption keys are shared or distributed between clients, either a common shared Security World folder or local client copies of the Security World folder are used. In this case, you must factor in:

  • Encryption key distribution and synchronization with the associated encrypted data in the Oracle database.

  • Recognition of new encryption keys by the Entrust hardserver instance on each client.

For the new keys to be recognized by a client hardserver instance that did not initiate the rekey, first make sure that the new keys are available in the Security World folder it is using. Once the new keys are available, you can make the client hardserver instance recognize and use them in either of the following ways:

  1. In the client cknfastrc file, set the following environment variable:

    CKNFAST_ASSUME_SINGLE_PROCESS=0

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

These actions cause the available keys to be scanned by the client’s hardserver instance, after which any new keys are recognized and made usable. See Latency issues to understand the full consequences of these options.

It is your system administrator’s responsibility to ensure that distribution and recognition of shared (new) encryption keys is performed smoothly. In the unlikely event that synchronization problems cannot be resolved while the system is in continual operation, it may be necessary to temporarily halt encrypted database operations on all clients other than the one that initiated the rekey. Once the rekey has been performed and the correct keys are available and recognized by all clients, the system can be restored to normal operation.

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

Before rekeying, inspect the contents of your Security World local folder, and note the date and time at which you perform the rekey. After rekeying, verify that new key files have been created in your Security World local folder, and check that the date/time stamp of the new key files in the folder matches the date and time at which you performed the rekey.

Rekey for a non-multitenant database

The following instructions assume that the HSM (wallet) is already open.

CONNECT TESTER@DB or CONNECT sysdba@DB

--Assumes the HSM is already open
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "<credential>";

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

CONNECT C##TESTER@CDB<n>

The following instructions assume that the required CDB has started, and that the required PDBs and HSM (keystore) are already open.

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

Rekey for a multitenant database with the CDB only

The following instructions assume that the required CDB has started and the HSM (keystore) is already open.

CONNECT C##TESTER@CDB<n>

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

Rekey for a multitenant database with a single PDB only

The following instructions assume that the required CDB has started, and that the required PDB and HSM (keystore) are already open.

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

--Create the master key for the PDB you are currently connected to
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;