Oracle TDE
Appropriate Vault Enterprise license required
Oracle Transparent Data Encryption (TDE) is supported with the Vault PKCS#11 provider. In this setup, Vault's KMIP engine generates and store the "TDE Master Encryption Key" that the Oracle Database uses to encrypt and decrypt the "TDE Table Keys". Oracle will not have access to the TDE Master Encryption Key itself.
Requirements
To setup Oracle TDE backed by Vault, the following are required:
- A database running Oracle 19c Enterprise Edition
- A Vault Enterprise 1.11+ server with Advanced Data Protection for KMIP support.
- Vault has TCP port 5696 accessible to the Oracle database.
libvault-pkcs11.so
downloaded from releases.hashicorp.com for the operating system running the Oracle database.
Vault setup
On the Vault server, we need to setup the KMIP Secrets Engine:
Start the KMIP Secrets Engine and listener:
Important: When configuring KMIP for Oracle, you will probably need to set the
server_hostnames
andserver_ips
configuration parameters, otherwise the TLS connection to the KMIP Secrets Engine will fail due to certification validation errors. When configuring Oracle TDE, this error can manifest as thesqlplus
session silently hanging.Create a KMIP scope to contain the TDE keys and objects. The KMIP scope is essentially an isolated namespace. For example, you can create a scope called
my-service
:Create a KMIP role that has access to the scope:
Create TLS credentials (a certificate, key, and CA bundle) for the KMIP role:
Note: This command will output the credentials in plaintext.
The response from the
credential/generate
endpoint is JSON. The.data.certificate
entry contains a bundle of the TLS client key and certificate we will use to connect to KMIP with from Oracle. The.data.ca_chain[]
entries contain the CA bundle to verify the KMIP server's certificate. Save these to, e.g.,cert.pem
andca.pem
:
Oracle TDE preparation
The rest of the steps take place on the Oracle server.
We need to configure the Vault PKCS#11 provider.
Copy the
libvault-pkcs11.so
binary into$ORACLE_BASE/extapi/64/hsm
, and ensure there are no other PKCS#11 libraries in$ORACLE_BASE/extapi/64/hsm
.Copy the TLS certificate and key bundle (e.g.,
/etc/cert.pem
) and CA bundle (e.g.,/etc/ca.pem
) for the KMIP role (configured as above) to the Oracle server. The exact location does not matter as long as the Oracle process has access to it.Create a configuration file, for example
/etc/vault-pkcs11.hcl
, with the following contents:This file is used by
libvault-pkcs11.so
to know how to find and communicate with the KMIP engine in Vault.In particular:
- The
slot
block configures the first PKCS#11 slot to point to Vault. Oracle will use this first slot. server
should point to the Vault server's IP (or DNS name) and port number (5696 is the default).tls_cert_path
should be the location on the Oracle database of the client TLS certificate and key bundle used to connect to Vault server.ca_path
should be the location of the CA bundle on the Oracle database.scope
is the KMIP scope to authenticate against and where the TDE master keys and associated metadata will be stored.
The default location the PKCS#11 library will look for the configuration file is the current directory (
./vault-pkcs11.hcl
) and/etc/vault-pkcs11.hcl
, but you can override this by setting theVAULT_KMIP_CONFIG
environment variable to any file.- The
If you want to view the Vault logs (helpful when trying to find error messages), you can specify the
VAULT_LOG_FILE
(default is stdout) andVAULT_LOG_LEVEL
(default isINFO
). We'd recommend settingVAULT_LOG_FILE
to something like/tmp/vault.log
or/var/log/vault.log
. Other useful log levels areWARN
(quieter) andTRACE
(verbose, could possibly contain sensitive information, like raw network packets).
Enable TDE
The only remaining step is to setup Oracle TDE for an external HSM using shared library, libvault-pkcs11.so
.
These steps are not specific to Vault, other than requiring the shared library, HCL configuration, and certificates be present.
TDE is complex, but an example way to enable it is:
Open a
sqlplus
session into the root container (or switch into it withALTER SESSION SET CONTAINER = CDB$ROOT;
).Set WALLET_ROOT and TDE_CONFIGURATION parameters on the Oracle database. The wallet root directory is only used to set the TDE configuration parameter. To learn more about the wallet parameters refer to the Oracle TDE documentation.
Validate the parameters are set by querying
V$PARAMETER
Open the HSM wallet:
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "1234" CONTAINER = ALL;
. The password1234
here is used as the password for decrypting the TLS key, if it is stored encrypted on disk. If the TLS key is not encrypted, this password is ignored.Create the TDE master key:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY USING TAG 'default' IDENTIFIED BY "1234" CONTAINER = ALL;
, again specifying the TLS key password if necessary.Finally, use TDE in a PDB, e.g.,
CREATE TABLE test_tde (something CHAR(32) ENCRYPT);
.
More extensive information on the details and procedures for Oracle TDE can be found in Oracle's documentation.