percona · dAdAbird · Jun 4, 2025 · May 29, 2025 · May 30, 2025
@@ -20,8 +20,9 @@ pykmip-server -f "$SCRIPT_DIR/../contrib/pg_tde/pykmip-server.conf" -l /tmp/kmip
 TV=$(mktemp)
 { exec >$TV; vault server -dev; } &
 sleep 10
-export ROOT_TOKEN=$(cat $TV | grep "Root Token" | cut -d ":" -f 2 | xargs echo -n)
-echo "export ROOT_TOKEN=$ROOT_TOKEN"
+export ROOT_TOKEN_FILE=$(mktemp)
+cat $TV | grep "Root Token" | cut -d ":" -f 2 | xargs echo -n > $ROOT_TOKEN_FILE
+echo "export ROOT_TOKEN_FILE=$ROOT_TOKEN_FILE"
 if [ -v GITHUB_ACTIONS ]; then
-    echo "ROOT_TOKEN=$ROOT_TOKEN" >> $GITHUB_ENV
+    echo "ROOT_TOKEN_FILE=$ROOT_TOKEN_FILE" >> $GITHUB_ENV
 fi
@@ -116,9 +116,9 @@ _See [Make Builds for Developers](https://github.com/percona/pg_tde/wiki/Make-bu
         -- pg_tde_add_database_key_provider_vault_v2(provider_name, vault_token, vault_url, vault_mount_path, vault_ca_path)
         SELECT pg_tde_add_database_key_provider_vault_v2(
             'vault-provider',
-            json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/token' ),
-            json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/url' ),
-            to_json('secret'::text), NULL);
+            '/path/to/token_file',
+            'https://your.vault.server',
+            'secret', NULL);
 
         -- For File key provider
         -- pg_tde_add_database_key_provider_file(provider_name, file_path);

