A handful of fixes

created principal key file and updated the flow of the docs, TOC, fixes to texts and updated the way we present sql commands
percona · Andriciuc · May 8, 2025 · Apr 17, 2025 · Apr 17, 2025 · Apr 22, 2025
commit 1e3c16071997a1200fbe21c44cbf811be4ca6430
@@ -1,8 +1,8 @@
-# Install `pg_tde` on Debian or Ubuntu
+# Install pg_tde on Debian or Ubuntu
 
-This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL :octicons-link-external-16:](https://docs.percona.com/postgresql/latest/index.html).
+This page explains how to install `pg_tde` with [Percona Distribution for PostgreSQL :octicons-link-external-16:](https://docs.percona.com/postgresql/latest/index.html).
 
-Check the [list of supported platforms](install.md#__tabbed_1_1).
+Make sure you check the [list of supported platforms](install.md#__tabbed_1_1) before continuing.
 
 ## Preconditions
 
@@ -21,31 +21,31 @@ Check the [list of supported platforms](install.md#__tabbed_1_1).
     Install them with the following command:
 
     ```{.bash data-prompt="$"}
-    $ sudo apt-get install -y wget gnupg2 curl lsb-release
+        $ sudo apt-get install -y wget gnupg2 curl lsb-release
     ```
 
 2. Fetch the `percona-release` package
 
     ```{.bash data-prompt="$"}
-    $ sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
+        $ sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
     ```
 
 3. Install `percona-release`
 
     ```{.bash data-prompt="$"}
-    $ sudo dpkg -i percona-release_latest.generic_all.deb
+        $ sudo dpkg -i percona-release_latest.generic_all.deb
     ```
 
 4. Enable the Percona Distribution for PostgreSQL repository
 
     ```{.bash data-prompt="$"}
-    $ sudo percona-release enable-only ppg-{{pgversion17}} 
+        $ sudo percona-release enable-only ppg-{{pgversion17}} 
     ```
 
 6. Update the local cache
 
     ```bash
-    sudo apt-get update
+        sudo apt-get update
     ```
 
 ## Install `pg_tde` {.power-number}
@@ -59,17 +59,17 @@ Check the [list of supported platforms](install.md#__tabbed_1_1).
         The use of the `CASCADE` parameter deletes all tables that were created in the database with `pg_tde` enabled and also all dependencies upon the encrypted table (e.g. foreign keys in a non-encrypted table used in the encrypted one).     
 
         ```sql
-        DROP EXTENSION pg_tde CASCADE
+            DROP EXTENSION pg_tde CASCADE
         ```
 
     2. Uninstall the `percona-postgresql-17-pg-tde` package.  
 
 After all [preconditions](#preconditions) are met, run the following command to install `pg_tde`:
 
 ```{.bash data-prompt="$"}
-$ sudo apt-get install -y percona-postgresql-17 
+    $ sudo apt-get install -y percona-postgresql-17 
 ```
 
 ## Next step
 
-[Setup :material-arrow-right:](setup.md){.md-button}
+[Configure pg_tde :material-arrow-right:](setup.md){.md-button}
@@ -4,15 +4,13 @@ The `pg_tde` extension provides functions for managing different aspects of its
 
 ## Permission management
 
-By default, `pg_tde` is restrictive. It doesn't allow any operations until permissions are granted to the user. Only superusers can run permission management functions to manage user permissions. Operations on the global scope are limited to superusers only.
-
-Permissions are based on the normal `EXECUTE` permission on the functions provided by `pg_tde`. Superusers manage them using the `GRANT EXECUTE` and `REVOKE EXECUTE` commands.
+By default, `pg_tde` is restrictive. It doesn't allow any operations until permissions are granted to the user. Only superusers can create or modify to key providers or modify objects in the global scope. Functions for viewing keys and for setting the principal key in a database local key provider can on the other hand be run by the database owner and be delegated to normal users using the `GRANT EXECUTE` and `REVOKE EXECUTE` commands.
 
 The following functions are also provided for easier management of functionality groups:
 
 ### Database local key management
 
-Use these functions to grant or revoke permissions to manage permissions for the current database. They enable or disable all functions related to the providers and keys on the current database:
+Use these functions to grant or revoke permissions to manage the key of the current database. They enable or disable all functions related to the key of the current database:
 
 * `pg_tde_grant_database_key_management_to_role(role)`
 * `pg_tde_revoke_database_key_management_from_role(role)`
@@ -84,14 +82,14 @@ The Vault provider connects to a HashiCorp Vault or an OpenBao server, and store
 
 Use the following functions to add the Vault provider:
 
-```
+```sql
 SELECT pg_tde_add_database_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','url','mount','ca_path');
 ```
 
 These functions change the Vault provider:
 
-```
+```sql
 SELECT pg_tde_change_database_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
 SELECT pg_tde_change_global_key_provider_vault_v2('provider-name','secret_token','url','mount','ca_path');
 ```

@@ -1,8 +1,16 @@
-# Global Key Provider Configuration
+# Configure Key Management (KMS)
 
-In production environments, storing encryption keys locally on the PostgreSQL server can create security risks. To enhance security, `pg_tde` supports integration with external Key Management Systems (KMS) through a Global Key Provider interface.
+In production environments, storing encryption keys locally on the PostgreSQL server can introduce security risks. To enhance security, `pg_tde` supports integration with external Key Management Systems (KMS) through a Global Key Provider interface.
 
-This section explains how to configure `pg_tde` to use external key providers, including KMIP servers, HashiCorp Vault, local keyring files and more.
+This section describes how you can configure `pg_tde` to use the local and external key providers.
+To use an external KMS with `pg_tde`, follow these two steps:
+
+1. [Configure a Key Provider](vault.md)(kmip-server.md)(keyring.md)
+2. Set the [Global Principal Key](set-principal-key.md)
 
 !!! note
-     KMS integration is optional and it is intended for advanced deployments requiring higher security standards.
+     KMS integration is optional and intended for advanced deployments that require higher security standards.
+
+Select your prefered configuration from the links below:
+
+[Configure KMIP :material-arrow-right:](kmip-server.md){.md-button} [Configure Vault :material-arrow-right:](vault.md){.md-button} [Configure Keyring :material-arrow-right:](keyring.md){.md-button}
@@ -0,0 +1,23 @@
+# Configure local keyring file
+
+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.
+
+```sql
+    SELECT pg_tde_add_global_key_provider_file(
+        'provider-name',
+        '/path/to/the/keyring/data.file'
+    );
+```
+
+<i note>:material-information: Note:</i> The following example is used for testing purposes only:
+
+```sql
+    SELECT pg_tde_add_global_key_provider_file(
+        'file-keyring',
+        '/tmp/pg_tde_test_local_keyring.per'
+    );
+```
+
+## Next Step
+
+[Test pg_tde :material-arrow-right:](../test.md){.md-button}
@@ -1,27 +1,52 @@
-# Set up with KMIP server
+# Configure KMIP server
 
-Set up a global key provider
+To use a Key Management Interoperability Protocol (KMIP) server with `pg_tde`, you must configure it as a global key provider. This setup enables `pg_tde` to securely fetch and manage encryption keys from a centralized key management appliance.
 
-Make sure you have obtained the root certificate for the KMIP server and the keypair for the client. The client key needs permissions to create / read keys on the server. Find the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine).
+!!! note
 
-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.
+    You need the root certificate of the KMIP server and a client key/certificate pair with permissions to create and read keys on the server.
 
-```sql
-SELECT pg_tde_add_global_key_provider_kmip('provider-name','kmip-IP', 5696, '/path_to/server_certificate.pem', '/path_to/client_key.pem');
-```
+It is recommended to review the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine) if you're using Vault.
+
+For testing purposes, you can use a lightweight PyKMIP server, which enables easy certificate generation and basic KMIP behavior. If you're using a production-grade KMIP server, ensure you obtain valid, trusted certificates from the key management appliance.
+
+## Example usage
+
+    ```sql
+    SELECT pg_tde_add_global_key_provider_kmip(
+        'provider-name',
+        'kmip-IP', 
+        5696,
+        '/path_to/server_certificate.pem', 
+        '/path_to/client_key.pem'
+    );
+    ```
 
-where:
+## Parameter descriptions
 
-* `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider.
+* `provider-name` is the name of the provider. You can specify any name, it's for you to identify the provider
 * `kmip-IP` is the IP address of a domain name of the KMIP server
-* `port` is the port to communicate with the KMIP server. Typically used port is 5696.
-* `server-certificate` is the path to the certificate file for the KMIP server.
-* `client key` is the path to the client key.
+* `port` is the port to communicate with the KMIP server. Typically used port is 5696
+* `server-certificate` is the path to the certificate file for the KMIP server
+* `client key` is the path to the client key
 
-<i warning>:material-information: Warning:</i> Note that pg_tde_add_global_key_provider_kmip currently accepts only a combined client key + client certificate for the last parameter of this function named as `client key`.
+<i warning>:material-information: Warning:</i> `pg_tde_add_global_key_provider_kmip` currently accepts only a combined client key and a client certificate for its final parameter, reffered to as `client key`.
 
-<i warning>:material-information: Warning:</i> This example is for testing purposes only:
+<i note>:material-information: Note:</i> The following example is for testing purposes only.
 
 ```sql
-SELECT pg_tde_add_global_key_provider_kmip('kmip','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_key_jane_doe.pem');
+    SELECT pg_tde_add_global_key_provider_kmip(
+        'kmip','127.0.0.1', 
+        5696, 
+        '/tmp/server_certificate.pem', 
+        '/tmp/client_key_jane_doe.pem'
+    );
 ```
+
+For more information on related functions, see the link below:
+    
+[Percona TDE function reference](../functions.md){.md-button}
+
+## Next Step
+
+[Test pg_tde :material-arrow-right:](../test.md){.md-button}
@@ -0,0 +1,23 @@
+# Set the Global Principal Key
+
+Add a default principal key
+
+    ```sql
+    SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
+    ```
+
+## Parameter description
+
+    * `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
+    * `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
+    * `ensure_new_key` defines if a principal key must be unique. The default value `true` means that you must speficy a unique key during key rotation. The `false` value allows reusing an existing principal key.
+
+    <i warning>:material-information: Warning:</i> This example is for testing purposes only. Replace the key name and provider name with your values:
+
+    ```sql
+    SELECT pg_tde_set_key_using_global_key_provider('test-db-master-key','file-vault','ensure_new_key');
+    ```
+
+    The key is auto-generated.
+
+    After this, all databases that do not have something else configured will use this newly generated principal key.
@@ -0,0 +1,46 @@
+# Configure HashiCorp Vault
+
+You can configure `pg_tde` to use HashiCorp Vault as a global key provider for managing encryption keys securely.
+
+!!! note
+    This guide assumes that your Vault server is already set up and accessible. Vault configuration is outside the scope of this document, see [Vault's official documentation](https://developer.hashicorp.com/vault/docs) for more information.
+
+## Example usage
+
+```sql
+    SELECT pg_tde_add_global_key_provider_vault_v2(
+        'provider-name',
+        'secret_token',
+        'url',
+        'mount',
+        'ca_path'
+    );
+```
+
+## 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
+* `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
+
+<i note>:material-information: Note:</i> The following example is for testing purposes only. Use secure tokens and proper SSL validation in production environments:
+
+```sql
+    SELECT pg_tde_add_global_key_provider_vault_v2(
+        'my-vault',
+        'hvs.zPuyktykA...example...ewUEnIRVaKoBzs2',
+        'http://vault.vault.svc.cluster.local:8200',
+        'secret/data',
+        NULL
+    );
+```
+
+For more information on related functions, see the link below:
+
+[Percona TDE function reference](../functions.md){.md-button}
+
+## Next Step
+
+[Test pg_tde :material-arrow-right:](../test.md){.md-button}
@@ -3,7 +3,7 @@
 To allow storing secrets or any other parameters in a more secure, external location, `pg_tde`
 allows users to specify an external reference instead of hardcoded parameters.
 
-In Alpha1 version, `pg_tde` supports the following external storage methods:
+In the Alpha1 version, `pg_tde` supports the following external storage methods:
 
 * `file`, which just stores the data in a simple file specified by a `path`. The file should be
 readable to the postgres process.
@@ -14,7 +14,7 @@ readable to the postgres process.
 To use the file provider with a file location specified by the `remote` method,
 use the following command:
 
-```
+```sql
 SELECT pg_tde_add_database_key_provider_file(
     'file-provider', 
     json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' )
@@ -23,12 +23,11 @@ SELECT pg_tde_add_database_key_provider_file(
 
 Or to use the `file` method, use the following command:
 
-```
+```sql
 SELECT pg_tde_add_database_key_provider_file(
     'file-provider', 
     json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' )
     );"
 ```
 
-Any parameter specified to the `add_key_provider` function can be a `json_object` instead of the string, 
-similar to the above examples.
+Any parameter specified to the `add_key_provider` function can be a `json_object` instead of the string, similar to the above examples.
@@ -6,7 +6,7 @@ Here's how to do it:
 
 1. Drop the extension using the `DROP EXTENSION` command:
 
-    ```
+    ```sql
     DROP EXTENSION pg_tde;
     ```
 

@@ -5,6 +5,9 @@ To encrypt the data, two types of keys are used:
 * Internal encryption keys to encrypt user data. They are stored internally, near the data that they encrypt.
 * The principal key to encrypt database keys. It is kept separately from the database keys and is managed externally in the key management store.
 
+!!! note
+    For more information on managing and storing principal keys externally, see [Configure Global Key Provider](../global-key-provider-configuration/index)
+
 You have the following options to store and manage principal keys externally:
 
 * Use the HashiCorp Vault server. Only the back end KV Secrets Engine - Version 2 (API) is supported.

@@ -1,6 +1,6 @@
-# Installation
+# Install pg_tde
 
-Install `pg_tde` using one of the available installation methods:
+To install `pg_tde`, use one of the following methods:
 
 === ":octicons-terminal-16: Package manager"
 
@@ -29,6 +29,10 @@ Install `pg_tde` using one of the available installation methods:
 
     [Install from tarballs :material-arrow-right:](https://docs.percona.com/postgresql/17/tarball.html){.md-button}
 
-## Next steps
+Follow the configuration steps below to continue:
 
-[Setup :material-arrow-right:](setup.md){.md-button}
+[Configure pg_tde :material-arrow-right:](setup.md){.md-button}
+
+If you’ve already completed these steps, feel free to skip ahead to a later section:
+
+ [Configure Global Key Provider :material-arrow-right:](global-key-provider-configuration/index.md){.md-button} [Test pg_tde :material-arrow-right:](test.md){.md-button} [WAL encryption configuration :material-arrow-right:](global-key-provider-configuration/index.md){.md-button}
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,7 +6,7 @@ Here's how to do it: @@
 . Drop the extension using the `DROP EXTENSION` command:
-        ```
+        ```sql
         DROP EXTENSION pg_tde;
         ```
@@ Expand Down @@