Skip to content

Fix some documentation pages after key management functions renaming #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: TDE_REL_17_STABLE
Choose a base branch
from
Open

Fix some documentation pages after key management functions renaming #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 32 additions & 29 deletions contrib/pg_tde/documentation/docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,30 +199,30 @@ If `pg_tde.inherit_global_providers` is `OFF`, global providers are only used fo
To add a global provider:

```sql
pg_tde_add_global_key_provider_<TYPE>(‘provider_name', ... details ...)
pg_tde_add_global_key_provider_<TYPE>('provider_name', ... details ...)
```

To add a database specific provider:

```sql
pg_tde_add_key_provider_<TYPE>(‘provider_name', ... details ...)
pg_tde_add_database_key_provider_<TYPE>('provider_name', ... details ...)
```

Note that in these functions do not verify the parameters.
For that, see `pg_tde_verify_principal_key`.
For that, see `pg_tde_verify_key`.

### Changing providers

To change a value of a global provider:

```sql
pg_tde_modify_global_key_provider_<TYPE>(‘provider_name', ... details ...)
pg_tde_change_global_key_provider_<TYPE>('provider_name', ... details ...)
```

To change a value of a database specific provider:

```sql
pg_tde_modify_key_provider_<TYPE>(‘provider_name', ... details ...)
pg_tde_change_database_key_provider_<TYPE>('provider_name', ... details ...)
```

These functions also allow changing the type of a provider.
Expand All @@ -231,16 +231,16 @@ The functions however do not migrate any data.
They are expected to be used during infrastructure migration, for example when the address of a server changes.

Note that in these functions do not verify the parameters.
For that, see `pg_tde_verify_principal_key`.
For that, see `pg_tde_verify_key`.

### Changing providers from the command line

To change a provider from a command line, `pg_tde` provides the `pg_tde_modify_key_provider` command line tool.
To change a provider from a command line, `pg_tde` provides the `pg_tde_change_key_provider` command line tool.

This tool work similarly to the above functions, with the following syntax:

```bash
pg_tde_modify_key_provider <dbOid> <providerType> ... details ...
pg_tde_change_key_provider <dbOid> <providerType> ... details ...
```

Note that since this tool is expected to be offline, it bypasses all permission checks!
Expand All @@ -252,8 +252,8 @@ This is also the reason why it requires a `dbOid` instead of a name, as it has n
Providers can be deleted by the

```sql
pg_tde_delete_key_provider(provider_name)
pg_tde_delete_global_key_provider(provider_name)
pg_tde_delete_database_key_provider(provider_name)
pg_tde_delete_global_key_provider(provider_name)
```

functions.
Expand All @@ -269,16 +269,16 @@ Making this check makes more sense than potentially making some databases inacce

`Pg_tde` provides 2 functions to show providers:

* `pg_tde_list_all_key_providers()`
* `pg_tde_list_all_database_key_providers()`
* `pg_tde_list_all_global_key_providers()`

These functions only return a list of provider names, without any details about the type/configuration.

There's also two function to query the details of providers:

```sql
pg_tde_show_key_provider_configuration(‘provider-name')
pg_tde_show_global_key_provider_configuration(‘provider-name')
pg_tde_show_key_provider_configuration('provider-name')
pg_tde_show_global_key_provider_configuration('provider-name')
```

These functions display the provider type and configuration details, but won't show the sensitive parameters, such as passwords or authentication keys.
Expand All @@ -287,11 +287,11 @@ These functions display the provider type and configuration details, but won't s

`Pg_tde` implements access control based on execution rights on the administration functions.

For provider administration, it provides two pair of functions:
For keys and providers administration, it provides two pair of functions:
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have permission differentiation for key and providers administration. Is it something that we are planning?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, but maybe we should look closer at why and how we actually want multi-tenancy to work because the ability to create key providers is actually quite dnagerous.


```sql
pg_tde_(grant/revoke)_local_provider_management_to_role
pg_tde_(grant/revoke)_global_provider_management_to_role
pg_tde_(grant/revoke)_database_key_management_to_role
pg_tde_(grant/revoke)_global_key_management_to_role
```

There's one special behavior:
Expand All @@ -303,25 +303,25 @@ When `pg_tde.inherit_global_providers` is OFF, they can't execute the function a
Principal keys can be created or rotated using the following functions:

```sql
pg_tde_set_principal_key(‘key-name', ‘provider-name', ensure_new_key)
pg_tde_set_global_principal_key(‘key-name', ‘provider-name', ensure_new_key)
pg_tde_set_server_principal_key(‘key-name', ‘provider-name', ensure_new_key)
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
```

