From 6774c1ef9c0bdfda49157b8eda9c827b68dca150 Mon Sep 17 00:00:00 2001
From: Anastasia Alexadrova <anastasia.alexandrova@percona.com>
Date: Wed, 9 Oct 2024 19:19:12 +0200
Subject: [PATCH] Added WAL encryption setup

---
 documentation/docs/setup.md | 67 +++++++++++++++++++++++++++++++++++--
 documentation/docs/test.md  |  2 +-
 2 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/documentation/docs/setup.md b/documentation/docs/setup.md
index 04be1c59416..967d5e286ee 100644
--- a/documentation/docs/setup.md
+++ b/documentation/docs/setup.md
@@ -1,5 +1,7 @@
 # Set up `pg_tde`
 
+## Enable extension
+
 Load the `pg_tde` at the start time. The extension requires additional shared memory; therefore,  add the `pg_tde` value for the `shared_preload_libraries` parameter and restart the `postgresql` instance.
 
 1. Use the [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html) command from `psql` terminal to modify the `shared_preload_libraries` parameter.
@@ -38,7 +40,9 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         psql -d template1 -c 'CREATE EXTENSION pg_tde;'
         ```
 
-4. Set up a key provider for the database where you have enabled the extension
+## Key provider configuration
+
+1. Set up a key provider for the database where you have enabled the extension
 
     === "With HaschiCorp Vault"
 
@@ -63,7 +67,7 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         ```
        
        
-5. Add a principal key
+2. Add a principal key
 
     ```sql
     SELECT pg_tde_set_principal_key('name-of-the-principal-key', 'provider-name');
@@ -72,6 +76,65 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
    <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.
 
 
+## WAL encryption configuration (tech preview)
+
+Perform this step if you [installed Percona Server for PostgreSQL :octicons-link-external-16:](https://docs.percona.com/postgresql/17/installing.html). Otherwise, proceed to the [Next steps](#next-steps).
+
+1. Enable WAL level encryption using the ALTER SYSTEM SET command:
+
+    ```sql
+    ALTER SYSTEM set pg_tde.wal_encrypt = on;
+    ```
+
+2. Restart the server to apply the changes.
+
+    * On Debian and Ubuntu:    
+
+       ```sh
+       sudo systemctl restart postgresql.service
+       ```
+    
+    * On RHEL and derivatives
+
+       ```sh
+       sudo systemctl restart postgresql-17
+       ```
+
+    After you enabled `pg_tde` and started the Percona Server for PostgreSQL, a principal key and a keyring for WAL are created. We highly recommend you to create your own keyring and rotate the principal key. This is because the default principal key is created from the local keyfile and is stored unencrypted.
+
+3. Set up the key provider for WAL encryption
+
+   === "With HaschiCorp Vault"
+
+        ```sql
+        SELECT pg_tde_add_key_provider_vault_v2('PG_TDE_GLOBAL','provider-name',:'secret_token','url','mount','ca_path');
+        ``` 
+
+        where: 
+
+        * `PG_TDE_GLOBAL` is the constant that defines the WAL encryption key  
+        * `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
+        * [optional] `ca_path` is the path of the CA file used for SSL verification
+
+
+    === "With keyring file"
+
+        This setup is intended for development and stores the keys unencrypted in the specified data file.    
+
+        ```sql
+        SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file');
+        ```
+
+2. Rotate the principal key. Don't forget to specify the `PG_TDE_GLOBAL` constant to rotate only the principal key for WAL
+
+    ```sql
+    SELECT pg_tde_rotate_principal_key('PG_TDE_GLOBAL', 'new-principal-key', 'provider-name');
+    ```
+
+Now all WAL files are encrypted.
 
 ## Next steps
 
diff --git a/documentation/docs/test.md b/documentation/docs/test.md
index 594b704110a..f9711676618 100644
--- a/documentation/docs/test.md
+++ b/documentation/docs/test.md
@@ -68,4 +68,4 @@ To check if the data is encrypted, do the following:
 
 !!! hint
 
-    If you no longer wish to use `pg_tde` or wish to switch to using the `tde_heap_basic` access method, see how you can [decrypt your data](decrypt.md)
\ No newline at end of file
+    If you no longer wish to use `pg_tde` or wish to switch to using the `tde_heap_basic` access method, see how you can [decrypt your data](decrypt.md).
\ No newline at end of file