D Using OKM with Advanced Security Transparent Data Encryption (TDE)
You can use OKM with Transparent Data Encryption (TDE) to manage encryption or decryption of sensitive database information. This solution allows you to manage encryption keys for the Oracle database using the same encryption technology used in Oracle StorageTek tape drives.
This section assumes familiarity with TDE. See the white paper Oracle Advanced Security Transparent Data Encryption Best Practices, available at the following URL:
http://www.oracle.com/technetwork/database/security/twp-transparent-data-encryption-bes-130696.pdf
Overview of Transparent Data Encryption (TDE)
Transparent Data Encryption (TDE), a feature of Oracle Database 11gR2 and higher, provides database encryption and decryption services for the following products:
-
Oracle Database
-
Oracle Real Application Clusters (Oracle RAC)
-
Oracle Data Guard
-
Oracle Exadata Database Machine
-
Oracle Recovery Manager (RMAN)
-
Oracle Data Pump
Figure D-1 shows an OKM cluster featuring an Oracle database with Transparent Data Encryption (TDE). See Chapter 1, "OKM Overview and Installation Planning" for more information about the basic components of the OKM cluster.
TDE provides encryption services using a two-tiered key approach for TDE column encryption and TDE tablespace encryption. The first tier uses a master encryption key to encrypt the second tier table or tablespace data encryption keys that are stored within the database.
TDE stores the master encryption key in an external security module (Oracle Wallet or hardware security module). This is a recommended security practice and is crucial to maintaining the highest level of security from various threats. Use of OKM for the secure storage of the TDE master encryption keys is the recommended approach.
With TDE configured to use OKM, OKM creates and safely protects the AES256 master encryption key. OKM protects keys through replication (multiple copies across the cluster) and through backups of OKM itself.
Refer to "Disaster Recovery" for information about disaster recovery planning.
The following minimum versions are supported when using OKM with TDE:
Oracle Key Manager
-
Oracle Key Manager 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
-
Oracle Solaris 11 Express with SRU 12
-
Oracle Solaris 11 with x86 or SPARC, 32 bit or 64 bit
-
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 or higher.
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 and 12.2
OKM PKCS#11 Provider
A PKCS#11 provider is available for Oracle Solaris and Oracle Linux and has been certified to interface TDE with OKM. This provider is called "pkcs11_kms." You can configure TDE cto use the pkcs11_kms provider through its built-in support for hardware security modules.
The pkcs11_kms provider interacts with OKM for key creation and key retrieval operations. PKCS#11 consumer applications, such as TDE, can use the pkcs11_kms provider to acquire keys to use for encryption and decryption functions. These applications identify key objects using a unique label that they define. TDE generates this label when the master key is created. The pkcs11_kms provider passes this label to OKM where it is maintained as metadata on the data unit. In OKM, keys are associated with data units and for the pkcs11_kms provider, this relationship should always be 1:1. Each time a new master key is created, a data unit with the key's label is created along with the corresponding key object. The key label name space in OKM is cluster-wide.
Key label naming conflicts can arise with other clients of OKM. Consequently, users of the pkcs11_kms provider should devise a key label naming scheme that insures uniqueness of key labels.
See "Locate TDE Master Keys in OKM" for more information.
TDE Authentication with OKM
Any entity that interacts with OKM must authenticate, whether it be an administrative user logging in, a tape drive retrieving key material, or a PKCS#11 consumer such as Oracle TDE.
TDE authenticates with OKM through the specific token configured to use the pkcs11_kms provider. This token uses password-based authentication and X.509 certificates for mutual authentication of each party in the session, specifically the Oracle database instance and the OKM cluster node. You must configure TDE to properly pass these credentials to the PKCS#11 token.
The TDE password should simply be the passphrase of the OKM agent (see "Configure Database for TDE"), not the AgentID:AgentPassword as suggested in the Oracle TDE documentation.
For configuration instructions, refer to the document Oracle Advanced Security Transparent Data Encryption Best Practices, referenced at the beginning of this appendix.
Manage Authentication Credentials
OKM allows you to manage authentication credentials for agents using the pkcs11_kms provider. You can reset agent passphrases, and enable, disable or delete agents as your policies dictate.
If a security breach is detected, you may disable the specific agent so that key retrievals are denied, while allowing other agents servicing other applications or devices to maintain their access.
If you reset an agent passphrase, then remove the profile directory in the directory where the pkcs11_kms provider stores its slot configuration (for example, the location identified by the KMSTOKEN_DIR directory).
Load Balancing and Failover When Using pkcs11_kms
The pkcs11_kms provider is aware of the OKM cluster through use of OKM cluster services, a load balancer and cluster failover logic. The pkcs11_kms provider transparently maintains client-side awareness of the OKM cluster by periodically issuing cluster discovery operations. Network changes and changes in the OKM cluster or KMA availability are handled by the agent on behalf of the pkcs11_kms provider and TDE. PKCS#11 key generation and key retrieval operations are load balanced across KMAs in the OKM cluster.
To further optimize key retrieval performance, agents may be configured to be associated with KMAs through use of OKM sites. This feature allows definition of sites according to network topology. Typically, KMAs and agents within a site would have low network latency as opposed to member KMAs and agents across a WAN.
When a network segment or KMA is unavailable, the failover logic within the agent chooses another KMA to complete the operation. TDE is unaware of any failovers, so key management operations are very reliable. Failover preferences KMAs within the same site as the agent.
You can use the kmscfg(1M) utility to tune the discovery frequency and the failover properties of the agent. See the kmscfg man page for more information.
Planning Considerations When Using TDE
-
"OKM Performance and Availability Considerations When Using pkcs11_kms"
-
"Network and Disaster Recovery Planning When Using pkcs11_kms"
Oracle Database Considerations When Using TDE
OKM is compatible with any of the following Oracle Database configurations:
-
Single Instance, Oracle RAC One Node
-
Oracle Database High Availability Architectures
-
Oracle RAC
Oracle Database with Oracle Real Application Clusters (Oracle RAC) is certified with OKM. Each node of the Oracle RAC system requires a configured pkcs11_kms provider for TDE to use. All nodes must share the same OKM agent ID for authentication. With Oracle RAC, the network topology uses a public and private network. The private network used for Oracle RAC node-node traffic may be shared with the OKM service network for better isolation of key retrieval traffic. Depending on how this private network is configured, this likely precludes agent failover to KMAs outside the private network such as KMAs in a remote site.
See "Integrate OKM and TDE" for shared storage requirements with Oracle RAC and the pkcs11_kms provider configuration files.
-
Oracle RAC Extended Cluster
In this configuration, KMAs within the OKM cluster must be colocated in the network with Oracle RAC nodes to minimize retrieval time.
-
Oracle Exadata Database Machine. See "Oracle RAC" above.
-
-
Oracle Data Guard
All secondary databases access the same OKM cluster used by the primary database.
-
Multiple Database Instances
When running multiple independent database instances on a host, a PKCS#11 token must be configured for each instance. This amounts to creating an OKM agent for each database instance, and authenticating the agent to OKM through the token. Use the kmscfg tool to complete this task.
When running multiple database instances under the same O/S user, but using different OKM agents, you must set the KMSTOKEN_DIR environment variable to a different location each time you invoke the kmscfg utility. See "Configure Database for TDE" for more information about the kmscfg utility.
For more information about running multiple databases on the same host, refer to the document Oracle Advanced Security Transparent Data Encryption Best Practices, referenced at the beginning of this appendix.
-
Oracle RMAN
-
Oracle Data Pump
OKM Performance and Availability Considerations When Using pkcs11_kms
Key retrievals for TDE through the pkcs11_kms token typically take 100-200 milliseconds per KMA access. When failovers occur, the response time is a multiple of the number of failover attempts.
OKM backup and key transfer operations are resource-intensive activities that can impact OKM database performance. Plan carefully to determine when and where to perform OKM backups.
Since OKM backups are cluster-wide, they can be performed on KMAs that are not servicing Oracle Database instances. Similarly, key transfer operations are also cluster-wide operations and can be performed on any KMA. Therefore, it is recommended that you choose a KMA that is not servicing busy Oracle Database instances.
Network and Disaster Recovery Planning When Using pkcs11_kms
OKM cluster configuration must be planned in accordance with the Oracle Database servers and the enterprise's disaster recovery strategy. OKM networking options are very flexible and include multi-homed interfaces used by the OKM management and service network. Oracle recommends that TDE access be over the OKM service network.
For detailed information about OKM disaster recovery planning, refer to "Disaster Recovery" along with the Oracle database publications.
Disaster Recovery planning decisions influence the network planning exercise. The pkcs11 provider's configuration directory is a new consideration for disaster recovery planning. Consider recovery scenarios for this storage area to avoid the need to reconfigure a pkcs11_kms token, especially when it is shared between nodes of an Oracle RAC.
Key Management Planning When Using pkcs11_kms
Key management planning must address the key life cycle and security policies of the enterprise. These considerations will naturally lead to discussions on data retention.
-
See "OKM Key States and Transitions" for information about NIST SP-800 key management phases and corresponding OKM key states.
-
See "Re-Key Due to OKM Policy Based Key Expiration" for information about an issue that can occur when a key policy is not set to a long enough time period.
All TDE master keys are Advanced Encryption Standard (AES) 256 bits generated by OKM. KMAs may contain a FIPS 140-2 Level 3-certified hardware security module, such as an SCA 6000 PCIe card. When KMAs have this hardware security module, their keys are created by the hardware security module. Otherwise, cryptographic operations use the Solaris Crypto Framework's software token provider. See "Manage Key Policies" for more information.
Key Lifecycle — The key lifecycle is the primary configuration item with respect to key policy planning decisions. The periods for the operational phase of the key's lifecycle should be chosen based upon data retention needs and the frequency with which TDE master keys will be re-keyed. The TDE DDL supports specification of various key sizes for the master key, as does the schema encryption dialogs within OKM. Only AES 256 bit keys can be used with OKM.
Key Policy Encryption Period — The key policy encryption period defines the length of time for the key to be used in the protect and process (encrypt and decrypt) state of the lifecycle. This period should correspond to the time period for use of the master key before it should be re-keyed (for example, maximum one year for PCI).
Key Policy Cyptoperiod — The key policy cryptoperiod is the remaining time allotted for use of the master key to decrypt data during the process only (decrypt only) state of the key lifecycle. The length of this period should conform to the data retention requirements for the data protected by the TDE master key. Typically this value is a number of years corresponding to the enterprise policy for data retention (for example, a seven year retention period for US tax records). The rate at which new keys will be generated should not be a concern with TDE as re-key operations will likely be infrequent. However, if this becomes a concern, then consider lengthening the encryption period on the key policy and re-keying less frequently. You can also increase the OKM key pool size configuration parameter to direct the KMAs to maintain a larger pool of available keys. Multiple key policies may be defined for use with different types of databases as needs dictate.
Key Access Control Through Key Groups
It may be necessary to control access to keys managed by OKM when multiple database instances or multiple agents are accessing the OKM cluster for various purposes.
All OKM agents are assigned to at least one key group (a default key group assignment is required), which authorizes them to have access to the keys within those groups. The agent's default key group is the only key group within which a pkcs11_kms provider's agent will create keys.
Consider using multiple key groups when master keys do not need to be shared across database instances or hosts. An example might be to use one key group for production database instances and another key group for development/test databases, so that isolation is assured. Agents in the test database key group would then be blocked by OKM if they attempt to use a master key for a production database. Such an attempt would also be flagged in the OKM audit log and may be an indicator of a configuration error that could disrupt a production database.
TDE also provides isolation of master keys through their key label naming convention. In the PKCS#11 specification, key labels are not required to be unique. However, OKM enforces unique labels unless the agent includes a default key group attached to a key policy where "Allows Revocation" is true. In this case, OKM relaxes the uniqueness constraints and issues a warning instead of an error for duplicate labels.
If a label conflict occurs between different master keys for different database instances, the first label created is always returned. Any agent attempting to access a key that shares an identical label belonging to another key group will be denied by OKM. This is detected during a re-key operation, and the work around is to re-key until another, non-conflicting, label is generated.
Key and Data Destruction Considerations
Destruction of data to conform to data retention requirements can begin with the destruction of TDE master keys. How and when these keys should be destroyed is an important planning item. OKM provides for this and for tracking of OKM backups, which include these keys. Management of OKM backups is both a Disaster Recovery planning item and key destruction planning item.
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
The following minimum versions are supported when using OKM with TDE:
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 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
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
The OKM cluster installation process is described in the OKM Installation Guide. 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
You must install and configure the OKM PKCS#11 Provider, pkcs11_kms, on the Oracle database server(s). A pkcs11_kms distribution is available for each of following platforms:
-
Oracle Solaris 11
-
Oracle Solaris 10 Update 10
-
Oracle Linux Server
Perform the following steps to install pkcs11_kms:
-
Display the version of the pkcs_kms package:
#> pkg info -r pkcs11_kms
Verify the output of this command.
-
Enter the following command:
#> pkg install system/library/security/pkcs11_kms
-
Install the provider into the Solaris Crypto Framework.
# cryptoadm install provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
Note:
The single quotes are significant. see cryptoadm(1M). -
Enter the following sequence of commands to verify the installation:
# cryptoadm list -m -v \ provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
Note:
This displays message: 'no slots presented' until kmscfg is run.
The pkcs distribution is installed as "SUNWpkcs11kms" in Solaris 10 Update 10 installations.
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
-
Enter the following command to install the pkcs11_kms package for the hardware platform:
# pkgadd [-d path to parent dir of package] SUNWpkcs11kms
-
Install the provider into the Solaris Crypto Framework.
# cryptoadm install provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
Note:
The single quotes are significant. see cryptoadm(1M).
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
Log in and click the Patches & Updates tab and search for the specific patch ID directly.
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
To uninstall pkcs11_kms, enter the following commands:
# cryptoadm uninstall \
provider='/usr/lib/security/$ISA/pkcs11_kms.so.1'
# pkg uninstall system/library/security/pkcs11_kms
To uninstall pkcs11_kms, enter the following command:
# pkgrm SUNWpkcs11kms
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
Each Oracle Database server must be running on a supported pkcs11_kms platform; see "pkcs11_kms" for details. 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
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.
-
Define the key policy. See:
-
Define the group definition. Assign the key policy to the key group and a handy name for the group. See:
-
Configure agent(s). See:
-
Associate each agent with a default key group. See "Assign Agents to Key Groups".
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.
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.
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
The pkcs11_kms provider must be configured on the Oracle Database nodes that will require TDE master keys. Perform the following steps to configure the pkcs11_kms provider:
-
O/S User Considerations:
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.
-
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.
-
-
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.
-
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.
-
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.
-
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
At this point, you have defined a pkcs11 slot and you can verify authentication with OKM.
-
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 Number of slots: 1 Slot #1 Description: Oracle Key Management System Manufacturer: Oracle Corporation PKCS#11 Version: 2.20 Hardware Version: 0.0 Firmware Version: 0.0 Token Present: True Slot Flags: CKF_TOKEN_PRESENT Token Label: KMS Manufacturer ID: Oracle Corporation Model: Serial Number: Hardware Version: 0.0 Firmware Version: 0.0 UTC Time: PIN Min Length: 1 PIN Max Length: 256 Flags: CKF_LOGIN_REQUIRED
-
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.
solaris> pktool inittoken currlabel=KMS Enter SO PIN: Token KMS initialized.
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.
-
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' Provider: /usr/lib/security/$ISA/pkcs11_kms.so.1 Number of slots: 1 Slot #1 Description: Oracle Key Management System Manufacturer: Oracle Corporation PKCS#11 Version: 2.20 Hardware Version: 0.0 Firmware Version: 0.0 Token Present: True Slot Flags: CKF_TOKEN_PRESENT Token Label: KMS Manufacturer ID: Oracle Corporation Model: Serial Number: Hardware Version: 0.0 Firmware Version: 0.0 UTC Time: PIN Min Length: 1 PIN Max Length: 256 Flags: CKF_LOGIN_REQUIRED CKF_TOKEN_INITIALIZED
-
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> -
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.
-
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
-
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).
-
-
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.
Migration of Master Keys from the Oracle Wallet
The old wallet must be retained and a new master key will be generated by OKM and safely protected by the key management system. Refer to the document Oracle Advanced Security Transparent Data Encryption Best Practices, referenced at the beginning of this appendix.
The Oracle Database Administrator must perform re-key operations before the key's lifecycle dictates. Otherwise, the database will not start. Refer to the various Oracle Database and TDE documents for the DDL used to perform this operation. Re-keying may also be performed using Oracle Enterprise Manager.
Re-Key Due to OKM Policy Based Key Expiration
Once a key reaches the post-operational state, each key retrieval by TDE will trigger a warning in the OKM audit logs indicating that a post-operational key has been retrieved. Presence of these audit messages is an indication that it is time to re-key the database instance's master encryption key. The OKM audit message identifies the specific agent and key that is being retrieved to facilitate identification of the Oracle Database instance and master encryption key that has reached the post-operational state. Notification through SNMP v3 informs or SNMP v2 traps may be configured in OKM to support automation of this process.
The pkcs11_kms provider will attempt to inform its PKCS#11 consumers that the key has reached the post-operational state. This is done by setting the PKCS#11 "CKA_ENCRYPT" attribute to false for the master key.
All released versions of Oracle Database 11 and 12 will try to use a key to encrypt data after its encryption period has expired. TDE will never automatically re-key the TDE master key.
On Solaris, you may see errors similar to the following in the database alert logs:
HSM heartbeat died. Likely the connection has been lost. PKCS11 function C_EncryptInit returned PKCS11 error code: 104 HSM connection lost, closing wallet
If this error is encountered, the Database Administrator must perform the following actions:
-
Set an environment variable for the user associated with the pkcs11_kms token (typically the Oracle user's profile). This allows the deactivated key to continue to be used for encryption:
# export PKCS11_KMS_ALLOW_ENCRYPT_WITH_DEACTIVATED_KEYS=1
-
Restart the database.
-
Rekey the master key for the database instance, following the instructions in your Oracle Database administration documentation.
On Oracle Linux, the default for the pkcs11_kms provider allows use of deactivated keys, however, you will see errors similar to the following in the /var/log/messages file:
pkcs11_kms: Encrypting with key which does not support encryption (check to see if key is expired or revoked
If this message is encountered, the database administrator should re-key the TDE master key as described in the Oracle Database administration documentation.
In spite of this, TDE will continue to use the key and not perform an automatic re-key operation. OKM administrators observing the post-operational key retrieval audit warnings must inform a Database Administrator that it is time to re-key their database instance's master key.
Convert from Another Hardware Security Module Solution
Contact Oracle technical support for specific steps required to convert from another vendor's hardware security module solution to OKM.
Key Destruction When Using TDE
Before destroying keys that have reached the post-operational phase, the OKM administrator must verify that the key is no longer being used.
OKM administrators are responsible for the regular destruction of keys in the post-operational phase. Deletion of keys through the pkcs11_kms provider is not supported with OKM and is a restricted operation reserved for OKM users that have been assigned the role of Operator. Once a key has been destroyed, any attempt to retrieve it will fail, including PKCS#11 C_FindObjects requests.
Key Transfer in Support of Oracle RMAN and Oracle Data Pump
Use of Oracle RMAN and/or Oracle Data Pump may require the ability to supply the master key to another OKM cluster, perhaps at a disaster recovery site or with a partner. OKM key transfer operations readily support this using the secure key export and key import services. See "Transfer Keys Between Clusters" for more information.
-
Establish key transfer partners between the source and destination OKM clusters.
-
Identify the TDE master keys to be exported in support of Oracle RMAN backups or encrypted data exported using Oracle Data Pump.
-
Export the keys from the source OKM cluster. This will create a secure key export file.
-
Transmit the exported key file to the transfer partner.
-
The destination transfer partner imports the keys into their OKM cluster.
Run Oracle RMAN restore or Oracle Data Pump import to re-create the database instance that requires the keys. This requires the configuration steps necessary to use TDE with OKM at the importing location. The restore or import operation then accesses the OKM for the universal master keys required to decrypt the column or tablespace keys used by the database instance.
Attestation, Auditing, and Monitoring for TDE
Oracle recommends the following:
-
Review and monitor the OKM active history of the TDE agent to help detect problems.
-
Auditors can use OKM audit events to attest that TDE is accessing its master keys from the OKM cluster.
-
Configure an SNMP manager for OKM.
-
Explore the use of OKM CLI to generate enterprise specific reports.
Locate TDE Master Keys in OKM
You can locate the TDE master keys within OKM using either the GUI or CLI. TDE generates the master key labels and OKM uses a data unit's External Tag attribute to store this value. TDE master key generation (including re-key operations) always creates a new data unit object and key object within the OKM cluster.
-
Perform a query on the OKM data units and filter the list using an ExternalTag filter: "ExternalTag" begins with "ORACLE.TDE". All TDE key labels begin with this string so this will generate a list of OKM data units that were created by TDE. Each OKM data unit will have a single TDE master key associated with it. These keys can be viewed using the OKM GUI to examine their lifecycle state and other properties, such as key group, export/import status, and which OKM backups contain destroyed keys. These keys can also be viewed using the OKM CLI. For example:
>okm listdu --kma=acme1 --user=joe \ --filter="ExternalTag=ORACLE.TDE"
-
When multiple Oracle Database instances share an OKM cluster, an OKM administrator can identify which keys correspond to a particular database by using a query against the audit events for the agent that corresponds to that database instance. These audit events can be viewed using the Oracle GUI. Filter the agent's audit history using the filter: "Operation equals CreateDataUnit". This produces a list of the audit events corresponding to TDE master key creations. The audit event details provide the necessary information to identify the specific data units for the master keys. These audit events can also be viewed using the OKM CLI. For example:
>okm listauditevents --kma=acme1 --user=joe \ --filter="Operation=CreateDataUnit"
Troubleshooting When Using pkcs11_kms
This section describes error conditions that may be encountered when using OKM with pkcs11_kms.
Cannot Retrieve the Master Key When Using pkcs11_kms
The Oracle Database reports one of the following errors when the master key cannot be retrieved:
-
ORA-28362
-
ORA-06512
If these errors are encountered, perform the following diagnostic steps to identify the issue:
-
Examine the $ORACLE_BASE/diag/rdbms/$SID/$SID/trace/alert_$SID.log file. This file logs success/fail messages related to "alter" DDL statements used to access the encryption wallet.
-
Examine the KMSAgentLog.log file in the pkcs11_kms configuration directory ($KMSTOKEN_DIR/KMSAgentLog.log).
-
Verify the general status of OKM. Check the following:
-
Are KMAs active?
-
Are KMAs locked?
-
Is the key pool depleted?
-
KMA ILOM/ELOM faults
-
KMA console messages
-
-
Verify the status of the pkcs11_kms token as demonstrated earlier.
-
Verify the status of the agent by examining OKM audit events for that agent to ensure that it enrolled and is enabled.
-
Verify network connectivity from the Oracle Database host to OKM nodes.
-
Contact Oracle Technical Support. You may be asked to provide one or more KMA System Dumps.
Loss of the pkcs11_kms Configuration Directory
Use the following procedure to recover a lost or corrupted pkcs11_kms token profile:
-
Perform the configuration steps described in "Configure Database for TDE".
-
Solaris Only - Repopulate the token's metadata, using the following data unit filter with the OKM: "ExternalTag" begins with "ORACLE.TDE".
-
Solaris Only - Save the results of this listing to a file (for example "du.lst") and then execute the following shell script:
for label in `awk '{print $2}' < du.lst ` do pktool list token=KMS objtype=key label="${label}" done
No Slots Available Error When Using pkcs11_kms
The client gets "No Slots Available" errors when issuing any PKCS#11 operation.
-
Ensure that the kmscfg utility has run successfully.
-
Ensure that the pkcs11_kms provider has been properly installed and configured.
CKA_GENERAL_ERROR Error When Using pkcs11_kms
The client gets the CKA_GENERAL_ERROR error when trying to retrieve keys.
-
Verify that the agent has a default key group in the OKM cluster.
-
Review the $KMSTOKEN_DIR/KMSAgentLog.log file for more information.
Could Not Open PKCS#12 File Error
The "Could not open PKCS#12 file" error appears in the $KMSTOKEN_DIR/KMSAgentLog.log file.
-
Select audit events in the OKM cluster to determine whether the agent passphrase has recently changed.
-
Remove the <profile-name> directory under $KMSTOKEN_DIR.