Merge pull request #6342 from EnterpriseDB/transparent_data_encryption/streamlining_docs

TDE: improvements and fixes for DOCS-1147

Author: gvasquezvargas

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

@@ -12,13 +12,13 @@ Create a new EDB Postgres Advanced Server cluster with TDE enabled.
 
 ## Worked example
 
-This example uses EDB Postgres Advanced Server 15 running on a Linux platform. It uses OpenSSL to define the passphrase to wrap and unwrap the generated data encryption key.
+This example uses EDB Postgres Advanced Server 16 running on a Linux platform. It uses OpenSSL to define the passphrase to wrap and unwrap the generated data encryption key.
 
 1. Set the data encryption key (wrap) and decryption (unwrap) environment variables:
 
    ```shell
-   export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass:<password> -out %p'
-   export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:<password> -in %p'
+   export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pbkdf2 -pass pass:<password> -out "%p"'
+   export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:<password> -in "%p"'
    ```
 
    !!!note
@@ -28,21 +28,21 @@ This example uses EDB Postgres Advanced Server 15 running on a Linux platform. I
 1. Initialize the cluster using `initdb` with encryption enabled. This command sets the `data_encryption_key_unwrap_command` parameter in the `postgresql.conf` file.
 
    ```shell
-   /usr/edb/as15/bin/initdb --data-encryption -D /var/lib/edb/as15/data 
+   /usr/edb/as16/bin/initdb --data-encryption -D /var/lib/edb/as16/data 
    ```
 
 1. Start the cluster:
 
    ```shell
-   /usr/edb/as15/bin/pg_ctl -D /var/lib/edb/as15/data start
+   /usr/edb/as16/bin/pg_ctl -D /var/lib/edb/as16/data start
    ```
 
 1. Run grep on `postgresql.conf` to verify the setting of `data_encryption_key_unwrap_command`: 
 
    ```shell
-   grep data_encryption_key_unwrap_command /var/lib/edb/as15/data/postgresql.conf
+   grep data_encryption_key_unwrap_command /var/lib/edb/as16/data/postgresql.conf
    __OUTPUT__
-   data_encryption_key_unwrap_command = 'openssl enc -d -aes-128-cbc -pass pass:<password> -in %p'
+   data_encryption_key_unwrap_command = 'openssl enc -d -aes-128-cbc -pass pass:<password> -in "%p"'
    ```
 
 1.  [Verify that data encryption is enabled](verifying_tde).

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

