PG-1206 Reworked intro to pg_tde (#353)

* PG-1206 Reworked intro to pg_tde


---------

Co-authored-by: Artem Gavrilov <[email protected]>

documentation/docs/faq.md

@@ -0,0 +1,30 @@
+# FAQ
+
+## Why do I need TDE?
+
+- Compliance to security and legal regulations like GDPR, PCI DSS and others
+- Encryption of backups
+- Granular encryption of specific data sets and reducing the performance overhead that encryption brings
+- Additional layer of security to existing security measures
+
+## I use disk-level encryption. Why should I care about TDE?
+
+Encrypting a hard drive encrypts all data including system and application files that are there. However, disk encryption doesn’t protect your data after the boot-up of your system. During runtime, the files are decrypted with disk-encryption.
+
+TDE focuses specifically on data files and offers a more granular control over encrypted data. It also ensures that files are encrypted on disk during runtime and when moved to another system or storage.
+
+Consider using TDE and storage-level encryption together to add another layer of data security
+
+## Is TDE enough to ensure data security?
+
+No. TDE is an additional layer to ensure data security. It protects data at rest. Consider introducing also these measures:
+
+* Access control and authentication
+* Strong network security like TLS
+* Disk encryption
+* Regular monitoring and auditing
+* Additional data protection for sensitive fields (e.g., application-layer encryption)
+
+## 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.

documentation/docs/index.md

@@ -1,8 +1,10 @@
 # `pg_tde` documentation
 
-`pg_tde` is the extension that brings in [Transparent Data Encryption (TDE)](tde.md) to PostgreSQL and enables users to keep sensitive data safe and secure. The encryption is transparent for users allowing them to access and manipulate the data and not to worry about the encryption process.
+`pg_tde` is the open source PostgreSQL extension that provides Transparent Data Encryption (TDE) to protect data at rest. This ensures that the data stored on disk is encrypted, and no one can read it without the proper encryption keys, even if they gain access to the physical storage media. 
 
-Users can configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys, while keeping others non encrypted. 
+You can configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys while keeping others unencrypted.
+
+Lear more [what is Transparent Data Encryption](tde.md#how-does-it-work) and [why you need it](tde.md#why-do-you-need-tde).
 
 !!! important 
 
@@ -22,7 +24,7 @@ Users can configure encryption differently for each database, encrypting specifi
 
 ## Known limitations
 
-* Keys in the local keyfile are stored unencrypted.
+* Keys in the local keyfile are stored unencrypted. For better security we recommend using the Key management storage. 
 * System tables are currently not encrypted.
 
 <i warning>:material-alert: Warning:</i> Note that introducing encryption/decryption affects performance. Our benchmark tests show less than 10% performance overhead for most situations. However, in some specific applications such as those using JSONB operations, performance degradation might be higher.
@@ -41,7 +43,7 @@ The `pg_tde` extension comes in two distinct versions with specific access metho
 
 ### Which version to chose?
 
-The answer is pretty straightforward: if you don't use indexes and don't need index encryption, use the community version and the `tde_heap_basic` access method. Check the [upstream documentation :octicons-link-external-16:](https://github.com/percona/pg_tde/blob/main/README.md) how to get started.
+The answer is pretty straightforward: for data sets where indexing is not mandatory or index encryption is not required, use the community version and the `tde_heap_basic` access method. Check the [upstream documentation :octicons-link-external-16:](https://github.com/percona/pg_tde/blob/main/README.md) how to get started.
 
 Otherwise, enjoy full encryption with the Percona Server for PostgreSQL version and the `tde_heap` access method. 
 
@@ -55,10 +57,3 @@ The following is planned for future releases of `pg_tde`:
 
 * KMIP integration for key management
 * Global principal key management
-
-
-
-## Useful links
-
-* [What is Transparent Data Encryption](tde.md)
-

documentation/docs/setup.md

@@ -42,10 +42,12 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
 
 ## Key provider configuration
 
-1. Set up a key provider for the database where you have enabled the extension
+1. Set up a key provider for the database where you have enabled the extension.
 
     === "With HashiCorp Vault"
 
+        The Vault server setup is out of scope of this document.
+
         ```
         SELECT pg_tde_add_key_provider_vault_v2('provider-name',:'secret_token','url','mount','ca_path');
         ``` 
@@ -66,7 +68,7 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file');
         ```
 
-	<i warning>:material-information: Warning:</i> Example for testing purposes only:
+	<i warning>:material-information: Warning:</i> This example is for testing purposes only:
 
 	```
 	SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_local_keyring.per');
@@ -79,12 +81,14 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
     SELECT pg_tde_set_principal_key('name-of-the-principal-key', 'provider-name');
     ```
 
-    <i warning>:material-information: Warning:</i> Example for testing purposes only:
+    <i warning>:material-information: Warning:</i> This example is for testing purposes only:
 
     ```
     SELECT pg_tde_set_principal_key('test-db-master-key','file-vault');
     ```
 
+    The key is auto-generated.
+
    <i info>:material-information: Info:</i> The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup.
 
 

documentation/docs/tde.md

@@ -1,21 +1,21 @@
 # What is Transparent Data Encryption (TDE)
 
-Transparent Data Encryption offers encryption at the file level and solves the problem of protecting data at rest. The encryption is transparent for users allowing them to access and manipulate the data and not to worry about the encryption process.
+Transparent Data Encryption is a technology to protect data at rest. The encryption process happens transparently in the background, without affecting database operations. Data is automatically encrypted as it's written to the disk and decrypted as it's read, all in real-time. Users and applications interact with the data as usual without noticing any difference.
 
 ## How does it work?
 
 To encrypt the data, two types of keys are used:
 
-* Database keys to encrypt user data. These are stored internally, near the data that they encrypt.
-* The principal key to encrypt database keys. It is kept separately from the database keys and is managed externally. 
+* Table encryption keys (TEK) to encrypt user data. These keys are stored internally, near the data that they encrypt.
+* The principal key to encrypt table keys. It is kept separately from the table keys and is managed externally. 
 
 `pg_tde` is integrated with HashiCorp Vault server to store and manage principal keys. Only the back end KV Secrets Engine - Version 2 (API) is supported.
 
 The encryption process is the following:
 
 ![image](_images/tde-flow.png)
 
-When a user creates an encrypted table using `pg_tde`, a new random key is generated for that table. This key is used to encrypt all data the user inserts in that table. Eventually the encrypted data gets stored in the underlying storage. 
+When a user creates an encrypted table using `pg_tde`, a new random key is generated for that table using the AES128 (AES-ECB) cipher algorithm. This key is used to encrypt all data the user inserts in that table. Eventually the encrypted data gets stored in the underlying storage. 
 
 The table itself is encrypted using the principal key. The principal key is stored externally in the Vault key management store. 
 
@@ -27,13 +27,13 @@ Using TDE has the following benefits:
 
 * For organizations:
 
-    - Ensure data safety when at rest and in motion
-    - Comply with security standards like HIPAA, PCI DSS, SOC 2, ISO 27001
+    - Ensure data safety when it is stored on disk and in backups
+    - Comply with security and legal standards like HIPAA, PCI DSS, SOC 2, ISO 27001
 
 * For DBAs:
 
-    - Allows defining what to encrypt in the table and with what key
-    - Encryption on storage level is not a must to provide data safety. However, using TDE and storage-level encryption together adds another layer of data security
+    - Granular encryption of specific tables and reducing the performance overhead that encryption brings
+    - Additional layer of security to existing security measures like storage-level encryption, data encryption in transit using TLS, access control and more.
 
 !!! admonition "See also"
 

documentation/docs/test.md

@@ -2,10 +2,6 @@
 
 Enabling `pg_tde` extension for a database creates the table access method `tde_heap` . This access method enables you to encrypt the data.
 
-!!! warning
-
-    This is the tech preview functionality. Its scope is not yet finalized and can change anytime. **Use it only for testing purposes.**
-
 Here's how to do it:
 
 1. Create a table in the database for which you have [enabled `pg_tde`](setup.md) using the `tde_heap` access method as follows:

documentation/mkdocs.yml

@@ -169,6 +169,7 @@ nav:
   - How to:
     - Use reference to external parameters: external-parameters.md
     - Decrypt an encrypted table: decrypt.md
+  - faq.md
   - Release notes:
     - "pg_tde release notes": release-notes/release-notes.md
   - uninstall.md