Skip to content

PG-1607 PG-1652 Unify argument order for KMIP and Vault providers #404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 11, 2025
Merged

PG-1607 PG-1652 Unify argument order for KMIP and Vault providers #404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-change-key-provider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,6 @@ Depending on the provider type, the additional parameters are:

```bash
pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> file <filename>
pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> vault <token_path> <url> <mount_path> [<ca_path>]
pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> vault-v2 <url> <mount_path> <token_path> [<ca_path>]
pg_tde_change_key_provider [-D <datadir>] <dbOid> <provider_name> kmip <host> <port> <cert_path> <key_path> [<ca_path>]
```
50 changes: 26 additions & 24 deletions contrib/pg_tde/documentation/docs/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,15 +63,17 @@ Use the following functions to add the Vault provider:
```sql
SELECT pg_tde_add_database_key_provider_vault_v2(
'provider-name',
'url',
'mount',
'secret_token_path',
'url','mount',
'ca_path'
);

SELECT pg_tde_add_global_key_provider_vault_v2(
'provider-name',
'url',
'mount',
'secret_token_path',
'url','mount',
'ca_path'
);
```
Expand All @@ -81,17 +83,17 @@ These functions change the Vault provider:
```sql
SELECT pg_tde_change_database_key_provider_vault_v2(
'provider-name',
'secret_token_path',
'url',
'mount',
'secret_token_path',
'ca_path'
);

SELECT pg_tde_change_global_key_provider_vault_v2(
'provider-name',
'secret_token_path',
'url',
'mount',
'secret_token_path',
'ca_path'
);
```
Expand All @@ -115,19 +117,19 @@ Use these functions to add a KMIP provider:
```sql
SELECT pg_tde_add_database_key_provider_kmip(
'provider-name',
'kmip-addr',
`port`,
'/path_to/server_certificate.pem',
'/path_to/client_cert.pem',
'/path_to/client_key.pem'
'kmip-addr',
port,
'/path_to/client_cert.pem',
'/path_to/client_key.pem',
'/path_to/server_certificate.pem'
);
SELECT pg_tde_add_global_key_provider_kmip(
'provider-name',
'kmip-addr',
`port`,
'/path_to/server_certificate.pem',
'/path_to/client_certificate.pem',
'/path_to/client_key.pem'
'kmip-addr',
port,
'/path_to/client_certificate.pem',
'/path_to/client_key.pem',
'/path_to/server_certificate.pem'
);
```

Expand All @@ -136,19 +138,19 @@ These functions change the KMIP provider:
```sql
SELECT pg_tde_change_database_key_provider_kmip(
'provider-name',
'kmip-addr',
`port`,
'/path_to/server_certificate.pem',
'/path_to/client_cert.pem',
'/path_to/client_key.pem'
'kmip-addr',
port,
'/path_to/client_cert.pem',
'/path_to/client_key.pem',
'/path_to/server_certificate.pem'
);
SELECT pg_tde_change_global_key_provider_kmip(
'provider-name',
'kmip-addr',
`port`,
'/path_to/server_certificate.pem',
'/path_to/client_certificate.pem',
'/path_to/client_key.pem'
'kmip-addr',
port,
'/path_to/client_certificate.pem',
'/path_to/client_key.pem',
'/path_to/server_certificate.pem'
);
```

Expand Down
4 changes: 2 additions & 2 deletions contrib/pg_tde/documentation/docs/global-key-provider-configuration/vault.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ You can configure `pg_tde` to use HashiCorp Vault as a global key provider for m
```sql
SELECT pg_tde_add_global_key_provider_vault_v2(
'provider-name',
'secret_token_path',
'url',
'mount',
'secret_token_path',
'ca_path'
);
```
Expand All @@ -30,9 +30,9 @@ The following example is for testing purposes only. Use secure tokens and proper
```sql
SELECT pg_tde_add_global_key_provider_vault_v2(
'my-vault',
'/path/to/token_file',
'https://vault.vault.svc.cluster.local:8200',
'secret/data',
'/path/to/token_file',
'/path/to/ca_cert.pem'
);
```
Expand Down
12 changes: 6 additions & 6 deletions contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ You must do these steps for every database where you have created the extension.
For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.