@@ -54,8 +54,8 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [
 1.  Set environment variables to export the `wrap` and `unwrap` commands:
 
     ```
-    export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass:ok -out %p'
-    export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:ok -in %p'
+    export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pbkdf2 -pass pass:ok -out "%p"'
+    export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:ok -in "%p"'
     ```
 
     !!!note
@@ -109,7 +109,8 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [
     Include the `--copy-by-block` option. 
 
     ```  
-    /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block --check
+    /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin \
+      -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block --check
     ```
 
     !!!note
@@ -118,7 +119,8 @@ Use [pg_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html), [
 1.  To copy data from the source server to the target server, run the `pg_upgrade` command in normal mode: 
 
     ```
-    /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block
+    /usr/lib/edb-as/16/bin/pg_upgrade -b /usr/lib/edb-as/16/bin -B /usr/lib/edb-as/16/bin \
+      -d /var/lib/edb-as/16/non-TDE -D /var/lib/edb-as/16/TDE --copy-by-block
     ```
 
 1.  Restart the encrypted server: 

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

@@ -54,8 +54,8 @@ This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 1
 1.  Set environment variables to export the `wrap` and `unwrap` commands:
 
     ```
-    export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pass pass:ok -out %p'
-    export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pass pass:ok -in %p'
+    export PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pbkdf2 -pass pass:ok -out "%p"'
+    export PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:ok -in "%p"'
     ```
 
     !!!note
@@ -109,7 +109,8 @@ This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 1
     Include the `--copy-by-block` option. 
 
     ```  
-    /usr/lib/edb-pge/16/bin/pg_upgrade -b /usr/lib/postgresql/16/bin -B /usr/lib/edb-pge/16/bin -d /var/lib/postgresql/16/non-TDE -D /var/lib/edb-pge/16/TDE --copy-by-block --check
+    /usr/lib/edb-pge/16/bin/pg_upgrade -b /usr/lib/postgresql/16/bin -B /usr/lib/edb-pge/16/bin \
+      -d /var/lib/postgresql/16/non-TDE -D /var/lib/edb-pge/16/TDE --copy-by-block --check
     ```
 
     !!!note
@@ -118,7 +119,8 @@ This example upgrades a PostgreSQL 16 instance to EDB Postgres Extended Server 1
 1.  To copy data from the source server to the target server, run the `pg_upgrade` command in normal mode: 
 
     ```
-    /usr/lib/edb-pge/16/bin/pg_upgrade -b /usr/lib/postgresql/16/bin -B /usr/lib/edb-pge/16/bin -d /var/lib/postgresql/16/non-TDE -D /var/lib/edb-pge/16/TDE --copy-by-block
+    /usr/lib/edb-pge/16/bin/pg_upgrade -b /usr/lib/postgresql/16/bin -B /usr/lib/edb-pge/16/bin \
+      -d /var/lib/postgresql/16/non-TDE -D /var/lib/edb-pge/16/TDE --copy-by-block
     ```
 
 1.  Restart the encrypted server: 

product_docs/docs/tde/15/encrypted_files/wal_files.mdx

@@ -41,7 +41,8 @@ Alternatively, you can set the `PGDATAKEYUNWRAPCMD` environment variable before
 This example uses `pg_waldump` to display the WAL log of an encrypted cluster that uses `openssl` to wrap the data encryption key: 
 
 ```
-pg_waldump --data-encryption --key-file-name=pg_encryption/key.bin --key-unwrap-command='openssl enc -d -aes-128-cbc -pass pass:<passphrase> -in %p'
+pg_waldump --data-encryption --key-file-name=pg_encryption/key.bin \
+  --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:<passphrase> -in "%p"'
 ```
 
 ## Resetting a corrupt TDE-encrypted WAL file
@@ -59,5 +60,5 @@ Alternatively, you can set the `PGDATAKEYUNWRAPCMD` environment variable before
 This example uses `pg_resetwal` to reset a corrupt encrypted WAL log of an encrypted cluster that uses `openssl` to wrap the data encryption key:
 
 ```
-pg_resetwal --key-unwrap-command='openssl enc -d -aes-128-cbc -pass pass:<passphrase> -in %p'
+pg_resetwal --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -pass pass:<passphrase> -in" "%p"'
 ```

product_docs/docs/tde/15/initdb_tde_options.mdx

@@ -11,7 +11,9 @@ Adds transparent data encryption when initializing a database server.
 
 ### Supported values
 
-You can optionally specify an AES key length. Valid values are 128 and 256. The default is 128.
+You can optionally specify an AES key length in the form of `--data-encryption[=KEYLEN]`. 
+
+Valid values are 128 and 256. The default is 128.
 
 ## Option: `--key-wrap-command=<command>`
 

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

@@ -4,6 +4,12 @@ description: Learn how to omit using a wrapping key.
 deepToc: true
 ---
 
-If you don't want key wrapping, for example for testing, then you must set the wrap and unwrap commands to the special value `-`.
+If you don't want key wrapping, for example, for testing purposes, you can use either one of the following options to disable key wrapping: 
 
-This setting specifies to use the key from the file without further processing. This approach differs from not setting a wrap or unwrap command at all and from setting either or both to an empty string. Having no wrap or unwrap command set when TDE is used leaves your data encryption key unsecured and results in a fatal error when running an affected utility program.
+- You can set the wrap and unwrap commands to the special value `-` when initializing the cluster with `initdb`. For example, with the flags `--key-wrap-command=-` and `--key-unwrap-command=-`.
+
+- Or you can disable key wrapping when initializing the cluster with `initdb` by adding the flag `--no-key-wrap`.
+
+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.

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

@@ -48,8 +48,8 @@ You must make the commands available to the TDE database server so it can wrap a
   <details><summary>Example</summary>
 
   ```shell
-  PGDATAKEYWRAPCMD='openssl enc -e -aes128-wrap -pbkdf2 -out "%p"'
-  PGDATAKEYUNWRAPCMD='openssl enc -d -aes128-wrap -pbkdf2 -in "%p"'
+  PGDATAKEYWRAPCMD='openssl enc -e -aes-128-cbc -pbkdf2 -out "%p"'
+  PGDATAKEYUNWRAPCMD='openssl enc -d -aes-128-cbc -pbkdf2 -in "%p"'
   export PGDATAKEYWRAPCMD PGDATAKEYUNWRAPCMD
   #After these variables are set, you can initialize the server:
   initdb --data-encryption -D /var/lib/edb/as16/data
@@ -63,7 +63,9 @@ You must make the commands available to the TDE database server so it can wrap a
   <details><summary>Example</summary>
 
   ```shell
-  initdb --data-encryption -D /var/lib/edb/as16/data --key-wrap-command='openssl enc -e -aes128-wrap -pbkdf2 -out "%p"' --key-unwrap-command='openssl enc -d -aes128-wrap -pbkdf2 -in "%p"'
+  initdb --data-encryption -D /var/lib/edb/as16/data \
+    --key-wrap-command='openssl enc -e -aes-128-cbc -pbkdf2 -out "%p"' \
+    --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -in "%p"'
   ```
 
   </details>

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

@@ -83,8 +83,8 @@ vault write -f transit/keys/pg-tde-master-1
 Use the `vault write` command with the `pg-tde-master-1` key to wrap and unwrap the data encryption key:
 
 ```
-PGDATAKEYWRAPCMD='base64 | vault write -field=ciphertext transit/encrypt/pg-tde-master-1 plaintext=- > %p'
-PGDATAKEYUNWRAPCMD='vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- < %p | base64 -d'
+PGDATAKEYWRAPCMD='base64 | vault write -field=ciphertext transit/encrypt/pg-tde-master-1 plaintext=- > "%p"'
+PGDATAKEYUNWRAPCMD='vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- < "%p" | base64 -d'
 ```
 
 ## Thales CipherTrust Manager example 

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

@@ -6,7 +6,9 @@ description: Learn how to secure your encryption key with a passphrase.
 You can protect the data key with a passphrase using the OpenSSL command line utility. The following is an example that sets up this protection:
 
 ```shell
-initdb -D datadir -y --key-wrap-command='openssl enc -e -aes-128-cbc -pbkdf2 -out "%p"' --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -in "%p"'
+initdb -D datadir --data-encryption \
+  --key-wrap-command='openssl enc -e -aes-128-cbc -pbkdf2 -out "%p"' \
+  --key-unwrap-command='openssl enc -d -aes-128-cbc -pbkdf2 -in "%p"'
 ```
 
 This example wraps the randomly generated data key (done internally by initdb) by encrypting it with the AES-128-CBC (AESKW) algorithm. The encryption uses a key derived from a passphrase with the PBKDF2 key derivation function and a randomly generated salt. The terminal prompts for the passphrase. (See the openssl-enc manual page for details about these options. Available options vary across versions.) The initdb utility replaces `%p` with the name of the file that stores the wrapped key.
@@ -30,8 +32,8 @@ Key unwrap commands that prompt for passwords on the terminal don't work when th
 For example, for systemd, you can use `systemd-ask-password`:
 
 ```
-PGDATAKEYWRAPCMD="bash -c 'openssl enc -e -aes-128-cbc -pbkdf2 -out %p -pass file:<(sudo systemd-ask-password --no-tty)'"
-PGDATAKEYUNWRAPCMD="bash -c 'openssl enc -d -aes-128-cbc -pbkdf2 -in %p -pass file:<(sudo systemd-ask-password --no-tty)'"
+PGDATAKEYWRAPCMD="bash -c 'openssl enc -e -aes-128-cbc -pbkdf2 -out "%p" -pass file:<(sudo systemd-ask-password --no-tty)'"
+PGDATAKEYUNWRAPCMD="bash -c 'openssl enc -d -aes-128-cbc -pbkdf2 -in "%p" -pass file:<(sudo systemd-ask-password --no-tty)'"
 ```
 
 You also need an entry like in `/etc/sudoers`: