1.0 Introduction
This article describes how to integrate Fortanix Self-Defending Key Management Service (KMS) with Oracle Transparent Data Encryption (TDE). It also contains the information that a user needs to:
- Generate a TDE master encryption key in Fortanix Self-Defending KMS
- Encrypt a tablespace or columns in a table
- Configure auto-login hardware security module (HSM)
- Perform hardware keystore migration
1.1 Why Fortanix Self-Defending KMS over Traditional HSM
The biggest security challenge when using TDE is securing the master key (called master encryption key, or MEK in Oracle). The ideal solution for securing the master key is to store it in an HSM and perform the wrapping and unwrapping of intermediate keys inside the HSM. Traditional HSMs often fall short when they are used in real world deployments of databases that have high “transactions per second” requirement and spread geographically. Traditional HSMs do not cluster very well, and even if they do, they rely on a client for load balancing which becomes a bottleneck as well as a security vulnerability.
Fortanix Self-Defending KMS is a next-generation HSM solution equipped to handle the high transaction rates that large commercial databases demand, and the ability to replicate keys across geographically distributed sites with minimal latency and high consistency. Fortanix Self-Defending KMS is designed to be infinitely scalable, highly available, and resilient to disasters and faults.
2.0 Terminology References
Fortanix Self-Defending KMS
Fortanix Self-Defending KMS is the cloud solution secured with Intel® SGX. With Fortanix Self-Defending KMS, you can securely generate, store, and use cryptographic keys and certificates, as well as secrets, such as passwords, API keys, tokens, or any blob of data.
TDE – Transparent Data Encryption
Transparent Data Encryption (TDE) enables you to encrypt sensitive data that you store in tables and tablespaces. Oracle Database uses authentication, authorization, and auditing mechanisms to secure data in the database, but not in the operating system data files where data is stored. To protect these data files, Oracle Database provides Transparent Data Encryption (TDE). To prevent unauthorized decryption, TDE stores the encryption keys in a security module external to the database, called a keystore. For more information, see Introduction to Transparent Data Encryption.
TDE Table Key
TDE Table key is an encryption key that is associated with a table whose columns are marked for encryption. The TDE master encryption key encrypts this table encryption key.
Tablespace Encryption Key
A Tablespace Encryption key is an encryption key for the encryption of a tablespace. The TDE master encryption key encrypts the tablespace encryption key, which in turn encrypts and decrypts data in the tablespace.
HSM – Hardware Security Module
A Security Module is an external keystore or a separate server or device that provides security storage for encryption keys. External keystores are external to an Oracle database. Oracle Database can interface with external keystores but cannot manipulate them outside of the Oracle interface. The Oracle database can request the external keystore to create a key, but it cannot define how this key is stored in an external database.
3.0 Prerequisites
- Fortanix Self-Defending KMS
- CA certificate for on-premise installation Fortanix Self-Defending KMS in PEM format.
- Oracle Database running on a Linux or Windows server (for example: Oracle database version 12c (Release 12.2.0.1.0) on Red Hat Enterprise Linux Server release 7.5). Supported Oracle Database versions are: 11g R2, 12c, 18c, 19c.
- For Oracle 11g, make sure Oracle Database patch 18948524 is applied. This patch enabled Auto-login mode of HSM wallet.
- Download the Fortanix PKCS#11 library from here.
4.0 Configuring Fortanix Self-Defending KMS for TDE
4.1 Obtaining Access in Fortanix Self-Defending KMS
- Create an Account in Fortanix Self-Defending KMS if you do not have one already. See Getting Started for more information. Check with an administrator if you need access to an existing account.
- Create a new Group, if not already created by the account administrator. This group, say “Oracle TDE”, which maintains the master keys for the TDE setup.
4.2 Create an Application in Fortanix Self-Defending KMS for Oracle TDE
- In your Fortanix Self-Defending KMS account, go to the Applications
tab (Figure 1).
- Create a new Fortanix Self-Defending KMS app using the button
. For example: Oracle demo (Figure 1)
- The next steps showcase different ways of authenticating Oracle Database to Fortanix Self-Defending KMS.
Figure 1: Applications tab in Self-Defending KMS
4.3 Copy the API Key
- The API Key authenticates Oracle Database access to Fortanix Self-Defending KMS.
- In the Oracle demo app that you created in the previous section, click the COPY API KEY button (Figure 2).
Figure 2: Copy API key
- In the Copy the API key dialog, click COPY API KEY button to copy the key to the clipboard (Figure 3). This will be required in Oracle configuration steps in Section 5.0.
Figure 3: Copy API key to clipboard
4.4 Copy the App ID and Password
NOTE: This is only required for Auto-login mode of configuring TDE. Refer to the steps in Section 6.0.
- In the Oracle demo app that you created in the previous section, click the COPY API KEY button (See Figure 2 above).
-
In the Copy the API Key dialog, switch to the USERNAME/PASSWORD.
-
Copy the Password value and the Username (App UUID) value using the Copy
button.
Figure 4: Copy Password
- Both the App UUID and password will be required in steps mentioned in Section 6.0.
4.5 Setup Certificate-Based Authentication
- Fortanix Self-Defending KMS supports improved authentication using client-side TLS, instead of API Key. This approach reduces the need to share sensitive API Key to the Oracle DBA and performs two-way authentication of client and service.
- This requires creation of certificate at DBA side and whitelisting it in Fortanix Self-Defending KMS. Following are sample steps to generate self-signed certificates. You may want to contact your organization CA for the approved steps of generating certificates.
- Copy App UUID from Fortanix Self-Defending KMS UI. See the steps in Section 4.4. This is required to be as the Common Name value during certificate generation steps.
- Generate the Certificate Signing Request (CSR) to get the client certificate.
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields, but you can leave some blank. For some fields there will be a default value. If you enter '.', the field will be left blank. ----
Country Name (2 letter code) [XX]:. State or Province Name (full name) []:. Locality Name (eg, city) [Default City]:. Organization Name (eg, company) [Default Company Ltd]:. Organizational Unit Name (eg, section) []:. Common Name (eg, your name or your server's hostname) []:[]:<SDKMS_APP_UUID>
Email Address []:.
Please enter the following 'extra' attributes to be sent with your certificate request
A challenge password []:
An optional company name []: - Enter the Fortanix Self-Defending KMS App UUID that you copied in Step 3 in the Common Name field above.
- The certificate needs to be signed by your preferred CA provider. The signed certificate should be in PEM format.
- Now, whitelist the certificate in Fortanix Self-Defending KMS by changing the app authentication type to Certificate.
Figure 4: Change App Authenticate Type - Upload the client certificate using the UPLOAD NEW CERTIFICATE button or copy the content of the signed certificate as input in the text box below.
Figure 5: Add Signed Certificate
5.0 Setup TDE in Oracle using HSM Wallet
5.1 Set Hardware Keystore Type in the sqlnet.ora File
NOTE: This step only applies for Oracle 11g, 12c, and 18c. Skip to Section 5.2 for Oracle 19c.
To configure a keystore for a hardware security module (hardware keystore), you must first define the keystore in the sqlnet.ora. The Oracle Database checks the sqlnet.ora file for the type of keystore and the directory location of the hardware keystone. If not set, it assumes a software keystore by default.
- The sqlnet.ora file is located in the ORACLE_HOMEdbs directory or in the location set by the TNS_ADMIN environment variable. If the file is not present in the directory, create a new one.
- Add the following line to the sqlnet.ora file to define the hardware keystore type.
ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD=HSM))
5.2 Set Hardware Keystore Type (Oracle 19c Only)
- Oracle 19c does not require to edit sqlnet.ora file. The setup of keystore type can be done using Oracle initialization parameters.
- Set the Oracle wallet location. Even though HSM Wallet does not reside on local disk, this step is required to set TDE.
ALTER SYSTEM SET WALLET_ROOT="/opt/oracle/admin/ORCLCDB/wallet" scope=spfile;
- Shutdown the system.
SQL> shutdown
- Startup the system
SQL> startup
- Set the wallet type to HSM.
SQL> ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM" scope=both;
5.3 Install PKCS#11 Library
Oracle Database requires PKCS#11 protocol implemented library of the HSM. The next steps are to install the Fortanix Self-Defending KMS PKCS#11 library to the appropriate location to ensure that Oracle Database can find this library. To download the library, see the section Prerequisites.
- Before copying the PKCS#11 library, create the directory location where you will copy the library. Oracle recommends placing the PKCS#11library in a designated directory structure as /opt/oracle/extapi/{32,64}/hsm/<vendor_name>/<pkcs_lib_version >
sudo mkdir -p /opt/oracle/extapi/64/hsm/fortanix/3.16.1311
In the above specification:
- 64 specifies whether the supplied binary is 32 bits or 64 bits. This will be 64 usually.
- fortanix stands for the name of the vendor supplying the library.
- 3.16.1311 refers to the version of the library. This should preferably be in the format, number.number.number
- Now, copy the Fortanix Self-Defending KMS PKCS#11 library to the directory location created in Step 1.
/opt/oracle/extapi/64/hsm/fortanix/0.8.0/ fortanix_pkcs11_3.16.1311.so
- Change the name of the library file fortanix_pkcs11_3.16.1311.so to follow the syntax libapiname.so. So, the name of the library file should change to libpkcs11.so.
sudo mv
/opt/oracle/extapi/64/hsm/fortanix/3.16.1311/fortanix_pkcs11_3.16.1311.so
/opt/oracle/extapi/64/hsm/fortanix/3.16.1311/libpkcs11.sosudo chown -R oracle:oinstall /opt/oracle
sudo chmod -R 775 /opt/oracle
5.4 Configure PKCS#11 Parameters
- Fortanix Self-Defending KMS PKCS#11 library can be configured for authentication and other behaviors using a configuration file.
- We recommend using the default location for the configuration file, which is /etc/fortanix/pkcs11.conf.
sudo mkdir /etc/fortanix
sudo chown -R oracle:oinstall /etc/fortanix
sudo chmod -R 775 /etc/fortanix- If the requirement is to use a custom location, then set the environment variable FORTANIX_PKCS11_CONFIG_PATH for the path of the custom location. This can be useful in RAC setup, where single configuration file can be hosted on a shared ASM disk group. e.g:
export FORTANIX_PKCS11_CONFIG_PATH=/u01/app/oracle/fortanix/pkcs11.conf
- If the requirement is to use a custom location, then set the environment variable FORTANIX_PKCS11_CONFIG_PATH for the path of the custom location. This can be useful in RAC setup, where single configuration file can be hosted on a shared ASM disk group. e.g:
- Create a file named pkcs11.conf in the desired folder (see step 2 above).
- Add parameters in the file as follows:
- API Key: See Section 4.3 on how to get the API Key from Fortanix Self-Defending KMS.
NOTE : The Fortanix Self-Defending KMS App API Key size is 160+ characters long. Due to the SQL command size limitation, the long API Key will not fit in the command line. To solve this problem, you must store the API key in this config file and pass the path of this file in the wallet creation query in Section 5.7.
- API Endpoint: This is the URL endpoint of the Fortanix Self-Defending KMS installation.
- To prevent creating duplicate opaque objects, set prevent_duplicate_opaque_objects = true in the config file. This would skip creating new Opaque objects if there is an existing Opaque object with the same CKA_LABEL. This is recommended.
- Optionally, a log file location can be set. By default, logging is done in /var/log/syslog.
- Optionally, a retry timeout can be set in milliseconds, which allows for retries in case of failures from service side. By default, this is set for 3 seconds.
api_endpoint = "https://sdkms.fortanix.com"
api_key = "MWY5YT...TO5n"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
[log]
file = "<log filename>"
- API Key: See Section 4.3 on how to get the API Key from Fortanix Self-Defending KMS.
5.5 Configure CA Certificate
If Fortanix Self-Defending KMS is installed in an on-premise environment, the CA certificate used for HTTPS endpoint need to be provided in PKCS#11 configuration. If not set, the TLS communication to Fortanix Self-Defending KMS will not be successful.
- Download the CA certificate as a PEM file on the Oracle Database machine. File name can be syslogsdkms-ca.crt.
- Make sure the full certificate chain is part of the file.
- Add the location of CA file in PKCS#11 conf file as following:
api_endpoint = "https://sdkms.fortanix.com"
api_key = "MWY5YT...TO5n"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
ca_certs_file = "/path/to/sdkms-ca.pem"
[log]
file = "<log filename>"
5.6 Configure for Client Certificate Authentication
Alternatively, client certificate-based authentication can be set, instead of API Key based authentication. It brings stronger security as sensitive credential like API Key need not be shared to the DBA directly.
See the steps in Section 4.5 on how to create a client-side certificate and whitelist with Fortanix Self-Defending KMS.
Once the above steps are done, the following is required:
- the location of client key
- the location of the client certificate
- App UUID
api_endpoint = "https://sdkms.fortanix.com"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
ca_certs_file = "/path/to/sdkms-ca.pem"
app_id = "<SDKMS_APP_UUID>"
key_file = "/path/to/client-key.pem"
cert_file = "/path/to/client-cert.pem"
[log]
file = "<log filename>"NOTE : api_key is removed from the config file.
5.7 Setup Keystore and Master Key (for Oracle 11g only)
Log in with User sys with role sysdba.
Sqlplus / as sysdba
NOTE: If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora file changes can take effect.
5.7.1 Open Keystore
To open the hardware key store, run the following command:
ALTER SYSTEM SET ENCRYPTION WALLET OPEN IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf";
In the above specification,
- IDENTIFIED BY points to the location of the PKCS#11 configuration file prefixed with file:// (Based on step 2 of Section 5.4).
NOTE: Above command is required to open the keystore for use by database, on every start of the database.
5.7.2 Set TDE Master Encryption key
Next you must create a TDE master encryption key that is stored inside the Fortanix hardware keystore. Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys or tablespace encryption keys inside the hardware security module
- Run the following command:
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf";
The above command sets the Oracle database for TDE. Open the Fortanix Self-Defending KMS Web UI and go to the audit log to confirm if the master key was generated and used.
- Click the Settings
tab , and then in the left panel click the LOG MANAGEMENT tab to see the audit logs.
Figure 6: Audit Logs
The Fortanix Self-Defending KMS is now successfully integrated with the Oracle TDE.
From here you can proceed to:- Start encrypting data.
- Improving the setup with Auto login. This allows to auto open the keystore on database restarts.
5.8 Setup Keystore and Master Key for Oracle 12c, 18c, and 19c
Log in with User sys with role sysdba.
Sqlplus / as sysdba
NOTE: If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora file changes can take effect.
Switch to root container (if it is a container database). The keystore needs to be opened in the root container first. Run the following command in SQL*Plus:
ALTER SESSION SET CONTAINER = CDB$ROOT;
5.8.1 Open Keystore
To open the hardware key store, run the following command:
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
In the above specification,
- IDENTIFIED BY points to the location of the PKCS#11 Configuration file (prefixed
- with file:// (Based on step 2 of Section 5.4).
- CONTAINER is for use in a multitenant environment. Enter ALL to set the keystore in all the pluggable databases (PDBs) in this container database (CDB), or CURRENT for the current PDB.
NOTE: Above command is required to open the keystore for use by database, on every start of the database.
5.8.2 Set TDE Master Encryption key
Next you must create a TDE master encryption key that is stored inside the Fortanix hardware keystore. Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys or tablespace encryption keys inside the hardware security module
- Run the following command:
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
The above command sets the Oracle database for TDE. Open the Fortanix Self-Defending KMS Web UI and go to the audit log to confirm if the master key was generated and used.
- Click the Settings
tab , and then in the left panel click the LOG MANAGEMENT tab to see the audit logs.
Figure 7: Audit Logs
The Fortanix Self-Defending KMS is now successfully integrated with the Oracle TDE.
From here you can proceed to:- Start encrypting data.
- Improving the setup with Auto login. This allows to auto open the keystore on database restarts.
6.0 Encrypt Your Data
Once TDE is setup on the Oracle Database, we can proceed with data encryption. There are 2 ways of encrypting data:
- Column Encryption: Selected columns of a table to be encrypted.
- Tablespace Encryption: Encrypt entire tablespace using TDE. This is recommended by Oracle due to better performance.
6.1 Column Encryption
- Connect to SQL*plus as a non-sysadmin user to enable encryption on a table.
- Next, create a table with an encrypted column. Use the CREATE TABLE SQL statement with the ENCRYPT clause.
CREATE TABLE employee (first_name VARCHAR2(128), last_name VARCHAR2(128), empID NUMBER, salary NUMBER(6) ENCRYPT)
- Now insert some data into the table.
INSERT INTO employee VALUES ('JOHN', 'SMITH',001, 10000);
- To list the encrypted columns in your database, run the following command:
select * from dba_encrypted_columns;
OWNER TABLE_NAME COLUMN_NAME ENCRYPTION_ALG SALT INTEGRITY_ALG
------- ---------- ----------- -------------- ---- -------------
OE EMPLOYEE SALARY AES 192 bits key YES SHA-1
More details can be found here https://docs.oracle.com/database/121/TDPSG/GUID-61259237-5514-4531-AFB4-CF716F93F1E5.htm#TDPSG44324
6.2 Tablespace Encryption
- Connect to SQL*plus as a non-sysadmin user to create a new encrypted tablespace.
NOTE: Oracle Database does not support encrypting existing tablespace. See notes here https://docs.oracle.com/database/121/TDPSG/GUID-61259237-5514-4531-AFB4-CF716F93F1E5.htm#GUID-956B2FB6-345B-4402-8D13-ED48D6357438
- Make sure that COMPATIBLE Initialization parameter setting is 11.2.0.0 or higher. This is typically an issue with older 11g databases.
SHOW PARAMETER COMPATIBLE
NAME TYPE VALUE
compatible string 11.2.0.0
noncdbcompatible BOOLEAN FALSE
// If above is less than 11.2.0.0, then run following
alter system set COMPATIBLE='11.2.0.0' scope=spfile;
shutdown
startup - Create a new encrypted tablespace using CREATE TABLESPACE SQL statement with the ENCRYPT clause.
CREATE TABLESPACE encrypted_ts (
DATAFILE '/u01/app/oracle/oradata/DB11G/encrypted_ts01.dbf' SIZE 128K
AUTOEXTEND ON NEXT 64K
ENCRYPTION USING 'AES256'
DEFAULT STORAGE(ENCRYPT);
ALTER USER test QUOTA UNLIMITED ON encrypted_ts; - Now insert some data into the table or tablespace.
CREATE TABLE ets_test (
id NUMBER(10),
data VARCHAR2(50)
)
TABLESPACE encrypted_ts;
INSERT INTO ets_test (id, data) VALUES (1, 'This is a secret!');
COMMIT; - The ENCRYPTED column of the DBA_TABLESPACES and USER_TABLESPACES views indicates if the tablespace is encrypted or not.
SELECT tablespace_name, encrypted FROM dba_tablespaces;
TABLESPACE NAME ENC
____________________________________________________________________
SYSTEM NO
SYSAUX NO
ENCRYPTED_TS YES
3 rows selected
7.0 Configuring Auto-Login
The method described in "Section 5.0" requires saving the Fortanix Self-Defending KMS API key in a config file. If you do not want to expose the API key in a file, you can configure the HSM key store to use auto-login using App ID and Password. The advantages would be:
- The API Key is not exposed to the database machine.
- In the case of database restart, the wallet is opened automatically.
In this method we will store the Fortanix Self-Defending KMS App’s secret/password in an auto-login keystore using a software keystore and the App Id (App UUID) will be stored in a config file. The Oracle TDE will pass the app secret stored in auto-login keystore as PIN to Fortanix Self-Defending KMS PKCS11 library. Fortanix Self-Defending KMS PKCS11 library will use this PIN and combine with App Id in the config file to create the basic authentication token for authenticating to Fortanix Self-Defending KMS.
For additional details on Oracle TDE and auto-login keystore, please see: https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#ASOAG10434
7.1 Auto Login in Oracle 11G
NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.
- Close the HSM keystore if it is open.
ALTER SYSTEM SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
- Create a new entry in sqlnet.ora file (Replace the existing WALLET setting).
ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD = HSM) (METHOD_DATA = (DIRECTORY = <wallet absolute Path>)))
- Create an auto-open and encryption wallet in the directory mentioned above:
orapki wallet create -wallet . -auto_login -pwd <password>
orapki wallet create -wallet . -auto_login -pwd password123
NOTE: When prompted for a password, provide a password of at least 8 characters. This will be your software wallet password. Remember it for future use.
- Add the following entry to the empty wallets to enable an ‘auto-open HSM’:
mkstore -wrl . -createEntry ORACLE.TDE.HSM.AUTOLOGIN <any-non-empty-string>
- <any-non-empty-string> could be any string and it is used only one time. For example:
mkstore -wrl . -createEntry ORACLE.TDE.HSM.AUTOLOGIN TESTDE
- Oracle opens the encryption wallet first and if not present then it will open the auto wallet. Rename the encryption wallet (ewallet.p12) or move it out of the ‘ENCRYPTION_WALLET_LOCATION’ defined in the ‘sqlnet.ora’ file to a secure location;
mv ewallet.p12 ewallet.p12.orig
- <any-non-empty-string> could be any string and it is used only one time. For example:
- Edit the existing PKCS#11 config file:
- Remove API Key if exists in the file.
- Add App Id. This value can be fetched from Section 4.4.
api_endpoint = "https://sdkms.fortanix.com"
app_id = "<App UUID>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
[log]
file = "<log filename>"NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert_file, key_file, etc. This means the configuration is applicable for certificate-based authenticate mode too.
- Create a TDE master encryption key inside the HSM using App password. The password can be fetched as per Section 4.4.
alter system set encryption key identified by " <SDKMS_APP_PASSWORD>";
NOTE: If certificate-based authentication is set (See Section 4.5), then password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password.
alter system set encryption key identified by "file:///etc/fortanix/pkcs11.conf";
- Run the following command to check the wallet open status.
SELECT * FROM V$ENCRYPTION_WALLET;
- Shutdown the database immediately.
- Startup the database.
- Run the following command to verify that the wallet is auto-open.
SELECT * FROM V$ENCRYPTION_WALLET;
This completes the auto-login steps for Oracle 11g.
7.2 Auto-Login in Oracle 12c and 18c
NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.
- Check if HSM key store is open. You can check the status of whether a keystore is open or closed by querying the STATUS column of the V$ENCRYPTION_WALLET view.
Select * from V$ENCRYPTION_WALLET
- Close the HSM keystore if it is open.
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
- Create directory for software wallet.
mkdir /opt/oracle/admin/ORCLCDB/wallet/Fortanix
- Now create a software keystore. This keystore will store the password to the HSM wallet for the purpose of auto-login. Make sure you use “<SDKMS_APP_PASSWORD>” as the wallet password in this step.
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE "/opt/oracle/admin/ORCLCDB/wallet/Fortanix" IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
NOTE:
- Provide a password of at least 8 characters above. This will be your software wallet password. Remember it for future use.
- From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For 12.2 database and above, it is also required to keep the wallet password the same as “<SDKMS_APP_PASSWORD>”.
- Reconfigure the sqlnet.ora file and add the keystore location of the software keystore created in Step 3 to the DIRECTORY setting of the ENCRYPTION_WALLET_LOCATION setting. For example:
ENCRYPTION_WALLET_LOCATION= (SOURCE=(METHOD=FILE)(METHOD_DATA= (DIRECTORY=/home/oracle/WALLETS/Fortanix)))
- Reconnect to the database, or log out and then log back in again, so that the change that you made in the previous step takes effect.
- Open the software keystore.
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
- Add Fortanix Self-Defending KMS App password as a secret in the software wallet using the client as HSM_PASSWORD. This is an Oracle defined client name that is used to represent the HSM password as a secret in the software keystore. The app password can be fetched as per Section 4.4.
ADMINISTER KEY MANAGEMENT ADD SECRET '<SDKMS_APP_PASSWORD>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY “<SDKMS_APP_PASSWORD>” WITH BACKUP;
NOTE: If certificate-based authentication is set (See Section 4.5), then the password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password.
ADMINISTER KEY MANAGEMENT ADD SECRET 'file:///etc/fortanix/pkcs11.conf' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY password WITH BACKUP;
- Edit the existing PKCS#11 config file:
- Remove API Key if it exists in the file.
- Add App Id. This value can be fetched from Section 4.4.
The updated contents of pkcs11.conf is:api_endpoint = "https://sdkms.fortanix.com"# app_id = "<App UUID>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000 [log] file = "<log filename>"
NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert_file, key_file, etc. This means the configuration is applicable for certificate-based authenticate mode too.
- Close the software keystore.
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
- Now create the auto-login keystore.
ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/Fortanix' IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
- Update the sqlnet.ora file to use the hardware security module location. Comment the previously configured wallet location (adjust DIRECTORY to the path where your wallet is stored).
ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/ORCLCDB/wallet/Fortanix)))
- Shutdown and restart the database for changes to pick up.
- Run the following command to verify that the wallet is auto-open.
SELECT * FROM V$ENCRYPTION_WALLET;
7.3 Auto-Login in Oracle 19c
NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.
- Check if HSM key store is open. You can check the status of whether a keystore is open or closed by querying the STATUS column of the V$ENCRYPTION_WALLET view.
Select * from V$ENCRYPTION_WALLET
- Close the HSM keystore if it is open.
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
- Create directory for software wallet.
mkdir /opt/oracle/admin/ORCLCDB/wallet/Fortanix
- Change the keystore type to software wallet.
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE"
- Create a software keystore. This keystore will store the password to the HSM wallet for the purpose of auto-login.
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/tde' IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
NOTE:
- Provide a password of at least 8 characters above. This will be your software wallet password. Remember it for future use.
- From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For 12.2 database and above, it is also required to keep the wallet password the same as “<SDKMS_APP_PASSWORD>”.
- Open the software keystore.
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
- Add Fortanix Self-Defending KMS App password as a secret in the software wallet using the client as HSM_PASSWORD. HSM_PASSWORD. This is an Oracle defined client name that is used to represent the HSM password as a secret in the software keystore. The app password can be fetched as per Section 4.4.
ADMINISTER KEY MANAGEMENT ADD SECRET '<SDKMS_APP_PASSWORD>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY “<SDKMS_APP_PASSWORD>” WITH BACKUP;
NOTE: If certificate-based authentication is set (See Section 4.5), then the password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password.
ADMINISTER KEY MANAGEMENT ADD SECRET 'file:///etc/fortanix/pkcs11.conf' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY password WITH BACKUP;
- Edit the existing PKCS#11 file:
- Remove API Key if exists in the file.
- Add App Id. This value can be fetched from Section 4.4.
The updated contents of pkcs11.conf is:
api_endpoint = "https://sdkms.fortanix.com"
app_id = "<App UUID>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
[log]
file = "<log filename>"NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert, key, etc. This means the configuration is applicable for certificate-based authenticate mode too.
- Close the software keystore.
ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
- Now create the auto-login keystore.
ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/tde IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
- Set the wallet location to HSM backed by auto-login.
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE"
- Shutdown and restart the database for changes to pick up.
- Run the following command to verify that the wallet is auto-open.
SELECT * FROM V$ENCRYPTION_WALLET;
8.0 Oracle RAC Setup
Oracle RAC (Real Application Cluster) is a cluster database with a shared cache architecture that overcomes the limitations of traditional shared-nothing and shared-disk approaches to provide highly scalable and available database solutions for enterprises. Oracle RAC is a key component of Oracle's private cloud architecture.
For Oracle RAC Cluster setup, you can perform both direct hsm or auto-login hsm procedures mentioned in Section 5.0 and Section 7.0 for Fortanix Self-Defending KMS integration. You will need to additionally make sure of the following:
- The PKCS11 config file should be:
- Either at a central location /etc/fortanix/pkcs11.conf
- Or at a location pointed by env variable FORTANIX_PKCS11_CONFIG_PATH see Step 2 of Section 5.4 for more details.
- The PKCS11 library that you will use should be version 3.3 and above. The latest library can be downloaded from the URL:
https://support.fortanix.com/hc/en-us/articles/360018312391-PKCS-11 - For autologin setup in Oracle 11g, the software wallet creation steps (Section 7.1, Step 3, and 4) can be skipped for the rest of the nodes.
- Complete the software keystore creation steps on node 1.
- Copy the software wallet files in the directory to the same location on other nodes (the .sso .p12 files)
- Rest steps remain the same on other nodes.
- For any other Oracle database version and integration type (auto-login etc.), all integration steps need to be executed on all the nodes in RAC cluster.
9.0 Master Key Rotation
Oracle database supports rotation of The TDE Master Key in Fortanix Self-Defending KMS.
- Key Rotation activity is driven by Oracle database, and not to be performed at Fortanix Self-Defending KMS directly. Thus, this requires the involvement of DBA.
- The Key rotation cannot be performed in Auto-login mode prior to Oracle database 12.2 versions.
- From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For example:
ADMINISTER KEY MANAGEMENT SET KEY FORCE KEYSTORE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
On Key rotation, Oracle database re-encrypts the existing Data Encryption Keys, with the new rotated key.
- For Oracle 11g, the key rotation command is 5.7.2
- For Oracle 12c, 18c and 19c, the key rotation command is 5.8.2
Its recommended to not delete the older master keys in Fortanix Self-Defending KMS. Oracle database will require the other keys in case of restore of older backups of the database.
10.0 Perform the Hardware Keystore Migration
You now have the configuration file for PKCS11 library, containing the app_id , Oracle master key, and the Fortanix Self-Defending KMS application secret stored in Wallet.
You can use the ADMINISTER KEY MANAGEMENT SQL statement to perform a hardware keystore migration.
To migrate from the software keystore to hardware keystore, you must use the MIGRATE USING keystore_password clause in the ADMINISTER KEY MANAGEMENT SET KEY SQL statement to decrypt the existing TDE table keys and the tablespace encryption keys with the TDE master encryption key in the software keystore and then re-encrypt them with the newly created TDE master encryption key in the hardware keystore.
After you complete the migration, you do not need to restart the database, nor do you need to manually re-open the hardware keystore. The migration process automatically reloads the keystore keys in memory.
To perform the hardware keystore migration, follow the steps mentioned in the previous section (Section 7.0) before executing the below procedure.
- Use the following syntax when you run the ADMINISTER KEY MANAGEMENT SQL statement for migration.
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "app_secret_value" MIGRATE USING software_keystore_password [WITH BACKUP [USING 'backup_identifier']];
NOTE: Here we need to use the App_secret that you set as HSM_PASSWORD after "IDENTIFIED BY", and then after MIGRATE USING you must use the software wallet password. For example, run the command as follows:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "V5iFE8LjFGk_p-pmhl74GVlqsp9JrdQ8fNEKeOY5VJ9XUibj18Ci9sLYCvIGY6og_Ql2sHSveoKi3WTHvvJ38w" MIGRATE USING password;
- You will receive the message “keystore altered”.
- Check if the appropriate keystores are opened, and contain the master key using the below command.
SELECT * FROM V$ENCRYPTION_WALLET;
11.0 Modify HSM Heartbeat Check Interval
NOTE: This section does not apply to Oracle 11G.
Oracle performs continuous HSM heartbeat checks by performing crypto operation with a key stored in HSM.
The default interval at which Oracle sends HSM Heartbeat check is 3 seconds. Fortanix recommends modifying this interval to a larger interval, as follows:
ALTER SYSTEM SET "_heartbeat_period_multiplier"= xx SCOPE=SPFILE;
ALTER SYSTEM SET "_heartbeat_config"=AUTOCONNECT SCOPE=SPFILE;
Where xx is used in the following way to determine the heartbeat interval:
xx + 3 (initial seconds) = yyy seconds.
For example, if you want to set the heartbeat interval to
- 2 minutes (120 seconds), the xx value will be 39.
39x3 + 3 (initial seconds) = 120 seconds. - 1 hour (3600 seconds), the xx value will be 1199. (This is recommended value by Fortanix). 1199x3 + 3 (initial seconds) = 3600 seconds.
12.0 Troubleshooting
The following table describes the possible reasons for errors and exceptions and provides information about resolving them.
PROBLEM |
RESOLUTION |
---|---|
Issues while opening the HSM wallet |
Ensure the following to troubleshoot:
|
Failing to open HSM wallet (ORA-28353) |
Look at PKCS11 log file to check if C_Login is failing. A failing entry for C_Login will have non-zero status as follows: 2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160 |
C_Login Failure |
Verify the following information is correct:
|
Encrypted Tablespace creation Failure |
In Oracle database 11g installation which have been upgraded from older version, the parameter COMPATIBLE needs to be set to increased to enable tablespace encryption. Run following command and restart database: |
HSM heartbeat Failure error |
Look at the PKCS11 log file to find which PKCS11 function is failing. Oracle performs continuous HSM heartbeat checks by performing crypto operation with a key stored in HSM. To troubleshoot heartbeat check failure, please check the following:
|
PKCS library fails to open the PKCS11 configuration file and uses default configuration. oracle[14045]: could not read config file /root/.config/fortanix/pkcs11.conf, using default configuration... |
Look for the PKCS11 errors in the log file, for example:
|
API failures from the PKCS#11 service |
Configure the error retry limit by setting retry_timeout_millis = xxxx in the config file. Where xxxx is the value of time in milliseconds. This is the maximum duration for which the PKCS#11 library will do any number of retries in case of API failures. For example, retry_timeout_millis = 6000 sets the retry limit to 6 secs. The default value is 3000, which is 3 secs. |
Orcale DB crashes |
Check if app is disabled in Fortanix Self-Defending KMS. |
Network connection lost between Oracle and Fortanix Self-Defending KMS |
Check firewall rules and IP table rules. |
NOTE: It is recommended that you configure your PKCS11 config file to store PKCS11 logs in a separate file. During TDE configuration or operation, if you get an error, please send the PKCS11 log file to Fortanix support team to troubleshoot the issue. Contents of PKCS11 log file will appear as follows:
2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160
2019-06-13T01:31:36.722161947-04:00 - Fortanix C_CloseSession -> 0
2019-06-13T01:31:36.722188512-04:00 - Fortanix C_Finalize -> 0
12.1 Rollback and Recovery
- In case of encrypting wrong column (using alter table), one can remove encryption by adding decrypt attribute to the column, see the URL for more details: http://www.dba-oracle.com/t_adv_plsql_tde_column_encryption.htm
- Encrypted columns or tablespace cannot be retrieved if the master key is deleted from Fortanix. Hence it is suggested to add policy in Fortanix of not deleting a key without permission (quorum approval policy at group level)
- Oracle strongly recommends that you do not delete keystores, particularly after you have configured Transparent Data Encryption and the keystore is in use. See the URL for more details: https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption- key.htm#ASOAG10407
13.0 References
- Introduction to Transparent Data Encryption
https://docs.oracle.com/en/database/oracle/oracle-database/12.2/asoag/introduction-to-transparent-data-encryption.html - Fortanix Self-Defending KMS Getting started
https://support.fortanix.com/hc/en-us/articles/360015809372-Getting-Started-with-SDKMS - Oracle TDE and auto-login keystore
https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#ASOAG10434