1. Installation and Administration Guide
  2. Advanced Security Transparent Data Encryption (TDE)
  3. Integrate OKM and TDE

Integrate OKM and TDE

This section describes how to install and configure pkcs11_kms and the OKM cluster for use with TDE.

System Requirements for OKM and TDE

Using OKM with TDE requires the system to meet minimum requirements.

Oracle Key Manager

OKM 2.4.1 operating with Replication Schema version 13. Supported OKM management platforms for the GUI and CLI are documented in the OKM product release notes, which include specific considerations for Oracle Solaris and Microsoft Windows platforms.

pkcs11_kms

pkcs11_kms is supported on the following platforms:

  • Oracle Solaris 11.x (all SRUs)
  • Oracle Solaris 10 Update 10 pkcs11_kms patch 147441-03 for x86 or patch 147159-02 for SPARC, 32 bit or 64 bit
  • Oracle Linux Server, release 5.5, 5.6, 5.9, 6.5, and 7

Oracle Database

OKM can be integrated with TDE as the following versions of the Oracle Database server on a supported pkcs11_kms platform:

  • Oracle Database 11.2.0.2 with patch 12626642
  • Oracle Database 11.2.0.4
  • Oracle Database 12.1
  • Oracle Database 12.2

Install OKM for TDE

Install OKM using the standard installation instructions, then use the procedures here for TDE.

The OKM cluster installation process is described in the Install the KMA. Typically, OKM installation involves engagement with Oracle Professional Services, to aid in planning, installation, and configuration service choices. Additionally, it is recommended that your security team be involved in the planning process.

After you establish a working OKM cluster, follow the OKM administration steps described in the configuration sections of this appendix.

Install pkcs11_kms

Install and configure the OKM PKCS#11 Provider, pkcs11_kms, on the Oracle database server(s).

A pkcs11_kms distribution is available for each platform.

Oracle Solaris 11

  1. Display the version of the pkcs_kms package:
    #> pkg info -r pkcs11_kms
  2. Enter the following command: 
    #> pkg install system/library/security/pkcs11_kms
  3. Install the provider into the Solaris Crypto Framework. The singel quotes are significant.
    # cryptoadm install provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
  4. Enter the following sequence of commands to verify the installation:
    # cryptoadm list -m -v \
provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'

    This displays message: 'no slots presented' until kmscfg is run.

Oracle Solaris 10 Update 10

The pkcs distribution is installed as "SUNWpkcs11kms" in Solaris 10 Update 10.

SPARC systems require Solaris patch 147159-03 or later. x86 systems require Solaris patch 147441-03 or later. To download Solaris patches, go to: https://support.oracle.com

  1. Enter the following command to install the pkcs11_kms package for the hardware platform.
    # pkgadd [-d path to parent dir of package] SUNWpkcs11kms
  2. Install the provider into the Solaris Crypto Framework. The single quotes are significant.
    # cryptoadm install provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'

Oracle Linux Server

pkcs11_kms is distributed as patch 26093641 for Linux 6 and patch 25979695 for Linux 7 on the My Oracle Support site at https://support.oracle.com

  1. Log in and click the Patches & Updates tab and search for the specific patch ID directly.
  2. pkcs11_kms is distributed as an RPM package. Use RPM package manager commands to install this software.

    For example: rpm -i pkcs11kms-1.3.0-1.x86_64.rpm

Uninstall pkcs11_kms

The procedures for unistalling pkcs11_kms depend on the platform.

Oracle Solaris 11

Enter the following commands:

# cryptoadm uninstall \

provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'

# pkg uninstall system/library/security/pkcs11_kms

Oracle Solaris 10 Update 10

Enter the following command:

# pkgrm SUNWpkcs11kms

Oracle Linux Server

When packaged with Oracle Database, the pkcs11_kms provider will be uninstalled through the steps used to uninstall the Oracle Database product. If installed through another means, then follow the inverse procedures of the install using rpm.

For example:

# rpm -e pkcs11kms-1.3.0-1.x86_64.rpm

Configure Database for TDE

Configure the shared library file (pkcs_kms.so) for TDE access.

Each Oracle Database server must be running on a supported pkcs11_kms platform. For Oracle Database 12.2.0.2, mandatory patch 12626642 must be installed. This patch is available at the following URL:

https://updates.oracle.com/download/12626642.html

Once installed, the shared library file (pkcs_kms.so) must be configured for TDE access. The library path is OS-specific:

  • /usr/lib/security/pkcs11_kms.so.1 (Solaris only, 32-bit)
  • /usr/lib/security/amd64/pkcs11_kms.so.1 (Solaris only, 64-bit)
  • /usr/lib64/pkcs11_kms.so.1 (Linux only, 64-bit)

Configure the OKM Cluster for TDE

Configure an already functional OKM cluster for TDE.

