cbdbad0629
AWS announced [KMS External Key Store](https://aws.amazon.com/blogs/aws/announcing-aws-kms-external-key-store-xks/), which we support using their reference [`xks-proxy`](https://github.com/aws-samples/aws-kms-xks-proxy) software. This adds a documentation page showing how to configure KMIP and the PKCS#11 provider to to work with KMS and `xks-proxy`. Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
131 lines
6.5 KiB
Plaintext
131 lines
6.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Oracle TDE - PKCS#11 Provider - Vault Enterprise
|
|
description: |-
|
|
The Vault PKCS#11 Provider can be used to enable Oracle TDE.
|
|
---
|
|
|
|
# Oracle TDE
|
|
|
|
[Oracle Transparent Data Encryption](https://docs.oracle.com/database/121/ASOAG/introduction-to-transparent-data-encryption.htm#ASOAG10270) (TDE)
|
|
is supported with the [Vault PKCS#11 provider](/docs/enterprise/pkcs11-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 19 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](https://releases.hashicorp.com/vault-pkcs11-provider) for the operating system running the Oracle database (the RHEL 7 x86-64 version for Oracle Enterprise Linux 7).
|
|
|
|
## Vault Setup
|
|
|
|
On the Vault server, we need to [setup the KMIP Secrets Engine](/docs/secrets/kmip):
|
|
|
|
1. Start the KMIP Secrets Engine and listener:
|
|
|
|
```sh
|
|
vault secrets enable kmip
|
|
vault write kmip/config listen_addrs=0.0.0.0:5696
|
|
```
|
|
|
|
~> **Important**: When configuring KMIP for Oracle, you will probably need to set the
|
|
`server_hostnames` and `server_ips` [configuration parameters](/api-docs/secret/kmip#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 the `sqlplus` session silently hanging.
|
|
|
|
1. 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`:
|
|
|
|
```sh
|
|
vault write -f kmip/scope/my-service
|
|
```
|
|
|
|
1. Create a KMIP role that has access to the scope:
|
|
|
|
```sh
|
|
vault write kmip/scope/my-service/role/admin operation_all=true
|
|
```
|
|
|
|
1. Create TLS credentials (a certificate, key, and CA bundle) for the KMIP role:
|
|
|
|
~> **Note**: This command will output the credentials in plaintext.
|
|
|
|
```sh
|
|
vault write -f -format=json kmip/scope/my-service/role/admin/credential/generate | tee kmip.json
|
|
```
|
|
|
|
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` and `ca.pem`:
|
|
|
|
```sh
|
|
jq --raw-output --exit-status '.data.ca_chain[]' kmip.json > ca.pem
|
|
jq --raw-output --exit-status '.data.certificate' kmip.json > cert.pem
|
|
```
|
|
|
|
## Oracle TDE Preparation
|
|
|
|
The rest of the steps take place on the Oracle server.
|
|
|
|
We need to configure the Vault PKCS#11 provider.
|
|
|
|
1. Copy the `libvault-pkcs11.so` binary into `$ORACLE_BASE/extapi/64/hsm/vault/0.0.1/`, and ensure there are no other PKCS#11 libraries in `$ORACLE_BASE/extapi/64/hsm`.
|
|
|
|
1. 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.
|
|
|
|
1. Create a configuration file, for example `/etc/vault-pkcs11.hcl`, with the following contents:
|
|
|
|
```hcl
|
|
slot {
|
|
server = "VAULT_ADDRESS:5696"
|
|
tls_cert_path = "/etc/cert.pem"
|
|
ca_path = "/etc/ca.pem"
|
|
scope = "my-service"
|
|
}
|
|
```
|
|
|
|
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 the `VAULT_KMIP_CONFIG` environment variable to any file.
|
|
|
|
1. 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) and `VAULT_LOG_LEVEL` (default is `INFO`). We'd recommend setting `VAULT_LOG_FILE` to something like `/tmp/vault.log` or `/var/log/vault.log`. Other useful log levels are `WARN` (quieter) and `TRACE` (very 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:
|
|
|
|
1. Create or update the `sqlnet.ora` (usually in `$ORACLE_BASE/oradata/dbconfig/$SID/sqlnet.ora`) configuration file to use an HSM encryption wallet by adding the following line:
|
|
|
|
```
|
|
encryption_wallet_location=(source=(method=hsm))
|
|
```
|
|
|
|
1. Restart the Oracle database so that it picks up the `sqlnet.ora` changes.
|
|
|
|
1. Open a `sqlplus` session into the root container (or switch into it with `ALTER SESSION SET CONTAINER = CDB$ROOT;`)
|
|
|
|
1. Open the HSM wallet: `ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "1234" CONTAINER = ALL;`.
|
|
The password `1234` here is used as the password for decyrpting the TLS key, if it is stored encrypted on disk.
|
|
If the TLS key is not encrypted, this password is ignored.
|
|
|
|
1. 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.
|
|
|
|
1. 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](https://docs.oracle.com/database/121/ASOAG/asopart1.htm#ASOAG600). |