diff --git a/contrib/pg_tde/documentation/docs/architecture/index.md b/contrib/pg_tde/documentation/docs/architecture/index.md
index b643a393fac95..9abd070c4c9eb 100644
--- a/contrib/pg_tde/documentation/docs/architecture/index.md
+++ b/contrib/pg_tde/documentation/docs/architecture/index.md
@@ -276,15 +276,19 @@ pg_tde_REVOKE_database_key_management_FROM_role
### Creating and rotating keys
-Principal keys can be created or rotated using the following functions:
+Principal keys can be created using the following functions:
```sql
-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)
+pg_tde_create_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.
+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')
+```
### Default principal key
@@ -296,7 +300,8 @@ 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_set_default_key_using_global_key_provider('key-name','provider-name','true/false')`
+* `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_delete_default_key()`
!!! note
diff --git a/contrib/pg_tde/documentation/docs/functions.md b/contrib/pg_tde/documentation/docs/functions.md
index 0a6a7afde256e..563d359aa2cf4 100644
--- a/contrib/pg_tde/documentation/docs/functions.md
+++ b/contrib/pg_tde/documentation/docs/functions.md
@@ -230,85 +230,78 @@ 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 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 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.
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_set_key_using_database_key_provider
+### pg_tde_creates_key_using_database_key_provider
-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.
+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().
-This function is typically used when working with per-database encryption through a local 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_set_key_using_database_key_provider(
+SELECT pg_tde_create_key_using_global_key_provider(
'key-name',
- 'provider-name',
- 'false' -- or 'true'
+ 'provider-name'
);
```
-For the third parameter (`true`, `false`, or omitted):
+### 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.
-* `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.
+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'
+);
+```
### pg_tde_set_key_using_global_key_provider
-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.
+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.
```sql
SELECT pg_tde_set_key_using_global_key_provider(
'key-name',
- 'provider-name',
- 'ensure_new_key'
+ 'provider-name'
);
```
- 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
-Creates or rotates the server principal key using the specified global key provider. Use this function to set a principal key for WAL encryption.
+Sets 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',
- 'ensure_new_key'
+ 'provider-name'
);
```
-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
-Creates or rotates the default principal key for the server using the specified global key provider.
+Sets 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',
- 'ensure_new_key'
+ 'provider-name'
);
```
-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.
-
## Encryption status check
### pg_tde_is_encrypted
diff --git a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
index 86bb9b1ada853..4c3cc3802d04e 100644
--- a/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
+++ b/contrib/pg_tde/documentation/docs/global-key-provider-configuration/set-principal-key.md
@@ -4,13 +4,23 @@ 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',
- 'false' -- or 'true', or omit entirely
+ 'global_vault_provider'
);
```
@@ -18,13 +28,10 @@ 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
-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.
+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.
@@ -34,10 +41,14 @@ If the specified key does **not** exist, a new encryption key is created under t
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',
- 'false'
+ 'file-vault'
);
```
diff --git a/contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md b/contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
index b59c1e7fc585a..247a1878c254b 100644
--- a/contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
+++ b/contrib/pg_tde/documentation/docs/how-to/multi-tenant-setup.md
@@ -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;'
@@ -57,8 +57,8 @@ You must do these steps for every database where you have created the extension.
=== "With KMIP server"
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('provider-name','kmip-addr', 5696, '/path_to/client_cert.pem', '/path_to/client_key.pem', '/path_to/server_certificate.pem');
@@ -85,9 +85,9 @@ You must do these steps for every database where you have created the extension.
```sql
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
@@ -113,25 +113,40 @@ You must do these steps for every database where you have created the extension.
```sql
SELECT pg_tde_add_database_key_provider_file('file-keyring', '/tmp/pg_tde_test_local_keyring.per');
```
-
-2. Add a principal key
+2. Create a key
```sql
- SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key', 'provider-name','ensure_new_key');
+
+ SELECT pg_tde_create_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.
- * `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.
:material-information: Warning: This example is for testing purposes only:
```sql
- SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
+ SELECT pg_tde_create_key_using_database_key_provider('test-db-master-key', 'file-vault');
```
!!! 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.
+
+ :material-information: Warning: This example is for testing purposes only:
+
+ ```sql
+ SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault');
+ ```