Skip to content

Commit 33af938

Browse files
authored
Re-apply set key changes: revert of revert commit (#461)
reverted the revert for set key changes for architecture, functions, set principal key and multi-tenant-setup.md
1 parent f10eae3 commit 33af938

File tree

4 files changed

+87
-59
lines changed

4 files changed

+87
-59
lines changed

contrib/pg_tde/documentation/docs/architecture/index.md

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -276,15 +276,19 @@ pg_tde_REVOKE_database_key_management_FROM_role
276276

277277
### Creating and rotating keys
278278

279-
Principal keys can be created or rotated using the following functions:
279+
Principal keys can be created using the following functions:
280280

281281
```sql
282-
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
283-
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
284-
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name', ensure_new_key)
282+
pg_tde_create_key_using_(global/database)_key_provider('key-name', 'provider-name')
285283
```
286284

287-
`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:
286+
287+
```sql
288+
pg_tde_set_key_using_(global/database)_key_provider('key-name', 'provider-name')
289+
pg_tde_set_server_key_using_(global/database)_key_provider('key-name', 'provider-name')
290+
pg_tde_set_default_key_using_(global/database)_key_provider('key-name', 'provider-name')
291+
```
288292

289293
### Default principal key
290294

@@ -296,7 +300,8 @@ With this feature, it is possible for the entire database server to easily use t
296300

297301
You can manage a default key with the following functions:
298302

299-
* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name','true/false')`
303+
* `pg_tde_create_key_using_global_key_provider('key-name','provider-name')`
304+
* `pg_tde_set_default_key_using_global_key_provider('key-name','provider-name')`
300305
* `pg_tde_delete_default_key()`
301306

302307
!!! note

contrib/pg_tde/documentation/docs/functions.md

Lines changed: 10 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ These functions list the details of all key providers for the current database o
229229

230230
## Principal key management
231231

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

234234
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.
235235

@@ -257,50 +257,35 @@ SELECT pg_tde_create_key_using_global_key_provider(
257257

258258
### pg_tde_set_key_using_database_key_provider
259259

260-
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.
261261

262262
This function is typically used when working with per-database encryption through a local key provider.
263263

264264
```sql
265265
SELECT pg_tde_set_key_using_database_key_provider(
266266
'key-name',
267-
'provider-name',
268-
'false' -- or 'true'
267+
'provider-name'
269268
);
270269
```
271-
272-
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-
277270
### pg_tde_set_key_using_global_key_provider
278271

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

281274
```sql
282275
SELECT pg_tde_set_key_using_global_key_provider(
283276
'key-name',
284-
'provider-name',
285-
'ensure_new_key'
277+
'provider-name'
286278
);
287279
```
288280

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.
294-
295281
### pg_tde_set_server_key_using_global_key_provider
296282

297-
Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
283+
Sets or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
298284

299285
```sql
300286
SELECT pg_tde_set_server_key_using_global_key_provider(
301287
'key-name',
302-
'provider-name',
303-
'ensure_new_key'
288+
'provider-name'
304289
);
305290
```
306291

@@ -315,24 +300,17 @@ The `ensure_new_key` parameter instructs the function how to handle a principal
315300

316301
### pg_tde_set_default_key_using_global_key_provider
317302

318-
Creates or rotates the default principal key for the server using the specified global key provider.
303+
Sets or rotates the default principal key for the server using the specified global key provider.
319304

320-
The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.
305+
The default key is automatically used as a principal key by any database that doesn't have an individual key provider and key configuration.
321306

322307
```sql
323308
SELECT pg_tde_set_default_key_using_global_key_provider(
324309
'key-name',
325-
'provider-name',
326-
'ensure_new_key'
310+
'provider-name'
327311
);
328312
```
329313

330-
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-
336314
### pg_tde_delete_key
337315

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

contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,34 @@ You can configure a default principal key using a global key provider. This key
44

55
## Create a default principal key
66

7+
To create a global principal key, run:
8+
9+
```sql
10+
SELECT pg_tde_create_key_using_global_key_provider(
11+
'key-name',
12+
'global_vault_provider'
13+
);
14+
```
15+
16+
## Configure a default principal key
17+
718
To configure a global principal key, run:
819

920
```sql
1021
SELECT pg_tde_set_default_key_using_global_key_provider(
1122
'key-name',
12-
'global_vault_provider',
13-
'false' -- or 'true', or omit entirely
23+
'global_vault_provider'
1424
);
1525
```
1626

1727
## Parameter description
1828

1929
* `key-name` is the name under which the principal key is stored in the provider.
2030
* `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.
2431

2532
## How key generation works
2633

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

2936
!!! note
3037
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
3441
This example is for testing purposes only. Replace the key name and provider name with your values:
3542

3643
```sql
37-
SELECT pg_tde_set_server_key_using_global_key_provider(
38-
'key-name',
39-
'provider-name'
44+
SELECT pg_tde_create_key_using_global_key_provider(
45+
'test-db-master-key',
46+
'file-vault'
47+
);
48+
49+
SELECT pg_tde_set_key_using_global_key_provider(
50+
'test-db-master-key',
51+
'file-vault'
4052
);
4153
```
4254

contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md

Lines changed: 45 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
4242
4343
!!! tip
4444
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:
4646
4747
```sh
4848
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.
5959
The KMIP server setup is out of scope of this document.
6060
6161
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.
6464
6565
```sql
6666
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.
100100
The Vault server setup is out of scope of this document.
101101
102102
```sql
103-
SELECT pg_tde_add_database_key_provider_vault_v2('provider-name', 'url', 'mount', 'secret_token_path', 'ca_path');
104-
```
103+
SELECT pg_tde_add_database_key_provider_vault_v2(
104+
'provider-name',
105+
'url',
106+
'mount',
107+
'secret_token_path',
108+
'ca_path'
109+
);
110+
```
105111
106-
where:
112+
where:
107113
108114
* `url` is the URL of the Vault server
109115
* `mount` is the mount point where the keyring should store the keys
@@ -141,25 +147,52 @@ You must do these steps for every database where you have created the extension.
141147
'/tmp/pg_tde_test_local_keyring.per'
142148
);
143149
```
144-
145-
2. Add a principal key
146150
151+
2. Create a key
147152
```sql
148-
SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key', 'provider-name','ensure_new_key');
153+
154+
SELECT pg_tde_create_key_using_database_key_provider(
155+
'name-of-the-key',
156+
'provider-name'
157+
);
149158
```
150159
151160
where:
152161
153162
* `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.
156164
157165
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
158166
159167
```sql
160-
SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
168+
SELECT pg_tde_create_key_using_database_key_provider(
169+
'test-db-master-key',
170+
'file-vault'
171+
);
161172
```
162173
163174
!!! note
164175
The key is auto-generated.
165176
177+
3. Use the key as principal key
178+
```sql
179+
180+
SELECT pg_tde_set_key_using_database_key_provider(
181+
'name-of-the-key',
182+
'provider-name'
183+
);
184+
```
185+
186+
where:
187+
188+
* `name-of-the-key` is the name of the principal key. You will use this name to identify the key.
189+
* `provider-name` is the name of the key provider you added before. The principal key will be associated with this provider.
190+
191+
<i warning>:material-information: Warning:</i> This example is for testing purposes only:
192+
193+
```sql
194+
SELECT pg_tde_set_key_using_database_key_provider(
195+
'test-db-master-key',
196+
'file-vault'
197+
);
198+
```

0 commit comments

Comments
 (0)