@@ -168,11 +168,10 @@ For such situations, `pg_tde` also provides [command line tools](../command-line
 
 ### Sensitive key provider information
 
-Key provider information authentication details is a sensitive information. It is not safe to store it together with the database in the `$PGDATA` directory, or even on the same server.
+!!! important
 
-To safeguard key providers' sensitive information, `pg_tde` supports references to external services. Instead of specifying authentication details directly, users specify the reference to the external service where it is stored. `pg_tde` then downloads the provider's authentication details when needed.
-
-The currently supported external services are HTTP and external file references.
+    Authentication details for key providers are sensitive and must be protected.
+    Do not store these credentials in the `$PGDATA` directory alongside the database. Instead, ensure they are stored in a secure location with strict file system permissions to prevent unauthorized access.
 
 ## User interface
 

@@ -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> <url> <mount_path> [<ca_path>]
+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> kmip <host> <port> <cert_path> <key_path> [<ca_path>] 
 ```
@@ -63,14 +63,14 @@ Use the following functions to add the Vault provider:
 ```sql
 SELECT pg_tde_add_database_key_provider_vault_v2(
   'provider-name',
-  'secret_token',
+  'secret_token_path',
   'url','mount',
   'ca_path'
 );
 
 SELECT pg_tde_add_global_key_provider_vault_v2(
   'provider-name',
-  'secret_token',
+  'secret_token_path',
   'url','mount',
   'ca_path'
 );
@@ -81,15 +81,15 @@ These functions change the Vault provider:
 ```sql
 SELECT pg_tde_change_database_key_provider_vault_v2(
   'provider-name',
-  'secret_token',
+  'secret_token_path',
   'url',
   'mount',
   'ca_path'
 );
 
 SELECT pg_tde_change_global_key_provider_vault_v2(
   'provider-name',
-  'secret_token',
+  'secret_token_path',
   'url',
   'mount',
   'ca_path'
@@ -101,13 +101,10 @@ where:
 * `provider-name` is the name of the key provider
 * `url` is the URL of the Vault server
 * `mount` is the mount point on the Vault server where the key provider should store the keys
-* `secret_token` is an access token with read and write access to the above mount point
+* `secret_token_path` is a path to the file that contains an access token with read and write access to the above mount point
 * **[optional]** `ca_path` is the path of the CA file used for SSL verification
 
-All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
-!!! important
-    Never specify the secret token directly, use a remote parameter instead.
 
 #### Adding or modifying KMIP providers
 
@@ -168,7 +165,6 @@ where:
 !!! note
     The specified access parameters require permission to read and write keys at the server.
 
-All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
 ### Adding or modifying local keyfile providers
 
@@ -212,8 +208,6 @@ where:
 * `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider.
 * `/path/to/the/key/provider/data.file` is the path to the key provider file.
 
-!!! note
-    All parameters can be either strings, or JSON objects [referencing remote parameters](how-to/external-parameters.md).
 
 ### Delete a provider
 

@@ -1,6 +1,6 @@
 # Keyring File Configuration
 
-This setup is intended for development and stores the keys unencrypted in the specified data file. See [how to use external reference to parameters](../how-to/external-parameters.md) to add an extra security layer to your setup.
+This setup is intended for development and stores the keys unencrypted in the specified data file.
 
 !!! note
      While keyfiles may be acceptable for **local** or **testing environments**, KMS integration is the recommended approach for production deployments.

@@ -10,7 +10,7 @@ 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',
+    'secret_token_path',
     'url',
     'mount',
     'ca_path'
@@ -20,7 +20,7 @@ SELECT pg_tde_add_global_key_provider_vault_v2(
 ## Parameter descriptions
 
 * `provider-name` is the name to identify this key provider
-* `secret_token` is an access token with read and write access to the above mount point
+* `secret_token_path` is a path to the file that contains an access token with read and write access to the above mount point
 * `url` is the URL of the Vault server
 * `mount` is the mount point where the keyring should store the keys
 * [optional] `ca_path` is the path of the CA file used for SSL verification
@@ -30,7 +30,7 @@ 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',
-    'hvs.zPuyktykA...example...ewUEnIRVaKoBzs2',
+    '/path/to/token_file',
     'http://vault.vault.svc.cluster.local:8200',
     'secret/data',
     NULL

@@ -84,14 +84,14 @@ You must do these steps for every database where you have created the extension.
         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','url','mount','ca_path');
+        SELECT pg_tde_add_database_key_provider_vault_v2('provider-name','secret_token_path','url','mount','ca_path');
         ``` 
 
         where: 
 
         * `url` is the URL of the Vault server
         * `mount` is the mount point where the keyring should store the keys
-        * `secret_token` is an access token with read and write access to the above mount point
+        * `secret_token_path` is a path to the file that contains an access token with read and write access to the above mount point
         * [optional] `ca_path` is the path of the CA file used for SSL verification
 
         <i warning>:material-information: Warning:</i> This example is for testing purposes only:
@@ -135,4 +135,3 @@ You must do these steps for every database where you have created the extension.
     !!! note
         The key is auto-generated.
 
-   <i info>:material-information: Info:</i> The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup.
@@ -40,15 +40,15 @@ Before turning WAL encryption on, you must follow the steps below to create your
     === "With HashiCorp Vault"
 
         ```sql
-        SELECT pg_tde_add_global_key_provider_vault_v2('provider-name', 'secret_token', 'url', 'mount', 'ca_path');
+        SELECT pg_tde_add_global_key_provider_vault_v2('provider-name', 'secret_token_path', 'url', 'mount', 'ca_path');
         ```
 
         where:
 
         * `provider-name` is the name you define for the key provider
         * `url` is the URL of the Vault server
         * `mount` is the mount point where the keyring should store the keys
-        * `secret_token` is an access token with read and write access to the above mount point
+        * `secret_token_path` is a path to the file that contains an access token with read and write access to the above mount point
         * [optional] `ca_path` is the path of the CA file used for SSL verification
 
     === "With keyring file"

@@ -188,7 +188,6 @@ nav:
       - "pg_checksums": command-line-tools/pg-tde-checksums.md 
     - "Uninstall pg_tde": how-to/uninstall.md
     - "Configure Multi-tenancy": how-to/multi-tenant-setup.md
-    - "Use Reference to External Parameters": how-to/external-parameters.md
     - "Decrypt an Encrypted Table": how-to/decrypt.md
   - faq.md
   - "Release Notes":

@@ -3,7 +3,7 @@ SELECT  * FROM pg_tde_key_info();
 ERROR:  Principal key does not exists for the database
 HINT:  Use set_key interface to set the principal key
 SELECT pg_tde_add_database_key_provider_file('incorrect-file-provider',  json_object('foo' VALUE '/tmp/pg_tde_test_keyring.per'));
-ERROR:  unexpected field "foo" for external value "path"
+ERROR:  key provider value cannot be an object
 SELECT pg_tde_add_database_key_provider_file('file-provider','/tmp/pg_tde_test_keyring.per');
  pg_tde_add_database_key_provider_file 
 ---------------------------------------
@@ -49,7 +49,7 @@ SELECT * FROM pg_tde_list_all_database_key_providers();
 (2 rows)
 
 SELECT pg_tde_change_database_key_provider_file('file-provider',  json_object('foo' VALUE '/tmp/pg_tde_test_keyring.per'));
-ERROR:  unexpected field "foo" for external value "path"
+ERROR:  key provider value cannot be an object
 SELECT * FROM pg_tde_list_all_database_key_providers();
  id | provider_name  | provider_type |                  options                   
 ----+----------------+---------------+--------------------------------------------
@@ -177,33 +177,13 @@ SELECT pg_tde_add_database_key_provider('file', 'provider', 'true');
 ERROR:  key provider options must be an object
 SELECT pg_tde_add_database_key_provider('file', 'provider', 'null');
 ERROR:  key provider options must be an object
--- Creating key providers fails if an external value object doesn't have all required keys
+-- Creating key providers fails if vaules are not scalar
 SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {}}');
-ERROR:  external value must contain "type" in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": null}}');
-ERROR:  external value must contain "type" in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "remote"}}');
-ERROR:  external remote value must contain "url" in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "remote", "url": null}}');
-ERROR:  external remote value must contain "url" in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "file"}}');
-ERROR:  external file value must contain "path" in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "file", "path": null}}');
-ERROR:  external file value must contain "path" in field "path"
--- Creating key providers fails if values are array instead of scalar
+ERROR:  key provider value cannot be an object
 SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": ["array"]}');
 ERROR:  unexpected array in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": ["array"]}}');
-ERROR:  unexpected array in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "file", "path": ["array"]}}');
-ERROR:  unexpected array in field "path"
--- Creating key providers fails if values are boolean
 SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": true}');
 ERROR:  unexpected boolean in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": true}}');
-ERROR:  unexpected boolean in field "path"
-SELECT pg_tde_add_database_key_provider('file', 'provider', '{"path": {"type": "file", "path": true}}');
-ERROR:  unexpected boolean in field "path"
 -- Modifying key providers fails if any required parameter is NULL
 SELECT pg_tde_change_database_key_provider(NULL, 'file-keyring', '{}');
 ERROR:  provider type cannot be null
@@ -231,33 +211,13 @@ SELECT pg_tde_change_database_key_provider('file', 'file-provider', 'true');
 ERROR:  key provider options must be an object
 SELECT pg_tde_change_database_key_provider('file', 'file-provider', 'null');
 ERROR:  key provider options must be an object
--- Modifying key providers fails if an external value object doesn't have all required keys
+-- Modifying key providers fails if vaules are not scalar
 SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {}}');
-ERROR:  external value must contain "type" in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": null}}');
-ERROR:  external value must contain "type" in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "remote"}}');
-ERROR:  external remote value must contain "url" in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "remote", "url": null}}');
-ERROR:  external remote value must contain "url" in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "file"}}');
-ERROR:  external file value must contain "path" in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "file", "path": null}}');
-ERROR:  external file value must contain "path" in field "path"
--- Modifying key providers fails if values are array instead of scalar
+ERROR:  key provider value cannot be an object
 SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": ["array"]}');
 ERROR:  unexpected array in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": ["array"]}}');
-ERROR:  unexpected array in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "file", "path": ["array"]}}');
-ERROR:  unexpected array in field "path"
--- Modifying key providers fails if values are boolean
 SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": true}');
 ERROR:  unexpected boolean in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": true}}');
-ERROR:  unexpected boolean in field "path"
-SELECT pg_tde_change_database_key_provider('file', 'file-provider', '{"path": {"type": "file", "path": true}}');
-ERROR:  unexpected boolean in field "path"
 -- Modifying key providers fails if new settings can't fetch existing server key
 SELECT pg_tde_add_global_key_provider_file('global-provider', '/tmp/global-provider-file-1');
  pg_tde_add_global_key_provider_file 

@@ -1,6 +1,6 @@
 CREATE EXTENSION IF NOT EXISTS pg_tde;
-\getenv root_token ROOT_TOKEN
-SELECT pg_tde_add_database_key_provider_vault_v2('vault-incorrect',:'root_token','http://127.0.0.1:8200','DUMMY-TOKEN',NULL);
+\getenv root_token_file ROOT_TOKEN_FILE
+SELECT pg_tde_add_database_key_provider_vault_v2('vault-incorrect',:'root_token_file','http://127.0.0.1:8200','DUMMY-TOKEN',NULL);
  pg_tde_add_database_key_provider_vault_v2 
 -------------------------------------------
 
@@ -16,7 +16,7 @@ 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','http://127.0.0.1:8200','secret',NULL);
+SELECT pg_tde_add_database_key_provider_vault_v2('vault-v2',:'root_token_file','http://127.0.0.1:8200','secret',NULL);
  pg_tde_add_database_key_provider_vault_v2 
 -------------------------------------------
 
@@ -52,6 +52,6 @@ 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', 'http://127.0.0.1:61', 'secret', NULL);
+SELECT pg_tde_add_database_key_provider_vault_v2('will-not-work', :'root_token_file', 'http://127.0.0.1:61', 'secret', NULL);
 ERROR:  HTTP(S) request to keyring provider "will-not-work" failed
 DROP EXTENSION pg_tde;
@@ -105,20 +105,17 @@ sql_tests = [
 tap_tests = [
   't/001_basic.pl',
   't/002_rotate_key.pl',
-  't/003_remote_config.pl',
-  't/004_file_config.pl',
-  't/005_multiple_extensions.pl',
-  't/006_remote_vault_config.pl',
-  't/007_tde_heap.pl',
-  't/008_key_rotate_tablespace.pl',
-  't/009_wal_encrypt.pl',
-  't/010_change_key_provider.pl',
-  't/011_unlogged_tables.pl',
-  't/012_replication.pl',
-  't/013_crash_recovery.pl',
-  't/014_pg_waldump_basic.pl',
-  't/015_pg_waldump_fullpage.pl',
-  't/016_pg_tde_change_key_provider.pl',
+  't/003_multiple_extensions.pl',
+  't/004_tde_heap.pl',
+  't/005_key_rotate_tablespace.pl',
+  't/006_wal_encrypt.pl',
+  't/007_change_key_provider.pl',
+  't/008_unlogged_tables.pl',
+  't/009_replication.pl',
+  't/010_crash_recovery.pl',
+  't/011_pg_waldump_basic.pl',
+  't/012_pg_waldump_fullpage.pl',
+  't/013_pg_tde_change_key_provider.pl',
 ]
 
 tests += {