You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`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.
285
+
Principal keys can be used or rotated using the following functions:
Copy file name to clipboardExpand all lines: contrib/pg_tde/documentation/docs/functions.md
+10-32Lines changed: 10 additions & 32 deletions
Original file line number
Diff line number
Diff line change
@@ -229,7 +229,7 @@ These functions list the details of all key providers for the current database o
229
229
230
230
## Principal key management
231
231
232
-
Use these functions to create a new principal key at a given key provider, 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.
232
+
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.
233
233
234
234
Principal 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.
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.
260
+
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.
261
261
262
262
This function is typically used when working with per-database encryption through a local key provider.
For the third parameter (`true`, `false`, or omitted):
273
-
274
-
*`true`: Requires the key to be newly created. If a key with the same name already exists, the function fails.
275
-
*`false` (default if omitted): Reuses the existing key with that name, if present. If the key does not exist, a new key is created.
276
-
277
270
### pg_tde_set_key_using_global_key_provider
278
271
279
-
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.
272
+
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.
280
273
281
274
```sql
282
275
SELECT pg_tde_set_key_using_global_key_provider(
283
276
'key-name',
284
-
'provider-name',
285
-
'ensure_new_key'
277
+
'provider-name'
286
278
);
287
279
```
288
280
289
-
The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
290
-
291
-
* If set to `true`, a new key must be unique.
292
-
If the provider already stores a key by that name, the function returns an error.
293
-
* If set to `false` (default), an existing principal key may be reused.
The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
331
-
332
-
* If set to `true`, a new key must be unique.
333
-
If the provider already stores a key by that name, the function returns an error.
334
-
* If set to `false` (default), an existing principal key may be reused.
335
-
336
314
### pg_tde_delete_key
337
315
338
316
Unsets 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.
*`key-name` is the name under which the principal key is stored in the provider.
20
30
*`global_vault_provider` is the name of the global key provider you previously configured.
21
-
* Third parameter (optional):
22
-
*`true` requires the key to be newly created. If the key already exists, the function fails.
23
-
*`false` or omitted (default), allows reuse of an existing key if it exists. If not, a new key is created under the specified name.
24
31
25
32
## How key generation works
26
33
27
-
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.
34
+
The key material (actual cryptographic key) is auto-generated by `pg_tde` and stored securely by the configured provider.
28
35
29
36
!!! note
30
37
This process sets the **default principal key for the entire server**. Any database without a key explicitly configured will fall back to this key.
@@ -34,9 +41,14 @@ If the specified key does **not** exist, a new encryption key is created under t
34
41
This example is for testing purposes only. Replace the key name and provider name with your values:
Copy file name to clipboardExpand all lines: contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
+45-12Lines changed: 45 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -42,7 +42,7 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
42
42
43
43
!!! tip
44
44
45
-
You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:
45
+
You can have the `pg_tde` extension automatically enabled for every newly created database. Modify the template `template1` database as follows:
46
46
47
47
```sh
48
48
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.
59
59
The KMIP server setup is out of scope of this document.
60
60
61
61
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).
62
-
63
-
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.
62
+
63
+
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.
64
64
65
65
```sql
66
66
SELECT pg_tde_add_database_key_provider_kmip(
@@ -100,10 +100,16 @@ You must do these steps for every database where you have created the extension.
100
100
The Vault server setup is out of scope of this document.
* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
154
-
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
155
-
* `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.
163
+
* `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.
156
164
157
165
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
0 commit comments