Updating pg_tde_set_default_key_using_global_key_provider parameter (#351)

Updates to # Global Principal Key Configuration parameter of setting
global key

Rewrote and added correct falste/true parameters for ensure_new_key on set_default_key.

---------

Co-authored-by: Anastasia Alexandrova <anastasia.alexandrova@percona.com>

contrib/pg_tde/documentation/docs/functions.md

@@ -264,21 +264,22 @@ Princial keys are stored on key providers by the name specified in this function
 
 ### pg_tde_set_key_using_database_key_provider
 
-Creates or rotates the principal key for the current database using the specified database key provider and key name.
+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(
-  'name-of-the-key',
+  'key-name',
   'provider-name',
-  'ensure_new_key'
+  'false' -- or 'true'
 );
 ```
 
- The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
+For the third parameter (`true`, `false`, or omitted):
 
-* If set to `true` (default), 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`, an existing principal key may be reused.
+* `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
 
@@ -286,7 +287,7 @@ Creates or rotates the global principal key using the specified global key provi
 
 ```sql
 SELECT pg_tde_set_key_using_global_key_provider(
-  'name-of-the-key',
+  'key-name',
   'provider-name',
   'ensure_new_key'
 );
@@ -304,7 +305,7 @@ Creates or rotates the server principal key using the specified global key provi
 
 ```sql
 SELECT pg_tde_set_server_key_using_global_key_provider(
-  'name-of-the-key',
+  'key-name',
   'provider-name',
   'ensure_new_key'
 );
@@ -324,7 +325,7 @@ The default key is automatically used as a principal key  by any database that d
 
 ```sql
 SELECT pg_tde_set_default_key_using_global_key_provider(
-  'name-of-the-key',
+  'key-name',
   'provider-name',
   'ensure_new_key'
 );

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

@@ -1,24 +1,35 @@
 # Global Principal Key Configuration
 
-You can configure a default principal key using a global key provider. This key will be used by all databases that do not have their own encryption keys configured.
+You can configure a default principal key using a global key provider. This key will be used by all databases that do not have their own encryption keys configured. The function **both** sets the principal key and rotates internal keys as needed.
 
 ## Create a default principal key
 
-Run the following command:
+To configure a global principal key, run:
 
 ```sql
 SELECT pg_tde_set_default_key_using_global_key_provider(
-    'name-of-the-key',
-    'provider-name',
-    'ensure_new_key'
+    'key-name',
+    'global_vault_provider',
+    'false'  -- or 'true', or omit entirely
 );
 ```
 
 ## Parameter description
 
-* `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.
+* `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.
+
+!!! note
+    This process sets the **default principal key** for the server. Any database without its own key configuration will use this key.
+
+## Example
 
 This example is for testing purposes only. Replace the key name and provider name with your values:
 
@@ -26,15 +37,10 @@ This example is for testing purposes only. Replace the key name and provider nam
 SELECT pg_tde_set_key_using_global_key_provider(
     'test-db-master-key',
     'file-vault',
-    'ensure_new_key'
+    'false'
 );
 ```
 
-!!! note
-    The key is auto-generated.
-
-After this, all databases that do not have something else configured will use this newly generated principal key.
-
 ## Next steps
 
 [Validate Encryption with pg_tde :material-arrow-right:](../test.md){.md-button}