These tasks assume a functioning OKM cluster configured with appropriate administrative users and roles. All KMAs in the OKM cluster must be running a minimum of OKM 2.4.1 and Replication Version 13.

  1. Define the key policy. See:
  2. Define the group definition. Assign the key policy to the key group and a handy name for the group. See:
  3. Configure agent(s). See:
  4. Associate each agent with a default key group. See Assign Agents to Key Groups.
    • Agent ID — The agent ID can be anything meaningful to the configuration, and should correspond to the Oracle user for the database instance to be associated with the agent.
    • Passphrase — Choose a strong passphrase as this passphrase will also be configured on the Oracle host for authenticating with OKM through the DDL statements that open the wallet (for example, the pkcs11_kms token). See Create an Agent for information about passphrase requirements. OneTimePassphrase flag should be set to "false" to allow password-based authentication any time the TDE "wallet" must be opened, as well as from multiple Oracle RAC nodes sharing a common agent ID. For maximum security this can be set to the default value of "true," but will only work in a single node Oracle Database configuration and not in Oracle RAC. When OneTimePassphrase is true, the agent's X.509 certificate is returned only when the agent successfully authenticates the first time. The pkcs11_kms provider securely stores the X.509 certificate's private key in a PKCS#12 file that is protected by a passphrase. The X.509 certificate and corresponding private key are then used for agent transactions with OKM. See kmscfg(1M) for other information that the pkcs11_kms provider stores.
    • Key Group — Assign the agent to the key group(s) defined for TDE. The pkcs11_kms provider only supports the default key group for key creation operations, including re-key operations. Any additional, non-default key groups associated with the agent will only allow key retrievals from keys in those groups. This capability could be leveraged in read-only/decryption-only database scenarios such as in support of a secondary database that will never generate a master key, but only needs the ability to access the master keys.

Configure kcs11_kms

Configure the pkcs11_kms provider on the Oracle Database nodes that will require TDE master keys.

  1. Configure the agent and pkcs11_kms provider using the Oracle Database user account. This does not require special privileges for the O/S user. When a host supports "Multiple Oracle Homes," then the pkcs11_kms token configuration must be in accordance with each Oracle Database software owner's user account. Refer to the Oracle Database Installation Guide 11g Release 2 for more information.
  2. The kmscfg utility creates one slot configuration per user at a time. It is possible to define additional slot configurations for an individual user, but only one will be active per process.

    Caution:

    The default location of the slot configuration directory for the KMS PKCS#11 provider is /var/kms/$USER on Solaris 11 Express and is /var/user/$USER/kms on Solaris 11. If you plan to upgrade your Solaris 11 Express system to Solaris 11, then you should first save your slot configuration elsewhere.

    For example:

    # cd /var/kms/$USER

    # tar cvf ~/save_my_okm_config.tar .

    After the upgrade, restore your slot configuration to the new location. For example:

    # mkdir -p /var/user/$USER/kms

    # cd /var/user/$USER/kms

    # tar xvf ~/save_my_okm_config.tar

    If you do not back up pcks11_kms data before you upgrade, your data will be lost and the master key used by the Oracle data base for encrypted data will not be available.

    The kmscfg utility stores configuration and run-time data in a KMS configuration directory at one of the following paths:

    • /var/user/$USER/kms (Solaris 11)
    • /var/kms/$USER (Solaris 10u10 and Solaris 11 Express)
    • /var/opt/kms/$USER (Oracle Linux Server)

    This directory is overridden by the $KMSTOKEN_DIR environment variable to the location of the customer's choosing.

    When kmscfg runs, a "profile" name is provided. This name is used for the agent-specific run-time subdirectory created within the configuration directory described above.

  3. Refer to the kmscfg man page for the default location of its slot configurations. Slot configurations may be controlled using the KMSTOKEN_DIR environment variable to define an alternate slot configuration and file system location.
    For Oracle RAC, where the agent profile must be shared between Oracle RAC nodes, use the KMSTOKEN_DIR environment variable to direct kmscfg to create the profile using the appropriate shared filesystem path. If the KMSTOKEN_DIR environment variable is set, it must be set persistently for the shell in a shell configuration file (such as .bashrc) so that it is always set before the database performing any PKCS#11 operations.
  4. Allocate file system storage space for the slot's configuration and run-time information. If you plan to use Oracle RAC, define the profile in a shared file system location with permissions that are readable and writable by each of the Oracle RAC node users.
  5. Allocate space requirements to allow for growth in each agent log. The log file is automatically created and is a helpful troubleshooting tool. The space consumed by the KMSAgentLog.log file can be managed using a tool like logadm(1M) on Solaris or logrotate(8) on Oracle Linux Server. Allocating 10 MB for each agent's profile directory is adequate for most configurations.
  6. Initialize a pkcs11_kms provider using the kmscfg utility. In this step, you define a profile for the OKM agent that will later be associated with a pkcs11_kms token.
     # kmscfg 
 Profile Name: oracle
 Agent ID: oracle
 KMA IP Address: kma1
  7. Verify authentication with OKM.
    1. On Solaris systems, verify authentication using the cryptoadm(1M) command. Note that the flag field shows CKF_LOGIN_REQUIRED in the following example, indicating that the slot is not yet configured with an authenticated token.
      solaris> cryptoadm list -v \ 
