open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs 17.5.1 revert commit 56106 (#458)

Browse Source 
reverted set key changes for architecture, functions, set principal key
and multi-tenant-setup.md
pull/238/head
Dragos Andriciuc 3 months ago committed by GitHub
parent 5a2c081a95
commit aa2357803f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 64 additions and 106 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 17
      contrib/pg_tde/documentation/docs/architecture/index.md
  2. 69
      contrib/pg_tde/documentation/docs/functions.md
  3. 27
      contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
  4. 57
      contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md

17
contrib/pg_tde/documentation/docs/architecture/index.md
Unescape View File

@ -276,19 +276,15 @@ pg_tde_REVOKE_database_key_management_FROM_role
### Creating and rotating keys
Principal keys can be created using the following functions:
Principal keys can be created or rotated using the following functions:
```sql
pg_tde_create_key_using_(global/database)_key_provider('key-name', 'provider-name')
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)
```
Principal keys can be used or rotated using the following functions:
```sql
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name')
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name')
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name')
```
`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
@ -300,8 +296,7 @@ With this feature, it is possible for the entire database server to easily use t
You can manage a default key with the following functions:
* `pg_tde_create_key_using_global_key_provider('key-name','provider-name')`
* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name')`
* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name','true/false')`
* `pg_tde_delete_default_key()`
!!! note

69
contrib/pg_tde/documentation/docs/functions.md
Unescape View File

@ -230,78 +230,85 @@ 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.
Use these functions to create a new principal key 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.
Princial keys are stored on key providers by the name specified in this function - for example, when using the Vault provider, after creating a key named "foo", a key named "foo" will be visible on the Vault server at the specified mount point.
### pg_tde_creates_key_using_database_key_provider
Creates a principal key at a database local key provider with the given name. For later use with pg_tde_set_key_using_database_key_provider().
```sql
SELECT pg_tde_create_key_using_database_key_provider(
'key-name',
'provider-name'
);
```
### pg_tde_create_key_using_global_key_provider
Creates a principal key at a global key provider with the given name. For later use with pg_tde_set_ series of functions.
```sql
SELECT pg_tde_create_key_using_global_key_provider(
'key-name',
'provider-name'
);
```
### pg_tde_set_key_using_database_key_provider
Sets the principal key for the **current** database, using the specified local key provider. It also rotates internal encryption keys to use the specified principal key.
Creates or reuses a principal key for the **current** database, using the specified local key provider. It also rotates internal encryption keys to use the specified principal key.
This function is typically used when working with per-database encryption through a local key provider.
```sql
SELECT pg_tde_set_key_using_database_key_provider(
'key-name',
'provider-name'
'provider-name',
'false' -- or 'true'
);
```
For the third parameter (`true`, `false`, or omitted):
* `true`: Requires the key to be newly created. If a key with the same name already exists, the function fails.
* `false` (default if omitted): Reuses the existing key with that name, if present. If the key does not exist, a new key is created.
### pg_tde_set_key_using_global_key_provider
Sets or rotates the global principal key using the specified global key provider and the key name. This key is used for global settings like WAL encryption.
Creates or rotates the global principal key using the specified global key provider and the key name. This key is used for global settings like WAL encryption.
```sql
SELECT pg_tde_set_key_using_global_key_provider(
'key-name',
'provider-name'
'provider-name',
'ensure_new_key'
);
```
The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.
### pg_tde_set_server_key_using_global_key_provider
Sets or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
```sql
SELECT pg_tde_set_server_key_using_global_key_provider(
'key-name',
'provider-name'
'provider-name',
'ensure_new_key'
);
```
The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.
### pg_tde_set_default_key_using_global_key_provider
Sets or rotates the default principal key for the server using the specified global key provider.
Creates or rotates the default principal key for the server using the specified global key provider.
The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.
The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.
```sql
SELECT pg_tde_set_default_key_using_global_key_provider(
'key-name',
'provider-name'
'provider-name',
'ensure_new_key'
);
```
The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
* If set to `true`, a new key must be unique.
If the provider already stores a key by that name, the function returns an error.
* If set to `false` (default), an existing principal key may be reused.
### pg_tde_delete_key
Deletes 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 default principal key, internal keys will be encrypted with the default key.

27
contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
Unescape View File

@ -4,23 +4,13 @@ You can configure a default principal key using a global key provider. This key
## Create a default principal key
To create a global principal key, run:
```sql
SELECT pg_tde_create_key_using_global_key_provider(
'key-name',
'global_vault_provider'
);
```
## Configure a default principal key
To configure a global principal key, run:
```sql
SELECT pg_tde_set_default_key_using_global_key_provider(
'key-name',
'global_vault_provider'
'global_vault_provider',
'false' -- or 'true', or omit entirely
);
```
@ -28,10 +18,13 @@ SELECT pg_tde_set_default_key_using_global_key_provider(
* `key-name` is the name under which the principal key is stored in the provider.
* `global_vault_provider` is the name of the global key provider you previously configured.
* Third parameter (optional):
* `true` requires the key to be newly created. If the key already exists, the function fails.
* `false` or omitted (default), allows reuse of an existing key if it exists. If not, a new key is created under the specified name.
## How key generation works
The key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider.
If the specified key does **not** exist, a new encryption key is created under the given name. In this case, the key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider.
!!! note
This process sets the **default principal key** for the server. Any database without its own key configuration will use this key.
@ -41,14 +34,10 @@ The key material (actual cryptographic key) is auto-generated by `pg_tde` and st
This example is for testing purposes only. Replace the key name and provider name with your values:
```sql
SELECT pg_tde_create_key_using_global_key_provider(
'test-db-master-key',
'file-vault'
);
SELECT pg_tde_set_key_using_global_key_provider(
'test-db-master-key',
'file-vault'
'file-vault',
'false'
);
```

57
contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
Unescape View File

@ -42,7 +42,7 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
!!! tip
You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:
You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:
```sh
psql -d template1 -c 'CREATE EXTENSION pg_tde;'
@ -59,8 +59,8 @@ You must do these steps for every database where you have created the extension.
The KMIP server setup is out of scope of this document.
Make sure you have obtained the root certificate for the KMIP server and the keypair for the client. The client key needs permissions to create / read keys on the server. Find the [configuration guidelines for the HashiCorp Vault Enterprise KMIP Secrets Engine](https://developer.hashicorp.com/vault/tutorials/enterprise/kmip-engine).
For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.
For testing purposes, you can use the PyKMIP server which enables you to set up required certificates. To use a real KMIP server, make sure to obtain the valid certificates issued by the key management appliance.
```sql
SELECT pg_tde_add_database_key_provider_kmip(
@ -100,16 +100,10 @@ You must do these steps for every database where you have created the extension.
The Vault server setup is out of scope of this document.
```sql
SELECT pg_tde_add_database_key_provider_vault_v2(
'provider-name',
'url',
'mount',
'secret_token_path',
'ca_path'
);
```
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name', 'url', 'mount', 'secret_token_path', 'ca_path');
```
where:
where:
* `url` is the URL of the Vault server
* `mount` is the mount point where the keyring should store the keys
@ -147,52 +141,25 @@ You must do these steps for every database where you have created the extension.
'/tmp/pg_tde_test_local_keyring.per'
);
```
2. Add a principal key
2. Create a key
```sql
SELECT pg_tde_create_key_using_database_key_provider(
'name-of-the-key',
'provider-name'
);
SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key', 'provider-name','ensure_new_key');
```
where:
* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
* `provider-name` is the name of the key provider you added before. The principal key is associated with this provider and it is the location where it is stored and fetched from.
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
* `ensure_new_key` defines if a principal key must be unique. The default value `true` means that you must speficy a unique key during key rotation. The `false` value allows reusing an existing principal key.
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
```sql
SELECT pg_tde_create_key_using_database_key_provider(
'test-db-master-key',
'file-vault'
);
SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
```
!!! note
The key is auto-generated.
3. Use the key as principal key
```sql
SELECT pg_tde_set_key_using_database_key_provider(
'name-of-the-key',
'provider-name'
);
```
where:
* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
```sql
SELECT pg_tde_set_key_using_database_key_provider(
'test-db-master-key',
'file-vault'
);
```

Write Preview
Loading…
Cancel
Save