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

Author: Andriciuc

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

contrib/pg_tde/documentation/docs/functions.md

@@ -229,7 +229,7 @@ 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 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.
+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.
 
 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.
 
@@ -257,50 +257,35 @@ SELECT pg_tde_create_key_using_global_key_provider(
 
 ### pg_tde_set_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.
+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.
 
 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',
-  'false' -- or 'true'
+  'provider-name'
 );
 ```
-
-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
 
-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'
 );
 ```
 
@@ -315,24 +300,17 @@ The `ensure_new_key` parameter instructs the function how to handle a principal
 
 ### 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.
-
 ### pg_tde_delete_key
 
 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

@@ -4,27 +4,34 @@ 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'
 );
 ```
 
 ## Parameter description
 
 * `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 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
 This example is for testing purposes only. Replace the key name and provider name with your values:
 
 ```sql
-SELECT pg_tde_set_server_key_using_global_key_provider(
-  'key-name',
-  'provider-name'
+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'
 );
 ```
 

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;'
@@ -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,10 +100,16 @@ 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
@@ -141,25 +147,52 @@ 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_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.
+    * `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.
 
     <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','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.
+
+    <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'
+        );
+    ```