diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md b/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md index e0edeb4b5de32..aac0c8d2f0680 100644 --- a/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md +++ b/contrib/pg_tde/documentation/docs/command-line-tools/cli-tools.md @@ -1,7 +1,18 @@ # Overview of pg_tde CLI tools -The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. These include: +The `pg_tde` extension introduces new command-line utilities and extends some existing PostgreSQL tools to support encrypted WAL and tables. -* [pg_tde_change_key_provider](../command-line-tools/pg-tde-change-key-provider.md): change encryption key provider for a database -* [pg_waldump](../command-line-tools/pg-waldump.md): inspect and decrypt WAL files -* [pg_checksums](../command-line-tools/pg-tde-checksums.md): verify data checksums (non-encrypted files only) +## New tools + +These tools are introduced by `pg_tde` to support key rotation and WAL encryption workflows: + +* [pg_tde_change_key_provider](./pg-tde-change-key-provider.md): change the encryption key provider for a database +* [pg_tde_archive_decrypt](./pg-tde-archive-decrypt.md): decrypts WAL before archiving +* [pg_tde_restore_encrypt](./pg-tde-restore-encrypt.md): a custom restore command for making sure the restored WAL is encrypted + +## Extended tools + +These existing PostgreSQL tools are enhanced to support `pg_tde`: + +* [pg_checksums](./pg-tde-checksums.md): verify data checksums (non-encrypted files only) +* [pg_waldump](./pg-waldump.md): inspect and decrypt WAL files diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md new file mode 100644 index 0000000000000..0b63ab5212dcf --- /dev/null +++ b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-archive-decrypt.md @@ -0,0 +1,55 @@ +# pg_tde_archive_decrypt + +The `pg_tde_archive_decrypt` tool wraps an archive command and decrypts WAL files before archiving. It allows external tools to access unencrypted WAL data, which is required because WAL encryption keys in the two-key hierarchy are host-specific and may not be available on the replay host. + +!!! tip + + For more information on the encryption architecture and key hierarchy, see [Architecture](../architecture/architcture.md). + +This tool is often used in conjunction with [pg_tde_restore_encrypt](./pg-tde-restore-encrypt.md) to support WAL archive. + +## How it works + +1. Decrypts the WAL segment to a temporary file on a RAM disk (`/dev/shm`) +2. Replaces `%p` and `%f` in the archive command with the path and name of the decrypted file +3. Executes the archive command + +!!! note + + To ensure security, encrypt the files stored in your WAL archive using tools like `PgBackRest`. + +## Usage + +```bash +pg_tde_archive_decrypt [OPTION] +pg_tde_archive_decrypt DEST-NAME SOURCE-PATH ARCHIVE-COMMAND +``` + +## Parameter descriptions + +* `DEST-NAME`: name of the WAL file to send to the archive +* `SOURCE-PATH`: path to the original encrypted WAL file +* `ARCHIVE-COMMAND`: archive command to wrap. `%p` and `%f` are replaced with the decrypted WAL file path and WAL file name, respectively. + +## Options + +* `-V, --version`: show version information, then exit +* `-?, --help`: show help information, then exit + +!!! note + + Any `%f` or `%p` parameter in `ARCHIVE-COMMAND` has to be escaped as `%%f` or `%%p` respectively if used as `archive_command` in `postgresql.conf`. + +## Examples + +### Using `cp` + +```ini +archive_command='pg_tde_archive_decrypt %f %p "cp %%p /mnt/server/archivedir/%%f"' +``` + +### Using `PgBackRest` + +```ini +archive_command='pg_tde_archive_decrypt %f %p "pgbackrest --stanza=your_stanza archive-push %%p"' +``` diff --git a/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md new file mode 100644 index 0000000000000..7435de2d0b761 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/command-line-tools/pg-tde-restore-encrypt.md @@ -0,0 +1,49 @@ +# pg_tde_restore_encrypt + +The `pg_tde_restore_encrypt` tool wraps a normal restore command from the WAL archive and writes them to disk in a format compatible with `pg_tde`. + +!!! note + + This command is often use together with [pg_tde_archive_decrypt](./pg-tde-archive-decrypt.md). + +## How it works + +1. Replaces `%f` and `%p` in the restore command with the WAL file name and temporary file path (in `/dev/shm`) +2. Runs the restore command to fetch the unencrypted WAL from the archive and write it to the temp file +3. Encrypts the temp file and writes it to the destination path in PostgreSQL’s data directory + +## Usage + +```bash +pg_tde_restore_encrypt [OPTION] +pg_tde_restore_encrypt SOURCE-NAME DEST-PATH RESTORE-COMMAND +``` + +## Parameter descriptions + +* `SOURCE-NAME`: name of the WAL file to retrieve from the archive +* `DEST-PATH`: path where the encrypted WAL file should be written +* `RESTORE-COMMAND`: restore command to wrap; `%p` and `%f` are replaced with the WAL file name and path to write the unencrypted WAL, respectively + +## Options + +* `-V, --version`: show version information, then exit +* `-?, --help`: show help information, then exit + +!!! note + + Any `%f` or `%p` parameter in `RESTORE-COMMAND` has to be escaped as `%%f` or `%%p` respectively if used as `restore_command` in `postgresql.conf`. + +## Examples + +### Using `cp` + +```ini +restore_command='pg_tde_restore_encrypt %f %p "cp /mnt/server/archivedir/%%f %%p"' +``` + +### Using `PgBackRest` + +```ini +restore_command='pg_tde_restore_encrypt %f %p "pgbackrest --stanza=your_stanza archive-get %%f \"%%p\""' +``` diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index 43725bb5de5e6..39c1c4eec0330 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -193,11 +193,13 @@ nav: - "Functions": functions.md - "Streaming Replication with tde_heap": replication.md - "TDE operations": - - "pg_tde CLI Tools": + - "pg_tde CLI tools": - "Overview": command-line-tools/cli-tools.md - "pg_tde_change_key_provider": command-line-tools/pg-tde-change-key-provider.md - - "pg_waldump": command-line-tools/pg-waldump.md + - "pg_tde_archive_decrypt": command-line-tools/pg-tde-archive-decrypt.md + - "pg_tde_restore_encrypt": command-line-tools/pg-tde-restore-encrypt.md - "pg_checksums": command-line-tools/pg-tde-checksums.md + - "pg_waldump": command-line-tools/pg-waldump.md - "Uninstall pg_tde": how-to/uninstall.md - "Configure Multi-tenancy": how-to/multi-tenant-setup.md - "Encryption Enforcement": how-to/enforcement.md