diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/keyring.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/keyring.md index 82829aefd1d12..fe35ba81e15d0 100644 --- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/keyring.md +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/keyring.md @@ -21,6 +21,10 @@ SELECT pg_tde_add_global_key_provider_file( ); ``` +For more information on related functions, see the link below: + +[Percona pg_tde Function Reference](../functions.md){.md-button} + ## Next steps [Global Principal Key Configuration :material-arrow-right:](set-principal-key.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-fortanix.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-fortanix.md index edc09daf51af8..2ab6b9a1711cd 100644 --- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-fortanix.md +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-fortanix.md @@ -3,3 +3,11 @@ `pg_tde` is compatible with Fortanix Data Security Manager (DSM) via the KMIP protocol. For a full setup guide, see [the Fortanix KMIP documentation here](https://support.fortanix.com/docs/users-guide-account-client-configurations?highlight=KMIP#23-kmip-clients). For more information on adding or modifying the provider, see the [Adding or modifying KMIP providers](https://docs.percona.com/pg-tde/functions.html?h=pg_tde_add_global_key_provider_kmip#adding-or-modifying-kmip-providers) topic. + +For more information on related functions, see the link below: + +[Percona pg_tde Function Reference](../functions.md){.md-button} + +## Next steps + +[Global Principal Key Configuration :material-arrow-right:](set-principal-key.md){.md-button} \ No newline at end of file diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-openbao.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-openbao.md new file mode 100644 index 0000000000000..ebf644654e1f7 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-openbao.md @@ -0,0 +1,237 @@ +# Using OpenBao as a KMIP-Compatible Key Provider + +`pg_tde` is compatible with OpenBao via the KMIP protocol. For a full setup guide, see [the OpenBao documentation here](https://openbao.org/docs/install/). + +To see an example configuration and installation of OpenBao on Ubuntu 24.04 for `pg_tde`, see [Install OpenBao on Ubuntu](#install-openbao-on-ubuntu). + +## Install OpenBao on Ubuntu + +The following steps allow you to install the OpenBao solution on Ubuntu with Percona's Server for PostgreSQL 17. + +### Prerequisites + +You need to ensure you meet the following: + +- OS: Ubuntu 24.04 +- `pg_tde` and Percona Server for PostgreSQL 17 installed + +### Step 1. Install OpenBao + +- Start by installing the latest version of OpenBao, run: + + ```bash + # as root + wget https://github.com/openbao/openbao/releases/download/v2.2.1/bao_2.2.1_linux_amd64.deb + dpkg -i ./bao_2.2.1_linux_amd64.deb + ``` + + !!! note + This guide uses OpenBao version 2.2.1. You can replace it with the latest version. + +- You can check the version by running: + + ```bash + bao --version + ``` + +### Step 2. Basic setup and configuration for OpenBao + +- Move the original OpenBao configuration and create a new one, run: + + ```bash + cp /etc/openbao/openbao.hcl /etc/openbao/openbao.hcl_DEPRECATED + ``` + +- Create a new configuration file: + + ```bash + echo ' + ui = true + + storage "file" { + path = "/opt/openbao/data" + } + + listener "tcp" { + address = "0.0.0.0:8200" + tls_disable = 1 + } + ' > /etc/openbao/openbao.hcl + ``` + +- Set the correct permissions: + + ```bash + chown openbao:openbao /etc/openbao/openbao.hcl + ``` + +### Step 3. Start OpenBao + +- To start your configuration, run: + + ```bash + sudo systemctl enable --now openbao + ``` + +- Check OpenBao's status to see if it is running: + + ```bash + systemctl status openbao + ``` + + You should see output similar to the following: + +
+ Example output (click to expand) + + ● openbao.service - "OpenBao - A tool for managing secrets" + Loaded: loaded (/usr/lib/systemd/system/openbao.service) + Active: active (running) + Docs: https://github.com/openbao/openbao/tree/main/website/content/docs + ... + CGroup: /system.slice/openbao.service + └─1061 /usr/bin/bao server --config=/etc/openbao/openbao.hcl +
+ +### Step 4. Initialize OpenBao + +Once OpenBao is running, you must initialize the system. This generates the unseal key and the initial root token, which are required to manage the server. + +- Set the `VAULT_ADDR` environment variable to point to your OpenBao listener: + + ```bash + export VAULT_ADDR="http://127.0.0.1:8200" + ``` + +- Run the initialization command. This will generate one unseal key and one root token, and save them to a file: + + ```bash + bao operator init -key-shares=1 -key-threshold=1 | grep -E 'Unseal|Token' > bao.ini + ``` + + !!! warning + Do **not** store `bao.ini` on a shared system or in source control. It contains sensitive credentials. + + This filters only the `Unseal Key` and `Initial Root Token` lines and saves them in `bao.ini`. + + Example output: + + ```bash + Unseal Key 1: LQtOF4m5ZwUtw9awGWiRf5/UNOEb4TqgJk8aP2z/0uE= + Initial Root Token: s.QKH11VesQVHLykL2fursdNjK + ``` + +### Step 5. Unseal and Mount the KV Secrets Engine + +After initializing OpenBao, unseal the instance and mount a KV (key-value) secrets engine under the path `percona/`. This is where keys for `pg_tde` will be stored. + +- Load the keys: + + Read the `UNSEAL_KEY` and `VAULT_TOKEN` from the `bao.ini` file: + + ```bash + UNSEAL_KEY=$(cat bao.ini | grep Unseal | cut -d ':' -f 2) + TOKEN=$(cat bao.ini | grep Token | cut -d ':' -f 2) + ``` + + Set the required environment variables: + + ```bash + export VAULT_ADDR="http://127.0.0.1:8200" + export VAULT_TOKEN=$TOKEN + ``` + +- Unseal the OpenBao server, run: + + ```bash + bao operator unseal $UNSEAL_KEY + ``` + + Expected output: + + ```yaml + Seal Type: shamir + Initialized: true + Sealed: false + ... + ``` + +- Enable the KV engine, run: + + ```bash + bao secrets enable --path=percona --version=2 kv + ``` + + This creates a versioned KV store at `percona/`, where you can store and manage keys securely. + +- Confirm mount status: + + List all enabled secrets engines: + + ```bash + bao secrets list + ``` + + Expected output: + + ```python + Path Type Description + ---- ---- ----------- + percona/ kv n/a + ... + ``` + +### Step 6. Configure Key Provider for pg_tde + +Once OpenBao is unsealed and the Percona KV store is mounted, configure a database-level key provider and principal key for your instance. + +- Set Vault token environment variable: + + Extract and export the Vault token from your `bao.ini` file: + + ```bash + export VAULT_TOKEN=$(cat bao.ini | grep Token | cut -d ':' -f 2) + ``` + +- Connect as the postgres user and configure the database: + + Create a new database using the `tde_template`, and set up the provider: + + ```bash + su - postgres <<_eof_ + dropdb --if-exists db01 + createdb db01 --template=tde_template + + psql db01 <<_eof1_ + \set ON_ERROR_STOP on + + -- Add the Vault V2 provider + SELECT * FROM pg_tde_add_database_key_provider_vault_v2 ( + 'percona01', -- provider name + '$VAULT_TOKEN', -- Vault token + 'http://127.0.0.1:8200', -- Vault address + 'percona', -- mount path in Vault + NULL -- optional CA cert + ); + + -- Set the encryption key for this database + SELECT * FROM pg_tde_set_key_using_database_key_provider ( + 'key01', -- key name + 'percona01', -- provider name + true -- ensure key is unique + ); + + -- (Optional) Verify setup + SELECT * FROM pg_tde_list_all_database_key_providers(); + SELECT * FROM pg_tde_key_info(); + _eof1_ + _eof_ + ``` + +For more information on related functions, see the link below: + +[Percona pg_tde Function Reference](../functions.md){.md-button} + +## Next steps + +[Global Principal Key Configuration :material-arrow-right:](set-principal-key.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-thales.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-thales.md index daf6bd5e16039..b6607b8ad8ffb 100644 --- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-thales.md +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/kmip-thales.md @@ -3,3 +3,11 @@ `pg_tde` is compatible with the Thales CipherTrust Manager via the KMIP protocol. For a full setup guide, see [the Thales documentation](https://thalesdocs.com/ctp/cm/2.19/reference/kmip-ref/index.html?). For more information on adding or modifying the provider, see the [Adding or modifying KMIP providers](https://docs.percona.com/pg-tde/functions.html?h=pg_tde_add_global_key_provider_kmip#adding-or-modifying-kmip-providers) topic. + +For more information on related functions, see the link below: + +[Percona pg_tde Function Reference](../functions.md){.md-button} + +## Next steps + +[Global Principal Key Configuration :material-arrow-right:](set-principal-key.md){.md-button} \ No newline at end of file diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index 9d542f2156a1c..1cd80ca070360 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -178,6 +178,7 @@ nav: - "2.1 Configure Key Management (KMS)": - "2.1 Configure Key Management (KMS)": global-key-provider-configuration/index.md - "KMIP Configuration": global-key-provider-configuration/kmip-server.md + - "OpenBao Configuration": global-key-provider-configuration/kmip-openbao.md - "Fortanix Configuration": global-key-provider-configuration/kmip-fortanix.md - "Vault Configuration": global-key-provider-configuration/vault.md - "Thales Configuration": global-key-provider-configuration/kmip-thales.md