`ensure_new_key` is a boolean parameter defaulting to false.
If it is true, the function might return an error instead of setting the key, if it already exists on the provider.

### Default principal key

With `pg_tde.inherit_global_key_providers`, it is also possible to set up a default global principal key, which will be used by any database which has the `pg_tde` extension enabled, but doesn't have a database specific principal key configured using `pg_tde_set_(global_)principal_key`.
With `pg_tde.inherit_global_key_providers`, it is also possible to set up a default global principal key, which will be used by any database which has the `pg_tde` extension enabled, but doesn't have a database specific principal key configured using `pg_tde_set_key_using_(global/database)_key_provider`.

With this feature, it is possible for the entire database server to easily use the same principal key for all databases, completely disabling multi-tenency.

A default key can be managed with the following functions:

```sql
pg_tde_set_default_principal_key(‘key-name', ‘provider-name', ensure_new_key)
pg_tde_drop_default_principal_key() -- not yet implemented
pg_tde_set_default_key('key-name', 'provider-name', ensure_new_key)
pg_tde_drop_default_key() -- not yet implemented
```

`DROP` is only possible if there's no table currently using the default principal key.
Expand All @@ -330,19 +330,21 @@ Changing the default principal key will rotate the encryption of internal keys f

### Removing key (not yet implemented)

`pg_tde_drop_principal_key` removes the principal key for the current database.
`pg_tde_drop_key` removes the principal key for the current database.
If the current database has any encrypted tables, and there isn't a default principal key configured, it reports an error instead.
If there are encrypted tables, but there's also a global default principal key, internal keys will be encrypted with the default key.

It isn't possible to remove the WAL (server) principal key.

### Current key details

`pg_tde_principal_key_info()` returns the name of the current principal key, and the provider it uses.
`pg_tde_key_info()` returns the name of the current principal key, and the provider it uses.

`pg_tde_global_principal_key_info(‘PG_TDE_GLOBAL')` does the same for the server key.
`pg_tde_server_key_info()` does the same for the server key.

`pg_tde_verify_principal_key()` checks that the key provider is accessible, that the current principal key can be downloaded from it, and that it is the same as the current key stored in memory - if any of these fail, it reports an appropriate error.
`pg_tde_default_key_info()` does the same for the default key.

`pg_tde_verify_key()` checks that the key provider is accessible, that the current principal key can be downloaded from it, and that it is the same as the current key stored in memory - if any of these fail, it reports an appropriate error.

### Listing all active keys (not yet implemented)

Expand All @@ -351,13 +353,14 @@ SUPERusers are able to use the following function:
`pg_tde_list_active_keys()`

Which reports all the actively used keys by all databases on the current server.
Similarly to `pg_tde_show_current_principal_key`, it only shows names and associated providers, it doesn't reveal any sensitive information about the providers.
Similarly to `pg_tde_key_info()`, it only shows names and associated providers, it doesn't reveal any sensitive information about the providers.

### Key permissions

Users with management permissions to a specific database `(pg_tde_(grant/revoke)_provider_management_to_role)` can change the keys for the database, and use the current key functions. This includes creating keys using global providers, if `pg_tde.inherit_global_providers` is enabled.
Users with management permissions to a specific database `(pg_tde_(grant/revoke)_(global/databse)_key_management_to_role)` can change the keys for the database, and use the current key functions. This includes creating keys using global providers, if `pg_tde.inherit_global_providers` is enabled.

Also, the `pg_tde_(grant/revoke)_key_management_to_role` function deals with only the specific permission for the above function:
// TODO: We don't have such permissions subset
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this todo to revisit this topic

Also, the `pg_tde_(grant/revoke)_(global/database)_key_management_to_role` function deals with only the specific permission for the above function:
it allows a user to change the key for the database, but not to modify the provider configuration.

### Creating encrypted tables
Expand Down
4 changes: 2 additions & 2 deletions contrib/pg_tde/documentation/docs/command-line-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ Its only intended use is to fix servers that can't start up because of inaccessi

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_<type>`](functions.md#change-an-existing-provider) SQL functions.
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_(global/database)_key_provider_<type>`](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_<type>`](functions.md#change-an-existing-provider) SQL functions.
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_(global/database)_key_provider_<type>`](functions.md#change-an-existing-provider) SQL functions.

The general syntax is as follows:

Expand Down