```sql
SELECT pg_tde_add_database_key_provider_kmip('provider-name','kmip-addr', 5696, '/path_to/server_certificate.pem', '/path_to/client_cert.pem', '/path_to/client_key.pem');
SELECT pg_tde_add_database_key_provider_kmip('provider-name','kmip-addr', 5696, '/path_to/client_cert.pem', '/path_to/client_key.pem', '/path_to/server_certificate.pem');
```

where:
Expand All @@ -75,16 +75,16 @@ You must do these steps for every database where you have created the extension.

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```
SELECT pg_tde_add_database_key_provider_kmip('kmip','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_cert_jane_doe.pem', '/tmp/client_key_jane_doe.pem');
```sql
SELECT pg_tde_add_database_key_provider_kmip('kmip', '127.0.0.1', 5696, '/tmp/client_cert_jane_doe.pem', '/tmp/client_key_jane_doe.pem', '/tmp/server_certificate.pem');
```

=== "With HashiCorp Vault"

The Vault server setup is out of scope of this document.

```sql
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name','secret_token_path','url','mount','ca_path');
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name', 'url', 'mount', 'secret_token_path', 'ca_path');
```

where:
Expand All @@ -105,13 +105,13 @@ You must do these steps for every database where you have created the extension.
This setup is intended for development and stores the keys unencrypted in the specified data file.

```sql
SELECT pg_tde_add_database_key_provider_file('provider-name','/path/to/the/keyring/data.file');
SELECT pg_tde_add_database_key_provider_file('provider-name', '/path/to/the/keyring/data.file');
```

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```sql
SELECT pg_tde_add_database_key_provider_file('file-keyring','/tmp/pg_tde_test_local_keyring.per');
SELECT pg_tde_add_database_key_provider_file('file-keyring', '/tmp/pg_tde_test_local_keyring.per');
```

2. Add a principal key
Expand Down
10 changes: 5 additions & 5 deletions contrib/pg_tde/documentation/docs/wal-encryption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Before turning WAL encryption on, you must follow the steps below to create your
For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.

```sql
SELECT pg_tde_add_global_key_provider_kmip('provider-name','kmip-addr', 5696, '/path_to/server_certificate.pem', '/path_to/client_cert.pem', '/path_to/client_key.pem');
SELECT pg_tde_add_global_key_provider_kmip('provider-name', 'kmip-addr', 5696, '/path_to/client_cert.pem', '/path_to/client_key.pem', '/path_to/server_certificate.pem');
```

where:
Expand All @@ -33,14 +33,14 @@ Before turning WAL encryption on, you must follow the steps below to create your

<i warning>:material-information: Warning:</i> This example is for testing purposes only:

```
SELECT pg_tde_add_key_using_global_key_provider_kmip('kmip','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_cert_jane_doe.pem', '/tmp/client_key_jane_doe.pem');
```sql
SELECT pg_tde_add_key_using_global_key_provider_kmip('kmip', '127.0.0.1', 5696, '/tmp/client_cert_jane_doe.pem', '/tmp/client_key_jane_doe.pem', '/tmp/server_certificate.pem');
```

=== "With HashiCorp Vault"

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

where:
Expand All @@ -56,7 +56,7 @@ Before turning WAL encryption on, you must follow the steps below to create your
This setup is **not recommended**, as it is intended for development. The keys are stored **unencrypted** in the specified data file.

```sql
SELECT pg_tde_add_global_key_provider_file('provider-name','/path/to/the/keyring/data.file');
SELECT pg_tde_add_global_key_provider_file('provider-name', '/path/to/the/keyring/data.file');
```

3. Create principal key
Expand Down
4 changes: 2 additions & 2 deletions contrib/pg_tde/expected/kmip_test.out
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
CREATE EXTENSION pg_tde;
SELECT pg_tde_add_database_key_provider_kmip('kmip-prov','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_certificate_jane_doe.pem', '/tmp/client_key_jane_doe.pem');
SELECT pg_tde_add_database_key_provider_kmip('kmip-prov', '127.0.0.1', 5696, '/tmp/client_certificate_jane_doe.pem', '/tmp/client_key_jane_doe.pem', '/tmp/server_certificate.pem');
pg_tde_add_database_key_provider_kmip
---------------------------------------

Expand Down Expand Up @@ -35,6 +35,6 @@ SELECT pg_tde_verify_key();

