Innacurate documentation for OpenBao Configuration

[varshithmee]

Description

Issue

The current OpenBao documentation for pg_tde is outdated and missing critical setup steps. The documentation only shows how to use pg_tde_add_global_key_provider_vault_v2() but doesn't explain how to properly initialize OpenBao or set up the necessary secrets engine, policies, and authentication tokens that are required for pg_tde to work.At the same time, Vault configuration documentation did not work completely as mount points were handled differently. Newcomers engaging with open-source KMSs and TDE should find this more hjelpful.

Suggested solution

Proposed Documentation Update

The following documentation should replace or supplement the current OpenBao section:

---

Using OpenBao as a Key Provider

You can configure pg_tde to use OpenBao as a global key provider for managing encryption keys securely.

Prerequisites

This guide assumes that:

• Your OpenBao server is already set up and accessible
• OpenBao is initialized and unsealed
• You have administrative access to configure OpenBao

For OpenBao installation and basic configuration, see OpenBao's official documentation.

OpenBao Setup for pg_tde

Before configuring pg_tde to use OpenBao, you must set up OpenBao with the following components:

1. Enable KV Secrets Engine

pg_tde requires a KV v2 secrets engine to store encryption keys. Enable it at a mount path (we'll use tde as an example):

bao secrets enable -path=tde kv-v2

Note: Replace bao with your OpenBao CLI command (may be vault or openbao depending on your installation).

2. Create Access Policy

Create a policy that grants the necessary permissions to read and write keys in the secrets engine. Save the following policy to a file (e.g., tde-policy.json):

{
  "path": {
    "tde/*": {
      "capabilities": ["read", "create", "update", "list"]
    },
    "tde/metadata/*" : {
      "capabiliteis": ["read", "list"]
    },
    "sys/mounts/*": {
      "capabilities": ["read"]
    }
  }
}

Apply the policy to OpenBao:

bao policy write tde-policy /path/to/tde-policy.json

3. Create Authentication Token

Create a token with the policy attached:

bao token create -policy=tde-policy

Save the token value from the output - you'll need it for pg_tde configuration.

Alternatively, you can use AppRole authentication:

# Enable AppRole auth method
bao auth enable approle

# Create a role with the policy
bao write auth/approle/role/tde-role policies="tde-policy"

# Generate role ID and secret ID (for AppRole authentication)
bao read auth/approle/role/tde-role/role-id
bao write -f auth/approle/role/tde-role/secret-id

4. Store Token Securely

Save the token to a file that PostgreSQL can access (ensure proper file permissions):

echo "your-token-here" > /path/to/tde-token
chmod 600 /path/to/tde-token
chown postgres:postgres /path/to/tde-token

Configuring pg_tde with OpenBao

Once OpenBao is properly configured, register it as a global key provider in pg_tde:

SELECT pg_tde_add_global_key_provider_vault_v2(
    'provider-name',
    'url',
    'mount',
    'secret_token_path',
    'ca_path',
    'namespace'
);

Parameter Descriptions

• provider-name: The name to identify this key provider (e.g., 'my-openbao-provider')
• url: The URL of the OpenBao server (e.g., 'https://openbao.example.com:8200')
• mount: The mount path where the KV secrets engine is enabled (e.g., 'tde' for a mount at /tde)
• secret_token_path: The absolute path to the file containing the authentication token
• ca_path (optional): The path to the CA certificate file used for SSL verification (use NULL if not needed)
• namespace (optional): The namespace within the OpenBao server (use NULL if not using namespaces)

Complete Example

Production Setup with SSL Verification:

-- Register OpenBao as key provider
SELECT pg_tde_add_global_key_provider_vault_v2(
    'tde-openbao',
    'https://openbao.example.com:8200',
    'tde',
    '/secure/path/to/tde-token',
    '/etc/ssl/certs/ca-cert.pem',
    NULL
);

-- Create a master key using the provider
SELECT pg_tde_create_key_using_global_key_provider(
    'global-master-key',
    'tde-openbao'
);

-- Set as default key
SELECT pg_tde_set_default_key_using_global_key_provider(
    'global-master-key',
    'tde-openbao'
);

Docker/Container Setup (Internal Network):

When PostgreSQL and OpenBao are in the same Docker network:

SELECT pg_tde_add_global_key_provider_vault_v2(
    'tde-openbao',
    'https://openbao:8200',  -- Use container hostname
    'tde',
    '/openbao/init/tde-token',  -- Token file in mounted volume
    '/etc/ssl/certs/rootCA.pem'  -- CA cert for SSL verification
);

Troubleshooting

Connection Issues

• SSL Verification Errors: Ensure the CA certificate path is correct and the certificate is valid
• Network Connectivity: Verify PostgreSQL can reach the OpenBao server at the specified URL
• Token File Access: Ensure the PostgreSQL process has read access to the token file

Authentication Errors

• Invalid Token: Verify the token file contains the correct token and hasn't expired
• Policy Permissions: Ensure the token's policy grants read, create, update, and list capabilities on the mount path

Mount Path Issues

• Mount Not Found: Verify the KV secrets engine is enabled at the specified mount path
• Wrong Version: Ensure you're using KV v2 secrets engine (kv-v2), not KV v1

Security Best Practices

1. Use Minimal Permissions: Create policies that grant only the necessary capabilities
2. Secure Token Storage: Store tokens in files with restricted permissions (600) and owned by the postgres user
3. SSL/TLS: Always use HTTPS for OpenBao communication in production
4. Token Rotation: Regularly rotate authentication tokens
5. Network Security: Use firewalls and network policies to restrict access to OpenBao
6. Audit Logging: Enable audit logging in OpenBao to track all key access

Additional Resources

• OpenBao Documentation
• OpenBao KV Secrets Engine
• OpenBao Policies
• OpenBao Authentication

---

Summary of Changes Needed

1. Add complete OpenBao setup instructions (KV engine, policies, tokens)
2. Clarify the mount path parameter (should be just the mount name, not the full path)
3. Add examples for both production and containerized deployments
4. Include troubleshooting section
5. Add security best practices
6. Clarify token file requirements and permissions

This documentation update will help users properly configure OpenBao before attempting to use it with pg_tde, reducing configuration errors and support requests.

Additional context

No response

[ImTheKai]

Hi, thanks for the contribution and reaching out. We usually try to avoid duplicating upstream documentation, as it can get outdated super quickly, and we would rather link directly to the projects. Is there anything missing in the OpenBao documentation? We can potentially directly link to specific parts if this helps?

[Andriciuc]

Hello @varshithmee, thanks for the detailed feedback and for sharing this configuration update. Just to echo @ImTheKai's idea, we decided to intentionally avoid documenting full, prescriptive OpenBao and Vault configurations.

This is because copying specific upstream setups will create a long-term maintenance overhead and specific configurations can easily break as mount points, defaults, or behaviors change upstream.

We decided that our goal for documentation will be to document what pg_tde requires from a KMS and how it integrates, without tightly coupling the docs to fragile, version-specific configurations.

That said, please let us know how else we can help to improve clarity, and thank you again for the feedback!