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 you have an agreed organizational Certificate Practices Statement and a Security Policy/Procedure in place covering administration of the HSM. In particular, these documents should include 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, then 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 cards can be used for all database instances.

    • If you want to use OCS protection, the same 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 these 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, you need to decide the number of Operator Cards in the OCS card set. K/N functionality is not currently supported. This means that you must create 1/N OCS card sets. The number of OCS cards in a card set must at least match the number of HSMs that will be in your configuration, and with more to spare in case of a card loss or failure.

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

  • Entrust recommends that you create a policy for managing the passphrases for your:

    • ACS

    • Module protection

    • Softcard protection

    • OCS protection

    For information on passphrases, see About the HSM credential.

  • Entrust recommends that you create a policy for managing the physical security of your smartcards as used for ACS and OCS, and their deployment to authorized users.

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

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 an Entrust HSM, the following steps are required:

  1. Environment configuration.

  2. Install the Entrust HSM and Security World software.

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

Details of your installation and configuration will depend on:

  • Whether you want to migrate encryption keys from an existing Oracle software keystore to an Entrust HSM

  • 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 how you may set up your system, see the following Appendixes:

Basic set up

  1. Install the Entrust Security World software on each client in accordance with its accompanying documentation. If you are using Entrust Connects 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 key(s), set the following PKCS#11 environment variables:

    • Including OCS or Soft card key protection, and HSM load sharing:

      CKNFAST_LOADSHARING=1

    • Including module key protection:

      CKNFAST_FAKE_ACCELERATOR_LOGIN=1

    For more information, study the PKCS#11 library environment variables in the User Guide for your HSM.

  3. If you are using Entrust Connect(s), configure these to operate with your selected RFS and client(s) as described in your HSM documentation. Typically the client(s) will be the host server that your Oracle database is running on.

  4. Configure the Oracle PKCS#11 library folder to use the Entrust 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.6.8
chown oracle $ORACLE_BASE/extapi/64/hsm/nCipher/13.6.8
chgrp oinstall $ORACLE_BASE/extapi/64/hsm/nCipher/13.6.8
chmod 775 $ORACLE_BASE/extapi/64/hsm/nCipher/13.6.8

    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.8
      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, you will not be able to get these two systems to 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 nShield Connect (if being used). 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 for all clients and the RFS, and is loaded onto each nShield Connect used in the configuration.

  2. Check the Security World on your 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 Connect:

      • 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, then proceed as follows:

    • If you want to use module protection, no action is required at this point. Action is required later in the integration.

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

    • If you want to use a 1/N OCS card set protection, create the required number of card set(s) now, using exact 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, then 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, then create an OCS card set for this purpose.

Configuring Oracle database software to use the Entrust HSM

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.

    • 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 function using 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 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 HSM.

  • Create keys directly in HSM: 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 HSM.

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.

When using a softcard or OCS card, the <credential> will be a string containing the "passphrase|cardname" of the card being used. For instance, <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 completed migrating or creating encryption keys in an HSM, it is recommended to back up your Security World data, see the User Guide for your HSM.

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.

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

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

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

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

    SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE CONTAINER=ALL;

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.

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 the target database is multitenant, and you are already using a software wallet with TDE encryption.

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.

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

Use the WALLET_ROOT and TDE_CONFIGURATION parameters.

In the Oracle Server log in to the SQL database as sysdba.

CONNECT sysdba@FREEROOT

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

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

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

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER PLUGGABLE DATABASE ALL CLOSE;
SQL> ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM|FILE' CONTAINER = ALL;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN;
SQL> SHOW PARAMETER TDE_CONFIGURATION;

NAME                                 TYPE        VALUE
------------------------------------ ----------- ------------------------------
tde_configuration                    string      KEYSTORE_CONFIGURATION=HSM|FILE

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

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN;
SQL> 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:

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<credential>" MIGRATE USING <keystore-passphrase> WITH BACKUP;

  5. Check the encryption keys:

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

    % echo "list keys" | /opt/nfast/bin/rocs

