diff --git a/contrib/pg_tde/documentation/docs/advanced-topics/index.md b/contrib/pg_tde/documentation/docs/advanced-topics/adv-top-overview.md similarity index 63% rename from contrib/pg_tde/documentation/docs/advanced-topics/index.md rename to contrib/pg_tde/documentation/docs/advanced-topics/adv-top-overview.md index 9df169821bcd3..f52e01b97b378 100644 --- a/contrib/pg_tde/documentation/docs/advanced-topics/index.md +++ b/contrib/pg_tde/documentation/docs/advanced-topics/adv-top-overview.md @@ -4,4 +4,4 @@ This section covers the internal components and tools that power `pg_tde`. Use it to understand how encryption is implemented, fine-tune a configuration, leverage advanced CLI tools and functions for diagnostics and customization. -[Architecture](../architecture/index.md){.md-button} [GUC Variables](../variables.md){.md-button} [Functions](../functions.md){.md-button} +[Architecture](../architecture/architecture.md){.md-button} [GUC Variables](../variables.md){.md-button} [Functions](../functions.md){.md-button} diff --git a/contrib/pg_tde/documentation/docs/architecture/index.md b/contrib/pg_tde/documentation/docs/architecture/architecture.md similarity index 100% rename from contrib/pg_tde/documentation/docs/architecture/index.md rename to contrib/pg_tde/documentation/docs/architecture/architecture.md diff --git a/contrib/pg_tde/documentation/docs/faq.md b/contrib/pg_tde/documentation/docs/faq.md index 902e0a18b49fc..e1256e8b59f51 100644 --- a/contrib/pg_tde/documentation/docs/faq.md +++ b/contrib/pg_tde/documentation/docs/faq.md @@ -133,17 +133,17 @@ Since the `SET ACCESS METHOD` command drops hint bits and this may affect the pe You must restart the database in the following cases to apply the changes: * after you enabled the `pg_tde` extension -* to turn on / off the WAL encryption +* to turn WAL encryption on or off After that, no database restart is required. When you create or alter the table using the `tde_heap` access method, the files are marked as those that require encryption. The encryption happens at the storage manager level, before a transaction is written to disk. Read more about [how tde_heap works](index/table-access-method.md#how-tde_heap-works). ## What happens to my data if I lose a principal key? -If you lose encryption keys, especially, the principal key, the data is lost. That's why it's critical to back up your encryption keys securely and use the Key Management service for key management. +If you lose encryption keys, especially the principal key, the data is **lost**. It is critical to back up your encryption keys securely and use the Key Management service for key management. For more information, see the [Configure Key Management (KMS)](../docs/global-key-provider-configuration/index.md) topic. ## Can I use `pg_tde` in a multi-tenant setup? -Multi-tenancy is the type of architecture where multiple users, or tenants, share the same resource. It can be a database, a schema or an entire cluster. +Yes. Multi-tenancy is the type of architecture where multiple users, or tenants, share the same resource. It can be a database, a schema or an entire cluster. In `pg_tde`, multi-tenancy is supported via a separate principal key per database. This means that a database owner can decide what tables to encrypt within a database. The same database can have both encrypted and non-encrypted tables. @@ -157,7 +157,15 @@ WAL files are encrypted globally across the entire PostgreSQL cluster using the Since the encryption happens on the database level, it makes no difference for your tools and applications. They work with the data in the same way. -To restore from an encrypted backup, you must have the same principal encryption key, which was used to encrypt files in your backup. +To restore from an encrypted backup, you must have the same principal encryption key, which was used to encrypt files in your backup. See the [Restore an encrypted pg_tde backup](../docs/how-to/restore-backups.md) topic for more details. + +## What if the address of the key provider changed for one of my old backups? + +You can use the [pg_tde_change_key_provider](../docs/command-line-tools/pg-tde-change-key-provider.md) tool to correct the configuration. + +## How can I store an old key securely? + +To store an old key securely, see the [Configure Key Management (KMS)](../docs/global-key-provider-configuration/index.md) topic. ## I'm using OpenSSL in FIPS mode and need to use `pg_tde`. Does `pg_tde` comply with FIPS requirements? Can I use my own FIPS-mode OpenSSL library with `pg_tde`? diff --git a/contrib/pg_tde/documentation/docs/how-to/restore-backups.md b/contrib/pg_tde/documentation/docs/how-to/restore-backups.md new file mode 100644 index 0000000000000..c5d0f38383d55 --- /dev/null +++ b/contrib/pg_tde/documentation/docs/how-to/restore-backups.md @@ -0,0 +1,16 @@ +# Restoring encrypted backups + +To restore an encrypted backup created with an earlier key, ensure the key is still available in your Key Management System (KMS). The backup remains **encrypted** on disk, `pg_tde` uses the correct key to transparently access the data. + +Each encrypted table stores metadata that identifies which encryption key was used. When the encrypted data is read, `pg_tde` retrieves the correct key from the configured KMS. + +## How `pg_tde` uses old keys to load backups + +* **KMS**: stores the key that was active when the backup was made. +* **Encrypted backup**: contains data encrypted with the key available at that time. +* **Current server**: `pg_tde` automatically loads the backup if the key is accessible through the KMS. + +At runtime, `pg_tde` reads the key ID from the table metadata and fetches the corresponding key from the KMS. + +!!! note + If the key was deleted or the KMS configuration changed, the backup **cannot** be read. Use [pg_tde_change_key_provider](../command-line-tools/pg-tde-change-key-provider.md) to update KMS credentials or endpoints if needed. diff --git a/contrib/pg_tde/documentation/docs/wal-encryption.md b/contrib/pg_tde/documentation/docs/wal-encryption.md index 21f37ed73ae85..d63e6b7de2075 100644 --- a/contrib/pg_tde/documentation/docs/wal-encryption.md +++ b/contrib/pg_tde/documentation/docs/wal-encryption.md @@ -88,4 +88,4 @@ Before turning WAL encryption on, you must follow the steps below to create your Now WAL files start to be encrypted for both encrypted and unencrypted tables. For more technical references related to architecture, variables or functions, see: -[Technical Reference](advanced-topics/index.md){.md-button} +[Technical Reference](advanced-topics/adv-top-overview.md){.md-button} diff --git a/contrib/pg_tde/documentation/mkdocs.yml b/contrib/pg_tde/documentation/mkdocs.yml index ab8c6e25236ff..054a2cf3e2a71 100644 --- a/contrib/pg_tde/documentation/mkdocs.yml +++ b/contrib/pg_tde/documentation/mkdocs.yml @@ -178,8 +178,8 @@ nav: - "3. Validate Encryption with pg_tde": test.md - "4. Configure WAL Encryption (tech preview)": wal-encryption.md - "Technical Reference": - - "Technical Reference": advanced-topics/index.md - - "Architecture": architecture/index.md + - "Overview": advanced-topics/adv-top-overview.md + - "Architecture": architecture/architecture.md - "GUC Variables": variables.md - "Functions": functions.md - "TDE Operations": @@ -191,6 +191,7 @@ nav: - "Uninstall pg_tde": how-to/uninstall.md - "Configure Multi-tenancy": how-to/multi-tenant-setup.md - "Decrypt an Encrypted Table": how-to/decrypt.md + - "Restore an encrypted pg_tde backup": how-to/restore-backups.md - faq.md - "Release Notes": - "pg_tde release notes": release-notes/release-notes.md