provider='/usr/lib/security/$ISA/pkcs11_kms.so.1' 
Provider: /usr/lib/security/$ISA/pkcs11_kms.so.1 
...  
Flags: CKF_LOGIN_REQUIRED
    2. Verify that the pkcs11_kms token can authenticate with the OKM cluster. This example uses Oracle Solaris pktool(1), a utility that is not available for Linux platforms. The SO (PKCS#11 abbreviation for a security officer) prompt is for the agent's secret passphrase as established in a previous step by the OKM administrator who created the agent.
      solaris> pktool inittoken currlabel=KMS
Enter SO PIN:
Token KMS initialized.
    3. On Solaris systems, verify that the token is initialized by using the Solaris Crypto Framework cryptoadm(1M) command or the pktool(1) utility. Note that the token's flag shown by output from cryptoadm is now CKF_TOKEN_INITIALIZED: 
      solaris> cryptoadm list -v \
provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
 ...
 PIN Max Length: 256
 Flags: CKF_LOGIN_REQUIRED CKF_TOKEN_INITIALIZED
    4. On Solaris systems, use the pktool(1) utility to verify the status of PKCS#11 visible tokens:
      glengoyne> pktool tokens
Flags: L=Login required  I=Initialized  X=User PIN expired  S=SO PIN expired
Slot ID  Slot Name     Token Name                  Flags
-------  ---------     ----------                  -----
1        Sun Crypto    Softtoken      Sun Software PKCS#11 softtoken
2        Oracle Key Management System              KMS  L
glengoyne>

      This shows that Login to the token is still required. The meaning of the Flags in the pktool output can be shown as follows:

      glengoyne> pktool tokens -h
Usage:
   pktool -?    (help and usage)
   pktool -f option_file
   pktool subcommand [options...]

      where subcommands may be:

         tokens
   * flags shown as: L=Login required  I=Initialized  
     E=User PIN expired  S=SO PIN expired
glengoyne>
    5. On Solaris systems, use the pktool(1) utility to log in to the token and authenticate with the OKM cluster's KMA specified in the kmscfg(1) step and the passphrase created by an OKM administrator for the agent. This passphrase is supplied with the SO PIN prompt:
      glengoyne> pktool inittoken currlabel=KMS
Enter SO PIN:
Token KMS initialized.
    6. On Solaris systems, use the pktool(1) utility to verify the tokens status and that it is now initialized:
      glengoyne> pktool tokens
Flags: L=Login required  I=Initialized  X=User PIN expired  S=SO PIN expired
Slot ID  Slot Name   Token Name                    Flags
-------  ---------   ----------                    -----
1        Sun Crypto  Softtoken         Sun Software PKCS#11 softtoken
2        Oracle Key Management System              KMS   LI
    7. On Solaris systems, use the cryptoadm(1M) command to verify that the pkcs11_kms token is initialized by requesting to see the mechanisms that it supports:
      glengoyne> cryptoadm list -m -p  provider=/usr/lib/security/'$ISA'/pkcs11_kms.so.1
Mechanisms:
CKM_AES_KEY_GEN
CKM_AES_CBC
CKM_AES_CBC_PAD
glengoyne>

      On Solaris systems, use the pktool(1) utility to create and list keys through the pkcs11_kms provider as follows:

       # pktool genkey token=KMS keytype=aes keylen=256
   label=MyKey-test1
 # pktool list token=KMS objtype=key
 # pktool list token=KMS objtype=key label=MyKey-test1

      You can see the keys in the OKM system through the OKM Manager GUI or OKM CLI.

      Note:

      For Solaris, kmscfg(1) by default creates just one slot configuration per user at a time. You can define additional slot configurations, but only one will be active per process. You can do this by using the KMSTOKEN_DIR variable to define an alternate slot configuration and file system location.

      The Solaris 11 default is /var/user/$USERNAME/kms, but you can create your own naming schemes. A best practice might be /var/user/$USERNAME/$AGENTID-$CLUSTER/ This naming convention allows Solaris to have multiple slot-agent-cluster combinations based on various usage scenarios.

      For some PKCS#11 configurations, an alternate location is recommended, for example, TDE with Oracle RAC (see the TDE configuration section above), so that each node shares the pkcs11_kms provider's metadata).

  8. To configure TDE to use auto-open wallets, follow the instructions described in the document Oracle Advanced Security Transparent Data Encryption Best Practices, referenced at the beginning of this appendix.