DROP TABLE test_enc;
-- Creating provider fails if we can't connect to kmip server
SELECT pg_tde_add_database_key_provider_kmip('will-not-work','127.0.0.1', 61, '/tmp/server_certificate.pem', '/tmp/client_certificate_jane_doe.pem', '/tmp/client_key_jane_doe.pem');
SELECT pg_tde_add_database_key_provider_kmip('will-not-work', '127.0.0.1', 61, '/tmp/client_certificate_jane_doe.pem', '/tmp/client_key_jane_doe.pem', '/tmp/server_certificate.pem');
ERROR: SSL error: BIO_do_connect failed
DROP EXTENSION pg_tde;
16 changes: 8 additions & 8 deletions contrib/pg_tde/expected/vault_v2_test.out
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
CREATE EXTENSION IF NOT EXISTS pg_tde;
\getenv root_token_file VAULT_ROOT_TOKEN_FILE
\getenv cacert_file VAULT_CACERT_FILE
SELECT pg_tde_add_database_key_provider_vault_v2('vault-incorrect',:'root_token_file','https://127.0.0.1:8200','DUMMY-TOKEN',:'cacert_file');
SELECT pg_tde_add_database_key_provider_vault_v2('vault-incorrect', 'https://127.0.0.1:8200', 'DUMMY-TOKEN', :'root_token_file', :'cacert_file');
pg_tde_add_database_key_provider_vault_v2
-------------------------------------------

(1 row)

-- FAILS
SELECT pg_tde_set_key_using_database_key_provider('vault-v2-key','vault-incorrect');
SELECT pg_tde_set_key_using_database_key_provider('vault-v2-key', 'vault-incorrect');
ERROR: Invalid HTTP response from keyring provider "vault-incorrect": 404
CREATE TABLE test_enc(
id SERIAL,
Expand All @@ -17,13 +17,13 @@ CREATE TABLE test_enc(
) USING tde_heap;
ERROR: principal key not configured
HINT: create one using pg_tde_set_key before using encrypted tables
SELECT pg_tde_add_database_key_provider_vault_v2('vault-v2',:'root_token_file','https://127.0.0.1:8200','secret',:'cacert_file');
SELECT pg_tde_add_database_key_provider_vault_v2('vault-v2', 'https://127.0.0.1:8200', 'secret', :'root_token_file', :'cacert_file');
pg_tde_add_database_key_provider_vault_v2
-------------------------------------------

(1 row)

SELECT pg_tde_set_key_using_database_key_provider('vault-v2-key','vault-v2');
SELECT pg_tde_set_key_using_database_key_provider('vault-v2-key', 'vault-v2');
pg_tde_set_key_using_database_key_provider
--------------------------------------------

Expand Down Expand Up @@ -53,15 +53,15 @@ SELECT pg_tde_verify_key();

DROP TABLE test_enc;
-- Creating provider fails if we can't connect to vault
SELECT pg_tde_add_database_key_provider_vault_v2('will-not-work', :'root_token_file', 'https://127.0.0.1:61', 'secret', :'cacert_file');
SELECT pg_tde_add_database_key_provider_vault_v2('will-not-work', 'https://127.0.0.1:61', 'secret', :'root_token_file', :'cacert_file');
ERROR: HTTP(S) request to keyring provider "will-not-work" failed
-- Changing provider fails if we can't connect to vault
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', :'root_token_file', 'https://127.0.0.1:61', 'secret', :'cacert_file');
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', 'https://127.0.0.1:61', 'secret', :'root_token_file', :'cacert_file');
ERROR: HTTP(S) request to keyring provider "vault-v2" failed
-- HTTPS without cert fails
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', :'root_token_file', 'https://127.0.0.1:8200', 'secret', NULL);
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', 'https://127.0.0.1:8200', 'secret', :'root_token_file', NULL);
ERROR: HTTP(S) request to keyring provider "vault-v2" failed
-- HTTP against HTTPS server fails
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', :'root_token_file', 'http://127.0.0.1:8200', 'secret', NULL);
SELECT pg_tde_change_database_key_provider_vault_v2('vault-v2', 'http://127.0.0.1:8200', 'secret', :'root_token_file', NULL);
ERROR: Listing secrets of "http://127.0.0.1:8200" at mountpoint "secret" failed
DROP EXTENSION pg_tde;
Loading