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 are using a non-multitenant or multitenant database.

  • 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 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/12.80.4
chown oracle $ORACLE_BASE/extapi/64/hsm/nCipher/12.80.4
chgrp oinstall $ORACLE_BASE/extapi/64/hsm/nCipher/12.80.4
chmod 775 $ORACLE_BASE/extapi/64/hsm/nCipher/12.80.4

    2. copy/link the PKCS#11 library into the directory as the oracle user.

      cp /opt/nfast/toolkits/pkcs11/libcknfast.so $ORACLE_BASE/extapi/64/hsm/nCipher/12.80.4
      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.

      • If you are using Security World software v12, on the client run the Entrust nethsmadmin utility:

        >>nethsmadmin -c -m<n>

        Where <n> is the module number. The Security World must be shown as Initialized and Usable. For further details, see the User Guide for your HSM.

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. Oracle 11.1g or earlier versions might not support migration of some key types from a software wallet to an HSM. See the documentation for your Oracle version before attempting key migration.

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

Make sure you use 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, 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.

Non-multitenant

This section assumes database is open.

  • To open/close wallet:

    CONNECT TESTER@DB or CONNECT sysdba@DB

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

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

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

    Where the [ENCRYPTION] clause is optional.

Multitenant

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

  • To open/close 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 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 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>";

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 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 you back up your software wallet as an independent operation before attempting migration to the HSM. 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.

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

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

  1. 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='*';

  2. Migrate from the keystore to 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 wallet 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 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.

  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 "<keystorepassphrase>";

  2. 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='*';

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

    CONNECT sysdba@CDB1ROOT

    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@CDB1ROOT

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

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 up 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 up the WALLET_ROOT parameter.

    CONNECT sysdba@DB

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

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

Create the encryption keys

  1. Select the protection method (credential) that you require below, 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 created the master encryption keys in the HSM as above, proceed to encrypt your database by using tablespace encryption, column encryption, or both, as usual.

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. If your target database is non-multitenant, see Create master keys directly in an HSM 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.

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@CDB1ROOT

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

    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 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 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@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>";

--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 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, 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 non-multitenant database

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

CONNECT TESTER@DB, or CONNECT sysdba@DB

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

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 HSM (keystore) to be already open.

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

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>

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