PG-1457 Rename principal key on user API level to just a key

ci_scripts/backup/pg_basebackup_test.sh

@@ -105,7 +105,7 @@ setup_tde_heap(){
     sudo -u "$PG_USER" psql -p $PG_PORT -c "CREATE DATABASE $DB_NAME;"
     sudo -u "$PG_USER" psql -d "$DB_NAME" -p "$PG_PORT" -c "CREATE EXTENSION IF NOT EXISTS pg_tde;"
     sudo -u "$PG_USER" psql -d "$DB_NAME" -p "$PG_PORT" -c "SELECT pg_tde_add_database_key_provider_file('file-vault','$KEYLOCATION');"
-    sudo -u "$PG_USER" psql -d "$DB_NAME" -p "$PG_PORT" -c "SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-master-key','file-vault');"
+    sudo -u "$PG_USER" psql -d "$DB_NAME" -p "$PG_PORT" -c "SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault');"
     sudo -u "$PG_USER" psql -p $PG_PORT -c "ALTER DATABASE $DB_NAME SET default_table_access_method='tde_heap';"
     sudo -u "$PG_USER" psql -p $PG_PORT -c "SELECT pg_reload_conf();"
 }

ci_scripts/tde_setup.sql

@@ -1,4 +1,4 @@
 CREATE SCHEMA IF NOT EXISTS tde;
 CREATE EXTENSION IF NOT EXISTS pg_tde SCHEMA tde;
 SELECT tde.pg_tde_add_database_key_provider_file('reg_file-vault', '/tmp/pg_tde_test_keyring.per');
-SELECT tde.pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key', 'reg_file-vault');
+SELECT tde.pg_tde_set_key_using_database_key_provider('test-db-key', 'reg_file-vault');

ci_scripts/tde_setup_global.sql

@@ -2,7 +2,7 @@ CREATE SCHEMA tde;
 CREATE EXTENSION IF NOT EXISTS pg_tde SCHEMA tde;
 
 SELECT tde.pg_tde_add_global_key_provider_file('reg_file-global', '/tmp/pg_tde_test_keyring.per');
-SELECT tde.pg_tde_set_server_principal_key_using_global_key_provider('server-principal-key', 'reg_file-global');
+SELECT tde.pg_tde_set_server_key_using_global_key_provider('server-key', 'reg_file-global');
 ALTER SYSTEM SET pg_tde.wal_encrypt = on;
 ALTER SYSTEM SET default_table_access_method = 'tde_heap';
 ALTER SYSTEM SET search_path = "$user",public,tde;

contrib/pg_tde/README.md