`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs>   No. Name                     App        Protected by
    1 DATA_OBJECT_SUPPORTED_ID pkcs11     module
    2 ORACLE.TDE.HSM.MK.06E135 pkcs11     module
    3 ORACLE.SECURITY.KM.ENCRY pkcs11     module
    4 DATA_OBJECT_SUPPORTED_ID pkcs11     module
    5 DATA_OBJECT_SUPPORTED_ID pkcs11     module
    6 ORACLE.TDE.HSM.MK.060B47 pkcs11     module
    7 ORACLE.SECURITY.KM.ENCRY pkcs11     module
    8 DATA_OBJECT_SUPPORTED_ID pkcs11     module
rocs>

  6. Disable the auto login

    Here we only have to move keystore wallet file out of the way.

    sudo -u oracle mv <path-to-keystorefolder>/<keystore-folder>/tde/cwallet.sso <path-to-keystorefolder>/<keystore-folder>/tde/cwallet.sso.backup

  7. Bounce the database

    SQL> shutdown immediate;
SQL> startup;

  8. Close all keystores

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN READ WRITE;
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE CONTAINER=ALL;
SQL> ALTER SESSION SET CONTAINER = FREEPDB1;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         3 FILE                 CLOSED
         3 HSM                  CLOSED


SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         1 FILE                 CLOSED
         1 HSM                  CLOSED
         2 FILE                 CLOSED
         2 HSM                  CLOSED
         3 FILE                 CLOSED
         3 HSM                  CLOSED

  9. Open the HSM protection wallet on all databases

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER DATABASE OPEN;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN READ WRITE;
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>" CONTAINER=ALL;
SQL> ALTER SESSION SET CONTAINER = FREEPDB1;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         3 FILE                 CLOSED
         3 HSM                  OPEN

SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         1 FILE                 CLOSED
         1 HSM                  OPEN
         2 FILE                 CLOSED
         2 HSM                  OPEN
         3 FILE                 CLOSED
         3 HSM                  OPEN

Create master keys directly in an HSM for multitenant database

The following procedure applies when the target database is multitenant, and there is no preexisting software keystore.

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.

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.

In the Oracle Server log in to the SQL database as sysdba.

CONNECT sysdba@FREEROOT

Set the WALLET_ROOT and TDE_CONFIGURATION parameters

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

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER SYSTEM SET WALLET_ROOT = '<path-to-keystore>' scope=SPFILE;

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

    SQL> shutdown immediate;
SQL> startup;

  3. Set up the TDE_CONFIGURATION parameters as follows.

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER PLUGGABLE DATABASE ALL CLOSE;
SQL> ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=HSM" SCOPE=BOTH SID='*';
SQL> ALTER PLUGGABLE DATABASE ALL OPEN;
SQL> SHOW PARAMETER TDE_CONFIGURATION;

NAME                                 TYPE        VALUE
------------------------------------ ----------- ------------------------------
tde_configuration                    string      KEYSTORE_CONFIGURATION=HSM

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

    SQL> shutdown immediate;
SQL> startup;

Open the HSM keystore

You will see that when you open the HSM Keystore, the status will say OPEN_NO_MASTER_KEY.

SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER DATABASE OPEN;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN READ WRITE;
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<credential>" CONTAINER=ALL;
SQL> ALTER SESSION SET CONTAINER = FREEPDB1;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         3 HSM                  OPEN_NO_MASTER_KEY

SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> select CON_ID,WRL_TYPE,STATUS from V$ENCRYPTION_WALLET;

    CON_ID WRL_TYPE             STATUS
---------- -------------------- ------------------------------
         1 HSM                  OPEN_NO_MASTER_KEY
         2 HSM                  OPEN_NO_MASTER_KEY
         3 HSM                  OPEN_NO_MASTER_KEY

Create a TDE master encryption key

The TDE Master Encryption Key is stored inside the Entrust KeyControl. Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys and tablespace keys.

  1. Create the master encryption key:

    SQL> ALTER SESSION SET CONTAINER = CDB$ROOT;
SQL> ALTER PLUGGABLE DATABASE ALL OPEN;
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY <credential> WITH BACKUP CONTAINER = ALL;
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

    The master key is created.

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

  2. Check the encryption keys:

    Use the Entrust rocs utility to check that your encryption keys have been stored under the expected protection method before proceeding. You should see keys listed in the HSM based on the type of protection you are using.

    % echo "list keys" | /opt/nfast/bin/rocs

`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs>   No. Name                     App        Protected by
    1 DATA_OBJECT_SUPPORTED_ID pkcs11     module
    2 DATA_OBJECT_SUPPORTED_ID pkcs11     module
    3 ORACLE.TDE.HSM.MK.06377E pkcs11     module
    4 ORACLE.SECURITY.KM.ENCRY pkcs11     module
    5 ORACLE.TDE.HSM.MK.068E10 pkcs11     module
    6 ORACLE.SECURITY.KM.ENCRY pkcs11     module
    7 ORACLE.SECURITY.KM.ENCRY pkcs11     module
    8 ORACLE.SECURITY.KM.ENCRY pkcs11     module
rocs>

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 multitenant environments. 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

If the encryption keys are being shared or distributed between clients, then either a common shared Security World folder, or local client copies of the Security World folder, will be 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), you must first make sure that the new keys are available in the Security World folder it is using. If the new keys are available, then you can make the client hardserver instance recognize and use the new keys using either of the following options:

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

    CKNFAST_ASSUME_SINGLE_PROCESS=0

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

The above actions will cause the available keys to be scanned by the client’s hardserver instance, and any new keys will then be recognized and made usable. See Latency issues to understand the full consequences of these options.

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

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.
Before rekeying, you should inspect the contents of your Security World local folder, and note the date/time that you perform a rekey. After rekeying, you should verify that new key files have been created in your Security World local folder by inspection, and check the date/time stamp of new key files in the folder match the date/time you performed the rekey.

Rekey for a multitenant database with CDB only

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

CONNECT 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 begin by assuming the required CDB has started, the required PDB and HSM (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
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<credential>" WITH BACKUP;