From f24fac5f4a6cfa05a2bacf390c2d046708283ce8 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 18 Jun 2025 14:15:14 +0300 Subject: [PATCH 1/5] initial update from AA feedback In set-principal-key.md: * updated with correct code example using set_server_key_using_global parameter * updated note to reflect correct config In features.md: * Removed temporary tables feature to clear confusion, removed logical replication mention, removed WAL encryption as a feature. In functions.md: * Added ON FUNCTION for grant/revoke execution * Modified sensitive info bolded paragraph to important note * Small modifications to notes display, title cases and text fixes * added note to Add or modify Vault providers for keeping the same principal key. * Added warning for WAL in pg_tde_create_key_using_global_key_provider In general: * Removed all logical replication mentions except the FAQ and in RC2 release note. --- contrib/pg_tde/documentation/docs/features.md | 3 -- .../pg_tde/documentation/docs/functions.md | 29 ++++++++++++------- .../set-principal-key.md | 13 +++------ .../docs/index/supported-versions.md | 4 +-- .../documentation/docs/index/tde-encrypts.md | 3 +- 5 files changed, 27 insertions(+), 25 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/features.md b/contrib/pg_tde/documentation/docs/features.md index e7dc760e1c821..8809336fdc7ff 100644 --- a/contrib/pg_tde/documentation/docs/features.md +++ b/contrib/pg_tde/documentation/docs/features.md @@ -9,16 +9,13 @@ The following features are available for the extension: * Data tables * Index data for encrypted tables * TOAST tables - * Temporary tables created during database operations !!! note Metadata of those tables is not encrypted. -* Global Write-Ahead Log (WAL) encryption for data in both encrypted and non-encrypted tables * Single-tenancy support via a global keyring provider * Multi-tenancy support * Table-level granularity for encryption and access control * Multiple Key management options -* Logical replication of encrypted tables [Overview](index/index.md){.md-button} [Get Started](install.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 563d359aa2cf4..488464609fd49 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -8,15 +8,15 @@ By default, `pg_tde` is locked down. No one is allowed to do any operations unti However, database owners can run the “view keys” and “set principal key” functions on their own databases. You can delegate these rights to other roles with the following commands: -* `GRANT EXECUTE` -* `REVOKE EXECUTE` +* `GRANT EXECUTE ON FUNCTION` +* `REVOKE EXECUTE ON FUNCTION` ## Key provider management A key provider is a system or service responsible for managing encryption keys. `pg_tde` supports the following key providers: * local file (not recommended for production use) -* Hashicorp Vault / OpenBao +* HashiCorp Vault / OpenBao * KMIP compatible providers Key provider management includes the following operations: @@ -52,9 +52,14 @@ The `change` functions require the same parameters as the `add` functions. They Provider specific parameters differ for each implementation. Refer to the respective subsection for details. -**Some provider specific parameters contain sensitive information, such as passwords. Never specify these directly, use the remote configuration option instead.** +!!! warning + Some provider specific parameters contain sensitive information, such as passwords. **Never** specify these directly, use the remote configuration option instead. -#### Adding or modifying Vault providers +!!! note + The updated provider must be able to retrieve the same principal keys as the original configuration. + If the new configuration cannot access existing keys, encrypted data and backups will become unreadable. + +#### Add or modify Vault providers The Vault provider connects to a HashiCorp Vault or an OpenBao server, and stores the keys on a key-value store version 2. @@ -106,7 +111,7 @@ where: * `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 -#### Adding or modifying KMIP providers +#### Add or modify KMIP providers The KMIP provider uses a remote KMIP server. @@ -165,7 +170,7 @@ where: !!! note The specified access parameters require permission to read and write keys at the server. -### Adding or modifying local keyfile providers +### Add or modify local keyfile providers This provider manages database keys using a local keyfile. @@ -225,14 +230,14 @@ These functions list the details of all key providers for the current database o * `pg_tde_list_all_database_key_providers()` * `pg_tde_list_all_global_key_providers()` -!!! important +!!! warning All configuration values include possibly sensitive values, such as passwords. **Never** specify these directly, use the remote configuration option instead. ## Principal key management -Use these functions to create a new principal key at a given keyprover, and to use those keys for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope. +Use these functions to create a new principal key at a given key provider, and to use those keys for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope. -Princial keys are stored on key providers by the name specified in this function - for example, when using the Vault provider, after creating a key named "foo", a key named "foo" will be visible on the Vault server at the specified mount point. +Principal keys are stored on key providers by the name specified in this function - for example, when using the Vault provider, after creating a key named "foo", a key named "foo" will be visible on the Vault server at the specified mount point. ### pg_tde_creates_key_using_database_key_provider @@ -244,6 +249,7 @@ SELECT pg_tde_create_key_using_database_key_provider( 'provider-name' ); ``` + ### pg_tde_create_key_using_global_key_provider Creates a principal key at a global key provider with the given name. For later use with pg_tde_set_ series of functions. @@ -289,6 +295,9 @@ SELECT pg_tde_set_server_key_using_global_key_provider( ); ``` +!!! warning + The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. **Do not enable this feature in production environments**. + ### pg_tde_set_default_key_using_global_key_provider Sets or rotates the default principal key for the server using the specified global key provider. diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md index 4c3cc3802d04e..7956cdc30f16a 100644 --- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md +++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md @@ -34,21 +34,16 @@ SELECT pg_tde_set_default_key_using_global_key_provider( The key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider. !!! note - This process sets the **default principal key** for the server. Any database without its own key configuration will use this key. + This process sets the **default principal key for the entire server**. Any database without a key explicitly configured will fall back to this key. ## Example This example is for testing purposes only. Replace the key name and provider name with your values: ```sql -SELECT pg_tde_create_key_using_global_key_provider( - 'test-db-master-key', - 'file-vault' -); - -SELECT pg_tde_set_key_using_global_key_provider( - 'test-db-master-key', - 'file-vault' +SELECT pg_tde_set_server_key_using_global_key_provider( + 'key-name', + 'provider-name' ); ``` diff --git a/contrib/pg_tde/documentation/docs/index/supported-versions.md b/contrib/pg_tde/documentation/docs/index/supported-versions.md index ed4758d0b671c..d943451450d58 100644 --- a/contrib/pg_tde/documentation/docs/index/supported-versions.md +++ b/contrib/pg_tde/documentation/docs/index/supported-versions.md @@ -1,6 +1,6 @@ # Versions and Supported PostgreSQL Deployments -The `pg_tde` extension is available for [Percona Server for PostgreSQL 17.x](https://docs.percona.com/postgresql/17/postgresql-server.html), an open source, drop-in replacement for PostgreSQL Community. This version provides the `tde_heap` access method and offers [full encryption capabilities](../features.md), including encryption of tables, indexes, WAL data, and support for logical replication. +The `pg_tde` extension is available for [Percona Server for PostgreSQL 17.x](https://docs.percona.com/postgresql/17/postgresql-server.html), an open source, drop-in replacement for PostgreSQL Community. This version provides the `tde_heap` access method and offers [full encryption capabilities](../features.md), including encryption of tables, indexes and WAL data. The extension is tightly integrated with Percona Server for PostgreSQL to deliver enhanced encryption functionality that is not available in community builds. @@ -8,7 +8,7 @@ The extension is tightly integrated with Percona Server for PostgreSQL to delive By using our PostgreSQL distribution, you get: -- **Full encryption support** through the `tde_heap` access method, including tables, indexes, WAL data, and logical replication. +- **Full encryption support** through the `tde_heap` access method, including tables, indexes and WAL data. - **Enhanced performance and enterprise-ready features** not available in community builds. - **Regular updates and security patches** backed by Percona’s expert support team. - **Professional support** and guidance for secure PostgreSQL deployments. diff --git a/contrib/pg_tde/documentation/docs/index/tde-encrypts.md b/contrib/pg_tde/documentation/docs/index/tde-encrypts.md index 53bbb82b2198f..1bc2c70cef3e4 100644 --- a/contrib/pg_tde/documentation/docs/index/tde-encrypts.md +++ b/contrib/pg_tde/documentation/docs/index/tde-encrypts.md @@ -6,6 +6,7 @@ * **Temporary tables** created during the query execution, for data tables created using the extension. * **Write-Ahead Log (WAL) data** for the entire database cluster. This includes WAL data in encrypted and non-encrypted tables. * **Indexes** on encrypted tables. -* **Logical replication data** for encrypted tables (ensures encrypted content is preserved across replicas). + +!!! [Table Access Methods and TDE](table-access-method.md){.md-button} From b75078996e1da8e88dda03160519537211e2d293 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 18 Jun 2025 14:35:36 +0300 Subject: [PATCH 2/5] Update functions.md * fixed keyfile to key file and keyfile proviers to key file providers * updated remote config options to file paths for specific param warning note. --- contrib/pg_tde/documentation/docs/functions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 488464609fd49..4110049b9092a 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -53,7 +53,7 @@ The `change` functions require the same parameters as the `add` functions. They Provider specific parameters differ for each implementation. Refer to the respective subsection for details. !!! warning - Some provider specific parameters contain sensitive information, such as passwords. **Never** specify these directly, use the remote configuration option instead. + Some provider specific parameters contain sensitive information, such as passwords. **Never** specify these directly, use the file paths instead. !!! note The updated provider must be able to retrieve the same principal keys as the original configuration. @@ -172,14 +172,14 @@ where: ### Add or modify local keyfile providers -This provider manages database keys using a local keyfile. +This provider manages database keys using a local key file. This function is intended for development or quick testing, and stores the keys unencrypted in the specified data file. !!! important - Local keyfile providers are **not recommended** for production environments, they lack the security and manageability of external key management systems. + Local key file providers are **not recommended** for production environments, they lack the security and manageability of external key management systems. -Add a local keyfile provider: +Add a local key file provider: ```sql SELECT pg_tde_add_database_key_provider_file( @@ -193,7 +193,7 @@ SELECT pg_tde_add_global_key_provider_file( ); ``` -Change a local keyfile provider: +Change a local key file provider: ```sql SELECT pg_tde_change_database_key_provider_file( From 977da84820e9fc71a5d4fbcd7f945a5df87c6df2 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 18 Jun 2025 14:49:58 +0300 Subject: [PATCH 3/5] Update functions.md fixed keyfile to key file for title Removed warning notes regarding remote config options. --- contrib/pg_tde/documentation/docs/functions.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 4110049b9092a..5124f60e0abb4 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -52,9 +52,6 @@ The `change` functions require the same parameters as the `add` functions. They Provider specific parameters differ for each implementation. Refer to the respective subsection for details. -!!! warning - Some provider specific parameters contain sensitive information, such as passwords. **Never** specify these directly, use the file paths instead. - !!! note The updated provider must be able to retrieve the same principal keys as the original configuration. If the new configuration cannot access existing keys, encrypted data and backups will become unreadable. @@ -170,7 +167,7 @@ where: !!! note The specified access parameters require permission to read and write keys at the server. -### Add or modify local keyfile providers +### Add or modify local key file providers This provider manages database keys using a local key file. @@ -230,9 +227,6 @@ These functions list the details of all key providers for the current database o * `pg_tde_list_all_database_key_providers()` * `pg_tde_list_all_global_key_providers()` -!!! warning - All configuration values include possibly sensitive values, such as passwords. **Never** specify these directly, use the remote configuration option instead. - ## Principal key management Use these functions to create a new principal key at a given key provider, and to use those keys for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope. From 09ee6311103fd10b11ce7f96e0220e1bb4ba7d01 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 18 Jun 2025 14:57:28 +0300 Subject: [PATCH 4/5] Update functions.md restructured and improved paragraphs create key and creates keys --- contrib/pg_tde/documentation/docs/functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md index 5124f60e0abb4..ae6c0494da17f 100644 --- a/contrib/pg_tde/documentation/docs/functions.md +++ b/contrib/pg_tde/documentation/docs/functions.md @@ -235,7 +235,7 @@ Principal keys are stored on key providers by the name specified in this functio ### pg_tde_creates_key_using_database_key_provider -Creates a principal key at a database local key provider with the given name. For later use with pg_tde_set_key_using_database_key_provider(). +Creates a principal key using the database-local key provider with the specified name. Use this key later with [`pg_tde_set_key_using_database_key_provider()`](#pg_tde_set_key_using_database_key_provider). ```sql SELECT pg_tde_create_key_using_database_key_provider( @@ -246,7 +246,7 @@ SELECT pg_tde_create_key_using_database_key_provider( ### pg_tde_create_key_using_global_key_provider -Creates a principal key at a global key provider with the given name. For later use with pg_tde_set_ series of functions. +Creates a principal key at a global key provider with the given name. Use this key later with the `pg_tde_set_` series of functions. ```sql SELECT pg_tde_create_key_using_global_key_provider( From 91407eaa0b5574faaa1ea2118e5066a7ab906136 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 19 Jun 2025 13:43:00 +0300 Subject: [PATCH 5/5] Update features.md Added * Temporary tables --- contrib/pg_tde/documentation/docs/features.md | 1 + 1 file changed, 1 insertion(+) diff --git a/contrib/pg_tde/documentation/docs/features.md b/contrib/pg_tde/documentation/docs/features.md index 8809336fdc7ff..ce9cd10826a81 100644 --- a/contrib/pg_tde/documentation/docs/features.md +++ b/contrib/pg_tde/documentation/docs/features.md @@ -9,6 +9,7 @@ The following features are available for the extension: * Data tables * Index data for encrypted tables * TOAST tables + * Temporary tables !!! note Metadata of those tables is not encrypted.