@@ -126,11 +126,11 @@ _See [Make Builds for Developers](https://github.com/percona/pg_tde/wiki/Make-bu
 
         **Note: The `File` provided is intended for development and stores the keys unencrypted in the specified data file.**
 
-   5. Set the principal key for the database using the `pg_tde_set_principal_key` function.
+   5. Set the principal key for the database using the `pg_tde_set_key` function.
 
         ```sql
-        -- pg_tde_set_principal_key_using_database_key_provider(principal_key_name, provider_name);
-        SELECT pg_tde_set_principal_key_using_database_key_provider('my-principal-key','file');
+        -- pg_tde_set_key_using_database_key_provider(key_name, provider_name);
+        SELECT pg_tde_set_key_using_database_key_provider('my-key','file');
         ```
    
    6. Specify `tde_heap` access method during table creation

contrib/pg_tde/documentation/docs/functions.md

@@ -61,7 +61,7 @@ You can add a new key provider using the provided functions, which are implement
 
 There are two functions to add a key provider: one function adds it for the current database and another one - for the global scope. 
 
-* `pg_tde_add_key_provider_<type>('provider-name', <provider specific parameters>)`
+* `pg_tde_add_database_key_provider_<type>('provider-name', <provider specific parameters>)`
 * `pg_tde_add_global_key_provider_<type>('provider-name', <provider specific parameters>)`
 
 When you add a new provider, the provider name must be unqiue in the scope. But a local database provider and a global provider can have the same name.
@@ -201,12 +201,12 @@ Use these functions to create a new principal key for a specific scope such as a
 
 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_principal_key_using_database_key_provider
+### 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.
 
 ```
-SELECT pg_tde_set_principal_key_using_database_key_provider('name-of-the-principal-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key','provider-name','ensure_new_key');
 ```
 
  The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -215,12 +215,12 @@ SELECT pg_tde_set_principal_key_using_database_key_provider('name-of-the-princip
   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.
 
-### pg_tde_set_principal_key_using_global_key_provider
+### 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.
 
 ```
-SELECT pg_tde_set_principal_key_using_global_key_provider('name-of-the-principal-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
 ```
 
  The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -229,12 +229,12 @@ SELECT pg_tde_set_principal_key_using_global_key_provider('name-of-the-principal
   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.
 
-### pg_tde_set_server_principal_key_using_global_key_provider
+### 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.
 
 ```
-SELECT pg_tde_set_server_principal_key_using_global_key_provider('name-of-the-principal-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_server_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
 ```
 
 The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -244,14 +244,14 @@ The `ensure_new_key` parameter instructs the function how to handle a principal
 * If set to `false`, an existing principal key may be reused.
 
 
-### pg_tde_set_default_principal_key_using_global_key_provider
+### 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.
 
 The default key is automatically used as a principal key  by any database that doesn't have an individual key provider and key configuration.
 
 ```
-SELECT pg_tde_set_default_principal_key_using_global_key_provider('name-of-the-principal-key','provider-name','ensure_new_key');
+SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
 ```
 
 The `ensure_new_key` parameter instructs the function how to handle a principal key during key rotation:
@@ -282,23 +282,23 @@ SELECT pg_tde_is_encrypted('schema.table_name');
 
 This can additionally be used to verify that indexes and sequences are encrypted.
 
-### pg_tde_principal_key_info
+### pg_tde_key_info
 
 Displays information about the principal key for the current database, if it exists.
 
 ```
-SELECT pg_tde_principal_key_info()
+SELECT pg_tde_key_info()
 ```
 
-### pg_tde_server_principal_key_info
+### pg_tde_server_key_info
 
 Displays information about the principal key for the server scope, if exists.
 
 ```
-SELECT pg_tde_server_principal_key_info()
+SELECT pg_tde_server_key_info()
 ```
 
-### pg_tde_verify_principal_key
+### pg_tde_verify_key
 
 This function checks that the current database has a properly functional encryption setup, which means:
 
@@ -311,10 +311,10 @@ This function checks that the current database has a properly functional encrypt
 If any of the above checks fail, the function reports an error.
 
 ```
-SELECT pg_tde_verify_principal_key()
+SELECT pg_tde_verify_key()
 ```
 
-### pg_tde_verify_server_principal_key
+### pg_tde_verify_server_key
 
 This function checks that the server scope has a properly functional encryption setup, which means:
 
@@ -327,5 +327,5 @@ This function checks that the server scope has a properly functional encryption
 If any of the above checks fail, the function reports an error.
 
 ```
-SELECT pg_tde_verify_server_principal_key()
+SELECT pg_tde_verify_server_key()
 ```

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

@@ -117,19 +117,19 @@ You must do these steps for every database where you have created the extension.
 2. Add a principal key
 
     ```sql
-    SELECT pg_tde_set_principal_key_using_database_key_provider('name-of-the-principal-key', 'provider-name','ensure_new_key');
+    SELECT pg_tde_set_key_using_database_key_provider('name-of-the-key', 'provider-name','ensure_new_key');
     ```
 
     where:
 
-    * `name-of-the-principal-key` is the name of the principal key. You will use this name to identify the key.
+    * `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.
 
     <i warning>:material-information: Warning:</i> This example is for testing purposes only:
 
     ```sql
-    SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
+    SELECT pg_tde_set_key_using_database_key_provider('test-db-master-key','file-vault','ensure_new_key');
     ```
 
     The key is auto-generated.

contrib/pg_tde/documentation/docs/setup.md

@@ -112,19 +112,19 @@ Load the `pg_tde` at startup time. The extension requires additional shared memo
 2. Add a default principal key
 
     ```sql
-    SELECT pg_tde_set_default_principal_key_using_global_key_provider('name-of-the-principal-key','provider-name','ensure_new_key');
+    SELECT pg_tde_set_default_key_using_global_key_provider('name-of-the-key','provider-name','ensure_new_key');
     ```
 
     where:
 
-    * `name-of-the-principal-key` is the name of the principal key. You will use this name to identify the key.
+    * `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.
 
     <i warning>:material-information: Warning:</i> This example is for testing purposes only. Replace the key name and provider name with your values:
 
     ```sql
-    SELECT pg_tde_set_principal_key_using_global_key_provider('test-db-master-key','file-vault','ensure_new_key');
+    SELECT pg_tde_set_key_using_global_key_provider('test-db-master-key','file-vault','ensure_new_key');
     ```
 
     The key is auto-generated.

contrib/pg_tde/documentation/docs/test.md

@@ -33,15 +33,7 @@ Here's how to do it:
 
     The function returns `t` if the table is encrypted and `f` - if not.
 
-3. Rotate the principal key when needed:
-
-    ```
-    SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin
-    -- or
-    SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name
-    -- or
-    SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- changeprovider
-    ```
+3. Rotate the principal key when needed, see [Principal key management](functions.md#principal-key-management))
 
 ## Encrypt existing table
 

contrib/pg_tde/documentation/docs/wal-encryption.md

@@ -61,7 +61,7 @@ Here's what to do:
 3. Create principal key
     
     ```sql
-    SELECT pg_tde_set_server_principal_key_using_global_key_provider('principal-key', 'provider-name');
+    SELECT pg_tde_set_server_key_using_global_key_provider('key', 'provider-name');
     ```
 
 4. Enable WAL level encryption using the `ALTER SYSTEM` command. You need the privileges of the superuser to run this command:

contrib/pg_tde/expected/access_control.out

@@ -4,8 +4,8 @@ SET ROLE regress_pg_tde_access_control;
 -- should throw access denied
 SELECT pg_tde_add_database_key_provider_file('file-vault', '/tmp/pg_tde_test_keyring.per');
 ERROR:  permission denied for function pg_tde_add_database_key_provider_file
-SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key', 'file-vault');
-ERROR:  permission denied for function pg_tde_set_principal_key_using_database_key_provider
+SELECT pg_tde_set_key_using_database_key_provider('test-db-key', 'file-vault');
+ERROR:  permission denied for function pg_tde_set_key_using_database_key_provider
 RESET ROLE;
 SELECT pg_tde_grant_database_key_management_to_role('regress_pg_tde_access_control');
  pg_tde_grant_database_key_management_to_role 
@@ -33,9 +33,9 @@ SELECT pg_tde_add_database_key_provider_file('file-2', '/tmp/pg_tde_test_keyring
                                      2
 (1 row)
 
-SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key', 'file-vault');
- pg_tde_set_principal_key_using_database_key_provider 
-------------------------------------------------------
+SELECT pg_tde_set_key_using_database_key_provider('test-db-key', 'file-vault');
+ pg_tde_set_key_using_database_key_provider 
+--------------------------------------------
 
 (1 row)
 
@@ -46,10 +46,10 @@ SELECT * FROM pg_tde_list_all_database_key_providers();
   2 | file-2        | file          | {"type" : "file", "path" : "/tmp/pg_tde_test_keyring_2.per"}
 (2 rows)
 
-SELECT principal_key_name, key_provider_name, key_provider_id FROM pg_tde_principal_key_info();
-  principal_key_name   | key_provider_name | key_provider_id 
------------------------+-------------------+-----------------
- test-db-principal-key | file-vault        |               1
+SELECT key_name, key_provider_name, key_provider_id FROM pg_tde_key_info();
+  key_name   | key_provider_name | key_provider_id 
+-------------+-------------------+-----------------
+ test-db-key | file-vault        |               1
 (1 row)
 
 RESET ROLE;
@@ -63,7 +63,7 @@ SET ROLE regress_pg_tde_access_control;
 -- verify the view access is revoked
 SELECT * FROM pg_tde_list_all_database_key_providers();
 ERROR:  permission denied for function pg_tde_list_all_database_key_providers
-SELECT principal_key_name, key_provider_name, key_provider_id FROM pg_tde_principal_key_info();
-ERROR:  permission denied for function pg_tde_principal_key_info
+SELECT key_name, key_provider_name, key_provider_id FROM pg_tde_key_info();
+ERROR:  permission denied for function pg_tde_key_info
 RESET ROLE;
 DROP EXTENSION pg_tde CASCADE;

contrib/pg_tde/expected/alter_index.out

@@ -5,9 +5,9 @@ SELECT pg_tde_add_database_key_provider_file('file-vault','/tmp/pg_tde_test_keyr
                                      1
 (1 row)
 
-SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key','file-vault');
- pg_tde_set_principal_key_using_database_key_provider 
-------------------------------------------------------
+SELECT pg_tde_set_key_using_database_key_provider('test-db-key','file-vault');
+ pg_tde_set_key_using_database_key_provider 
+--------------------------------------------
 
 (1 row)
 

contrib/pg_tde/expected/cache_alloc.out

@@ -6,9 +6,9 @@ SELECT pg_tde_add_database_key_provider_file('file-vault','/tmp/pg_tde_test_keyr
                                      1
 (1 row)
 
-SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key','file-vault');
- pg_tde_set_principal_key_using_database_key_provider 
-------------------------------------------------------
+SELECT pg_tde_set_key_using_database_key_provider('test-db-key','file-vault');
+ pg_tde_set_key_using_database_key_provider 
+--------------------------------------------
 
 (1 row)
 

contrib/pg_tde/expected/change_access_method.out

@@ -5,9 +5,9 @@ SELECT pg_tde_add_database_key_provider_file('file-vault','/tmp/pg_tde_test_keyr
                                      1
 (1 row)
 
-SELECT pg_tde_set_principal_key_using_database_key_provider('test-db-principal-key','file-vault');
- pg_tde_set_principal_key_using_database_key_provider 
-------------------------------------------------------
+SELECT pg_tde_set_key_using_database_key_provider('test-db-key','file-vault');
+ pg_tde_set_key_using_database_key_provider 
+--------------------------------------------
 
 (1 row)