diff --git a/contrib/pg_tde/documentation/docs/command-line-tools.md b/contrib/pg_tde/documentation/docs/command-line-tools.md new file mode 100644 index 0000000000000..e5b2763529bd4 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/command-line-tools.md @@ -0,0 +1,60 @@ +# Command line tools + +The `pg_tde` extension provides new command line tools and modifies some existing tools to work with encrypted WAL and tables. + +## pg_tde_change_key_provider + +A tool for modifying the configuration of a key provider, possibly also changing its type. + +This tool edits the configuration files directly, ignoring permissions or running `postgres` processes. + +Its only intended use is to fix servers that can't start up because of inaccessible key providers. + +For example, you restore from an old backup and the address of the key provider changed in the meantime. You can use this tool to correct the configuration, allowing the server to start up. + +Use this tool **only when the server is offline.** To modify the key provider configuration when the server is up and running, use the [`pg_tde_change_key_provider_`](functions.md#change-an-existing-provider) SQL functions. + +### Usage + +To modify the key provider configuration, specify all parameters depending on the provider type in the same way as you do when using the [`pg_tde_change_key_provider_`](functions.md#change-an-existing-provider) SQL functions. + +The general syntax is as follows: + +``` +pg_tde_change_key_provider [-D ] +``` + +where : + +* [optional] `` is the data directory. When not specified, `pg_tde` uses the `$PGDATA` value. +* `` is the name you assigned to the key provider +* `` can be a `file`, `vault` or `kmip`. +* `` + + +Depending on the provider type, the additional parameters are: + +``` +pg_tde_change_key_provider [-D ] file +pg_tde_change_key_provider [-D ] vault [] +pg_tde_change_key_provider [-D ] kmip [] +``` + +## pg_waldump + +[`pg_waldump` :octicons-link-external-16:](https://www.postgresql.org/docs/current/pgwaldump.html) is a tool to display a human-readable rendering of the write-ahead log of a PostgreSQL database cluster. + +To read encrypted WAL records, `pg_waldump` supports the following additional arguments: + +* `keyring_path`: the directory where keyring config files for WAL are stored. These files are: + + * `pg_tde.map`, + * `pg_tde.dat`, + * `pg_tde_keyrings` + +`pg_waldump` will not try to decrypt WAL if the `keyring_path` is not set. + +## pg_checksums + +[`pg_checksums` :octicons-link-external-16:](https://www.postgresql.org/docs/current/app-pgchecksums.html) cannot calculate checksums for encrypted files. +It skips encrypted files and reports this in the output. diff --git a/contrib/pg_tde/documentation/docs/decrypt.md b/contrib/pg_tde/documentation/docs/decrypt.md index 5ce489c34d9d1..1aafcca361e35 100644 --- a/contrib/pg_tde/documentation/docs/decrypt.md +++ b/contrib/pg_tde/documentation/docs/decrypt.md @@ -1,14 +1,14 @@ -# Decrypt an encrypted table +# Remove encryption from an encrypted table ## Method 1. Change the access method -If you encrypted a table with the `tde_heap` access method and need to decrypt it, run the following command against the desired table (`mytable` in the example below): +If you encrypted a table with the `tde_heap` access method and need to remove the encryption from it, run the following command against the desired table (`mytable` in the example below): ``` ALTER TABLE mytable SET ACCESS METHOD heap; ``` -Note that the `SET ACCESS METHOD` command drops hint bits and this may affect the performance. Running a plain `SELECT count(*)` or `VACUUM` commands on the entire table will check every tuple for visibility and set its hint bits. Therefore, after executing the `ALTER TABLE` command, run a simple `count(*)` on your tables: +Note that the `SET ACCESS METHOD` command drops hint bits and this may affect performance. Running a plain `SELECT count(*)` or `VACUUM` command on the entire table will check every tuple for visibility and set its hint bits. Therefore, after executing the `ALTER TABLE` command, run a simple `count(*)` on your tables: ``` SELECT count(*) FROM mytable; @@ -24,9 +24,9 @@ The output returns `f` meaning that the table is no longer encrypted. -## Method 2. Create a new unencrypted table on the base of the encrypted one +## Method 2. Create a new not encrypted table on the base of the encrypted one -Alternatively, you can create a new unencrypted table with the same structure and data as the initial table. For example, the original encrypted table is `EncryptedCustomers`. Use the following command to create a new table `Customers`: +Alternatively, you can create a new not encrypted table with the same structure and data as the initial table. For example, the original encrypted table is `EncryptedCustomers`. Use the following command to create a new table `Customers`: ``` CREATE TABLE Customers AS diff --git a/contrib/pg_tde/documentation/docs/uninstall.md b/contrib/pg_tde/documentation/docs/uninstall.md index 3d997f24c6bea..3005d249416e2 100644 --- a/contrib/pg_tde/documentation/docs/uninstall.md +++ b/contrib/pg_tde/documentation/docs/uninstall.md @@ -1,27 +1,39 @@ # Uninstall `pg_tde` -If you no longer wish to use TDE in your deployment, you can remove the `pg_tde` extension. To do that, your user must have the superuser privileges or a database owner. +If you no longer wish to use TDE in your deployment, you can remove the `pg_tde` extension. To do so, your user must have the superuser privileges, or a database owner privileges in case you only want to remove it from a single database. Here's how to do it: -1. Drop the extension using the `DROP EXTENSION` with `CASCADE` command. +1. Drop the extension using the `DROP EXTENSION` command: - :material-alert: Warning: 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). + ``` + DROP EXTENSION pg_tde; + ``` - ``` - DROP EXTENSION pg_tde CASCADE - ``` + This command will fail if there are still encrypted tables in the database. -2. Run the `DROP EXTENSION` command against every database where you have enabled the `pg_tde` extension + In this case, you must drop the dependent objects manually. Alternatively, you can run the `DROP EXTENSION ... CASCADE` command to drop all dependent objects automatically. -3. Modify the `shared_preload_libraries` and remove the 'pg_tde' from it. Use the `ALTER SYSTEM` command for this purpose + Note that the `DROP EXTENSION` command does not delete the `pg_tde` data files related to the database. -4. Start or restart the `postgresql` cluster to apply the changes. +2. Run the `DROP EXTENSION` command against every database where you have enabled the `pg_tde` extension, if the goal is to completely remove the extension. This also includes the template databases, in case `pg_tde` was previously enabled there. + +3. Remove any reference to `pg_tde` GUC variables from the PostgreSQL configuration file. + +4. Modify the `shared_preload_libraries` and remove the 'pg_tde' from it. Use the `ALTER SYSTEM` command for this purpose, or edit the configuration file. + + !!! warning + + Once `pg_tde` is removed from the `shared_preload_libraries`, reading any leftover encrypted files will fail. Removing the extension from the `shared_preload_libraries` is also possible if the extension is still installed in some databases. + + Make sure to do this only if the server has no encrypted files in its data directory. + +5. Start or restart the `postgresql` cluster to apply the changes. * On Debian and Ubuntu: ```sh - sudo systemctl restart postgresql-17 + sudo systemctl restart postgresql ``` * On RHEL and derivatives diff --git a/contrib/pg_tde/documentation/docs/variables.md b/contrib/pg_tde/documentation/docs/variables.md new file mode 100644 index 0000000000000..9947eacc385fe --- /dev/null +++ b/contrib/pg_tde/documentation/docs/variables.md @@ -0,0 +1,63 @@ +# GUC Variables + +The `pg_tde` extension provides GUC variables to configure the behaviour of the extension: + +## pg_tde.wal_encrypt + +**Type** - boolean
+**Default** - off + +A `boolean` variable that controls if WAL writes are encrypted or not. + +Changing this variable requires a server restart, and can only be set at the server level. + +WAL encryption is controlled globally. If enabled, all WAL writes are encrypted in the entire PostgreSQL cluster. + +This variable only controls new writes to the WAL, it doesn't affect existing WAL records. + +`pg_tde` is always capable of reading existing encrypted WAL records, as long as the keys used for the encryption are still available. + +Enabling WAL encryption requires a configured global principal key. Refer to the [WAL encryption configuration](wal-encryption.md) documentation for more information. + +## pg_tde.enforce_encryption + +**Type** - boolean
+**Default** - off + +A `boolean` variable that controls if the creation of new, not encrypted tables is allowed. + +If enabled, `CREATE TABLE` statements will fail unless they use the `tde_heap` access method. + +Similarly, `ALTER TABLE SET ACCESS METHOD` is only allowed, if the access method is `tde_heap`. + +Other DDL operations are still allowed. For example other `ALTER` commands are allowed on unencrypted tables, as long as the access method isn't changed. + +You can set this variable at the following levels: + +* global - for the entire PostgreSQL cluster. +* database - for specific databases. +* user - for specific users. +* session - for the current session. + +Setting or changing the value requires superuser permissions. + +## pg_tde.inherit_global_providers + +**Type** - boolean
+**Default** - on + +A `boolean` variable that controls if databases can use global key providers for storing principal keys. + +If disabled, functions that change the key providers can only work with database local key providers. + +In this case, the default principal key, if set, is also disabled. + +You can set this variable at the following levels: + +* global - for the entire PostgreSQL cluster. +* database - for specific databases. +* user - for specific users. +* session - for the current session. + + +Setting this variable doesn't affect existing uses of global keys. It only prevents the creation of new principal keys using global providers. diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index fc137b1359182..04ca88e23887a 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -166,6 +166,8 @@ nav: - "3. Configure WAL encryption (tech preview)": wal-encryption.md - "4. Test TDE": "test.md" - functions.md + - command-line-tools.md + - variables.md - Concepts: - "What is TDE": tde.md - table-access-method.md