Merge pull request #6354 from EnterpriseDB/release/2024-12-17a

Release: 2024-12-17a

product_docs/docs/pgd/5.6/upgrades/upgrade_paths.mdx

@@ -4,6 +4,9 @@ title: Supported PGD upgrade paths
 
 ## Upgrading within version 5
 
+EDB Postgres Distributed uses [semantic versioning](https://semver.org/). 
+All changes within the same major version are backward compatible, lowering the risk when upgrading and allowing you to choose any later minor or patch release as the upgrade target. 
+
 You can upgrade from any version 5.x release to a later 5.x release. 
 
 ## Upgrading from version 4 to version 5

product_docs/docs/tde/15/enabling/enabling_key_wrapper.mdx

@@ -0,0 +1,70 @@
+---
+title: "Protect the data encryption key on an existing TDE cluster" 
+description: Learn how to enable a mechanism to protect the data encryption key on an existing TDE-enabled database cluster.
+---
+
+If you want to enable key wrapping on TDE-enabled database clusters where key wrapping was previously disabled, update the encryption settings in the `postgresql.conf` file.
+
+## Context 
+
+When you create a TDE-enabled database cluster, `initdb` generates a data encryption key and stores it in `pg_encryption/key.bin`. Since this file is stored in plaintext, TDE requires an additional mechanism to [secure the data encryption key](../secure_key/). You normally configure the protection of the key as you initialize your TDE-enabled database cluster.
+
+However, you can chose to [disable key wrapping](../secure_key/disabling_key) for your data encryption key. Although this setup is not recommended, you might have chosen to leave your key unprotected to facilitate managing the cluster for testing or demo purposes.
+
+If you disabled key wrapping, but later decide to enable a mechanism that secures your encryption key, you can enable it at a later time, by updating the encryption settings in the `postgresql.conf` file.
+
+## Enable key wrapping with a passphrase
+
+This example walks you through adding a passphrase-based protection mechanism or key wrapping to your data encryption key (`key.bin`).
+
+1.  Store the passphrase in a file accessible by initdb named `pass.bin`:
+
+    !!!important 
+       This example stores the passphrase in plaintext, a method you should only use for testing or demonstration purposes. In production environments, don't store your passphrase in a file. See [Using a passphrase](../secure_key/passphrase) for alternative methods.
+    !!!
+
+    ```
+    echo "<passphrase>" > /var/lib/postgresql/pass.bin
+    ```
+
+1.  Use OpenSSL to encrypt the existing `key.bin` data encryption key with the stored passphrase and save the encrypted file as `key.bin.WRAP`:
+
+    ```
+    cat $PGDATA/pg_encryption/key.bin | openssl enc -e -aes-128-cbc -pbkdf2 -pass file:/var/lib/postgresql/pass.bin -out $PGDATA/pg_encryption/key.bin.WRAP
+    ```
+
+1.  Create a backup of the unwrapped data encryption key named `key.bin.NOWRAP` in case you need to roll back to the original configuration:
+
+    ```
+    cp $PGDATA/pg_encryption/key.bin $PGDATA/pg_encryption/key.bin.NOWRAP
+    ```
+
+1.  Replace the existing data encryption key with the wrapped version:
+
+    ```
+    cp $PGDATA/pg_encryption/key.bin.WRAP $PGDATA/pg_encryption/key.bin
+    ```
+
+1.  Create a backup of the existing configuration file named `postgresql.conf.NOWRAP` in case you need to roll back to the original configuration:
+
+    ```
+    cp $PGDATA/postgresql.conf $PGDATA/postgresql.conf.NOWRAP
+    ```
+
+1.  Modify the `data_encryption_key_unwrap_command` value of the `postgresql.conf` file with the new command:
+
+    ```
+    sed -i "s|data_encryption_key_unwrap_command.*|data_encryption_key_unwrap_command = 'openssl enc -d -aes-128-cbc -pbkdf2 -pass file:/var/lib/postgresql/pass.bin -in \"%p\"'|" $PGDATA/postgresql.conf
+    ```
+
+1.  Create a backup of the modified `postgresql.conf` file that includes the key wrapping named `postgresql.conf.WRAP`:
+
+    ```
+    cp $PGDATA/postgresql.conf $PGDATA/postgresql.conf.WRAP
+    ```
+
+1.  Restart your database cluster to populate the updated data encryption key configuration:
+
+    ```
+    pg_ctl start
+    ```  

product_docs/docs/tde/15/enabling/index.mdx

@@ -5,6 +5,9 @@ indexCards: simple
 navigation: 
  - enabling_tde
  - enabling_tde_epas
+ - postgres_to_extended
+ - enabling_key_wrapper
+ - verifying_tde
 ---
 
 Create a TDE-enabled database server using `initdb`.

product_docs/docs/tde/15/secure_key/disabling_key.mdx

@@ -13,3 +13,7 @@ If you don't want key wrapping, for example, for testing purposes, you can use e
 With either one of the configurations, TDE generates encryption key files, but leaves them unprotected.
 
 For `intidb --data-encryption` to run successfully, you have to either specify a wrapping/unwrapping command, set a fallback environment variable with wrapping/unwrapping commands, or disable key wrapping with the one of the previous mechanisms. Otherwise, the creation of an encrypted database cluster will fail.
+
+!!!note
+If you want to enable key wrapping on TDE-enabled database clusters where key wrapping was previously disabled, see [Enabling a mechanism to protect the data encryption key](../enabling/enabling_key_wrapper).
+!!!

product_docs/docs/tde/15/secure_key/passphrase.mdx

@@ -19,6 +19,8 @@ The key wrap command receives the plaintext key on standard input and needs to p
 
 Utility programs like pg_rewind and pg_upgrade operate directly on the data directory or copies, such as backups. These programs also need to be told about the key unwrap command, depending on the circumstances. They each have command line options for this purpose.
 
+## Using environment variables to set wrap and unwrap commands
+
 To simplify operations, you can also set the key wrap and unwrap commands in environment variables. These are accepted by all affected applications if you don't provide the corresponding command line options. For example:
 
 ```shell
@@ -40,4 +42,26 @@ You also need an entry like in `/etc/sudoers`:
 
 ```
 postgres ALL = NOPASSWD: /usr/bin/systemd-ask-password
-```
+```
+
+## Providing the passphrase through a file
+
+Another way to simplify operations is to store the passphrase in plaintext, so you can reference the file containing the passphrase when securing the data encryption files.
+
+!!!important
+   You should only use this method for testing or demonstration purposes. Don't store your passphrase in a plaintext file for production environments.
+!!!
+
+1.  Store the passphrase in a file accessible by initdb named `pass.bin`:
+
+    ```
+    echo "<passphrase>" > /var/lib/postgresql/pass.bin
+    ```
+
+1.  Reference the file that contains the passphrase when initializing the TDE-enabled database cluster using the `-pass file:<path_to_file>` flag: 
+
+    ```
+    initdb --data-encryption \
+      --key-wrap-command='openssl enc -e -aes-128-cbc -pbkdf2 -pass file:/var/lib/postgresql/pass.bin -out "%p"' \
+      --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -pass file:/var/lib/postgresql/pass.bin -in "%p"'
+    ```