Skip to content

Commit

Permalink
PG-1320 Updatd considerations in installation
Browse files Browse the repository at this point in the history 
Added KMIP server to the list of options

Updated formatting for using the count(*) in docs

modified:   documentation/docs/decrypt.md
	modified:   documentation/docs/index.md
	modified:   documentation/docs/install.md
	modified:   documentation/docs/setup.md
	modified:   documentation/docs/test.md
  • Loading branch information
@nastena1606
nastena1606 committed Feb 4, 2025
1 parent b8d8702 commit f7f21f5
Show file tree
Hide file tree
Showing 5 changed files with 50 additions and 34 deletions.
19 changes: 10 additions & 9 deletions documentation/docs/decrypt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ If you encrypted a table with the `tde_heap` or `tde_heap_basic` access method a
ALTER TABLE mytable SET access method heap;
```

!!! hint
The ALTER TABLE <tablename> SET access method statement removes the [hint bits :octicons-link-external-16:](https://wiki.postgresql.org/wiki/Hint_Bits). This removal can lead to heavy writes to the database table, even if you're just reading from it.
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 command, run a simple "count(*)" on your tables:
```
Note that the `ALTER TABLE SET` 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 command, run a simple "count(*)" on your tables:

```
SELECT COUNT(*) FROM mytable;
```

Check that the table is not encrypted:

Expand All @@ -32,11 +32,12 @@ The output returns `f` meaning that the table is no longer encrypted.

Note that the indexes and WAL files will no longer be encrypted.

!!! hint
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 command, run a simple "count(*)" on your tables:
```
SELECT COUNT(*) FROM mytable;
Run a simple "count(*)" on your table to check every tuple for visibility and set the hint bits:

```
SELECT COUNT(*) FROM mytable;
```


## Method 2. Create a new unencrypted table on the base of the encrypted one

Expand Down
10 changes: 4 additions & 6 deletions documentation/docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@

`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.

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).
Learn 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

Expand All @@ -27,9 +25,9 @@ Lear more [what is Transparent Data Encryption](tde.md#how-does-it-work) and [wh

* Keys in the local keyfile are stored unencrypted. For better security we recommend using the Key management storage.
* System tables are currently not encrypted.
* Currently you cannot update the configuration of an existing Key Management Store (KMS). If its configuration changes (e.g. your Vault server has a new URL), you must set up a new key provider in `pg_tde` and create new keys there. Both the KMS and PostgreSQL servers must be up and running during these changes. [Reach out to our experts](https://www.percona.com/about/contact) for assistance and to outline the best update path for you.
* Currently you cannot update the configuration of an existing Key Management Store (KMS). If its configuration changes (e.g. your Vault server has a new URL), you must set up a new key provider in `pg_tde` and create new keys there. Both the KMS and PostgreSQL servers must be up and running during these changes. [Reach out to our experts](https://www.percona.com/about/contact) for help and to outline the best update path for you.

We plan to introduce the way to update the configuration of an existing KMS in future releases.
We plan to introduce the way to update the configuration of an existing KMS in future releases.

* `pg_rewind` doesn't work with encrypted WAL for now. We plan to fix it in future releases.

Expand All @@ -50,7 +48,7 @@ The `pg_tde` extension comes in two distinct versions with specific access metho

### Which version to chose?

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.
Use the community version and the `tde_heap_basic` access method for data sets where indexing is not mandatory or index encryption is not required. 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.

Expand Down
26 changes: 20 additions & 6 deletions documentation/docs/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,27 @@

You can use the following options to manage encryption keys:

* Use the HashiCorp Vault server. This is the recommended approach. The Vault server configuration is out of scope of this document. We assume that you have the Vault server up and running. For the `pg_tde` configuration, you need the following information:
* Use the Key Management Store (KMS). This is the recommended approach. `pg_tde` supports the following KMS:

* The secret access token to the Vault server
* The URL to access the Vault server
* (Optional) The CA file used for SSL verification
* HashiCorp Vault as the key/value secrets engine version 2 with secret versioning
* HashiCorp Vault as the KMIP server. The KMIP server is part of Vault Enterprise and requires a license
* OpenBao as the open-source alternative to HashiCorp Vault KMIP
* A KMIP-compatible server. For testing and development purposes you can use PyKMIP.

* Use the local keyfile. This approach is rather used for development and testing purposes since the keys are stored unencrypted in the specified keyfile.
The KMS configuration is out of scope of this document. We assume that you have the KMS up and running. For the `pg_tde` configuration, you need the following information:

=== "Vault secrets engine"

* The secret access token to the Vault server
* The URL to access the Vault server
* (Optional) The CA file used for SSL verification

=== "KMIP server"

* The hostname or IP address of the KMIP server.
* The valid certificates issued by the key management appliance.

* Use the local keyfile. Use the keyfile only development and testing purposes since the keys are stored unencrypted.

## Procedure

Expand All @@ -34,7 +48,7 @@ Install `pg_tde` using one of available installation methods:

=== "Build from source"

To build `pg_tde` from source code, do the following
To build `pg_tde` from source code, do the following:

1. On Ubuntu/Debian: Install the following dependencies required for the build:

Expand Down
6 changes: 2 additions & 4 deletions documentation/docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,6 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
The Vault server setup is out of scope of this document.
```
SELECT pg_tde_add_key_provider_kmip('kmip','127.0.0.1', 5696, '/tmp/server_certificate.pem', '/tmp/client_key_jane_doe.pem');
```
Expand All @@ -88,7 +86,7 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
```
SELECT pg_tde_add_key_provider_file_vault_v2('my-vault','https://vault.example.com','secret/data','hvs.zPuyktykA...example...ewUEnIRVaKoBzs2', NULL);
SELECT pg_tde_add_key_provider_file_vault_v2('my-vault','http://vault.vault.svc.cluster.local:8200,'secret/data','hvs.zPuyktykA...example...ewUEnIRVaKoBzs2', NULL);
```
=== "With a keyring file"
Expand Down Expand Up @@ -124,7 +122,7 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
<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.
## WAL encryption configuration
## WAL encryption configuration (tech preview)
After you [enabled `pg_tde`](#enable-extension) and started the Percona Server for PostgreSQL, a principal key and a keyring for WAL are created. Now you need to instruct `pg_tde ` to encrypt WAL files by configuring WAL encryption.
Expand Down
23 changes: 14 additions & 9 deletions documentation/docs/test.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Enabling `pg_tde` extension for a database creates the table access method `tde_

Here's how to do it:

## Encrypt data in a new table

1. Create a table in the database for which you have [enabled `pg_tde`](setup.md) using the `tde_heap` access method as follows:

```
Expand Down Expand Up @@ -41,18 +43,21 @@ Here's how to do it:
SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- changeprovider
```
4. You can encrypt an existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
## Encrypt existing table
```
ALTER TABLE table_name SET access method tde_heap;
```
You can encrypt an existing table. It requires rewriting the table, so for large tables, it might take a considerable amount of time.
!!! hint
Run the following command:
```
ALTER TABLE table_name SET access method tde_heap;
```
Note that the `ALTER TABLE SET` 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 command, run a simple "count(*)" on your tables:
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 command, run a simple "count(*)" on your tables:
```
SELECT COUNT(*) FROM mytable;
```
SELECT COUNT(*) FROM table_name;
```
!!! hint
Expand Down

0 comments on commit f7f21f5

Please sign in to comment.