Some comments on documentation #436
Conversation
Some comments I had during a cursory read-through of the docs. My comments are prefixed with AÅ:
Codecov ReportAll modified and coverable lines are covered by tests ✅
❌ Your project status has failed because the head coverage (84.65%) is below the target coverage (90.00%). You can increase the head coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## TDE_REL_17_STABLE #436 +/- ##
=====================================================
- Coverage 84.66% 84.65% -0.01%
=====================================================
Files 21 21
Lines 2589 2588 -1
Branches 402 401 -1
=====================================================
- Hits 2192 2191 -1
Misses 316 316
Partials 81 81
🚀 New features to boost your workflow:
|
| @@ -1,5 +1,7 @@ | |||
| # pg_waldump | |||
|
|
|||
| AÅ: We should probably include a notice about WAL encrypting being BETA and this information is subject to change | |||
|
|
|||
| [`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 (WAL) of a PostgreSQL database cluster. | |||
|
|
|||
There was a problem hiding this comment.
Added this note:
The WAL encryption feature is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. Do not enable this feature in production environments.
| @@ -87,6 +87,7 @@ The initial decision on what file to encrypt is based on the table access method | |||
| The principal key is used to encrypt the internal keys. The principal key is stored in the key management store. When you query the table, the principal key is retrieved from the key store to decrypt the table. Then the internal key for that table is used to decrypt the data. | |||
|
|
|||
| ### WAL encryption | |||
| AÅ: We should mention this is a BETA feature and subject to change. | |||
|
|
|||
There was a problem hiding this comment.
Added a note:
WAL encryption is currently in beta and is not effective unless explicitly enabled. It is not yet production ready. Do not enable this feature in production environments.
| @@ -134,6 +136,7 @@ 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 | |||
| AÅ: WAL encrytion is not yet production ready and should probably not be casually mentioned as something you can "turn on". | |||
|
|
|||
There was a problem hiding this comment.
updated this to turn on/off line to:
- when enabling WAL encryption, which is currently in beta. Do not enable this feature in production environments.
| @@ -150,6 +153,7 @@ In `pg_tde`, multi-tenancy is supported via a separate principal key per databas | |||
| To control user access to the databases, you can use role-based access control (RBAC). | |||
|
|
|||
| WAL files are encrypted globally across the entire PostgreSQL cluster using the same encryption keys. Users don't interact with WAL files as these are used by the database management system to ensure data integrity and durability. | |||
| AÅ: Again, WAL encryption hould probably not be mentioned as if it was a feature already. | |||
|
|
|||
There was a problem hiding this comment.
commented the above paragraph out for now regarding WAL
| @@ -117,6 +118,7 @@ The support of other encryption mechanisms such as AES256 is planned for future | |||
| ## Is post-quantum encryption supported? | |||
|
|
|||
| No, it's not yet supported. In our implementation we reply on OpenSSL libraries that don't yet support post-quantum encryption. | |||
| AÅ: Afaik newer versions of openssl support post-quantum algorithms. Maybe we should use some better excuse or mention what version we use? | |||
|
|
|||
There was a problem hiding this comment.
Updated the paragraph to:
No, pg_tde does not support post-quantum encryption.
|
Just wanted to say, appreciate all the great suggestions Anders! |
| @@ -4,6 +4,8 @@ | |||
|
|
|||
| Let's break down what it means. | |||
|
|
|||
| AÅ: We need to make it clear that this file are the ambitions for pg_tde, because a lot of this is not yet in there. | |||
|
|
|||
There was a problem hiding this comment.
So, I wanted to mention that architecture is similar to design here, so I thought why not combine these two. Added the following:
This topic outlines the long-term architectural goals and intended design for pg_tde. While many of the described components are implemented, however some features are still under active development and may not yet be available in the current release.
Let's break down the key building blocks of this design.
| * Single-tenancy support via a global keyring provider | ||
| * Multi-tenancy support | ||
| * Table-level granularity for encryption and access control | ||
| * Multiple Key management options | ||
| * Logical replication of encrypted tables | ||
| AÅ: We do not do anything for logical replication, do we? | ||
|
|
There was a problem hiding this comment.
- Removed temporary tables feature to clear confusion, removed logical replication mention, removed WAL encryption as a feature.
| @@ -36,6 +36,8 @@ The key material (actual cryptographic key) is auto-generated by `pg_tde` and st | |||
| !!! note | |||
| This process sets the **default principal key** for the server. Any database without its own key configuration will use this key. | |||
|
|
|||
| AÅ: This is confusing to me, but maybe makes sense in the rendered version. The Example below does _not_ set a default key, does it? | |||
|
|
|||
| ## Example | |||
|
|
|||
There was a problem hiding this comment.
I have reworded the note and the below example to properly describe the correct param:
- updated with correct code example using set_server_key_using_global parameter
- updated note to reflect correct config
| @@ -10,6 +10,7 @@ However, database owners can run the “view keys” and “set principal key” | |||
|
|
|||
| * `GRANT EXECUTE` | |||
| * `REVOKE EXECUTE` | |||
| AÅ: This should probably say `GRANT EXECUTE ON FUNCTION` and similar for revoke | |||
|
|
|||
There was a problem hiding this comment.
Fixed:
GRANT EXECUTE ON FUNCTIONREVOKE EXECUTE ON FUNCTION
| @@ -52,6 +53,8 @@ The `change` functions require the same parameters as the `add` functions. They | |||
|
|
|||
| Provider specific parameters differ for each implementation. Refer to the respective subsection for details. | |||
|
|
|||
| AÅ: We should probably have a notice here about the modified provider settings will need to be able to provide the exact same principal keys as the original settings. | |||
|
|
|||
There was a problem hiding this comment.
Added the following note for this:
!!! note
The updated provider must be able to retrieve the same principal keys as the original configuration.
If the new configuration cannot access existing keys, encrypted data and backups will become unreadable.
| @@ -231,6 +234,7 @@ These functions list the details of all key providers for the current database o | |||
| ## Principal key management | |||
|
|
|||
| Use these functions to create a new principal key at a given keyprover, and to use those keys for a specific scope such as a current database, a global or default scope. You can also use them to start using a different existing key for a specific scope. | |||
| AÅ: "keyprover"? | |||
|
|
|||
Some comments I had during a cursory read-through of the docs.
My comments are prefixed with AÅ:
Obviously this is never meant to be merged, it's just a way to give comments 🙂