Renamed master key to principal key (#228)

This commit contains lots of changes, but it's just a repeated execution of find <...> -exec sed <...>, so everything should work as before.
Percona-Lab · Jun 27, 2024 · 2a4f0d8 · 2a4f0d8
1 parent a21bfac
commit 2a4f0d8
Show file tree

Hide file tree

Showing 57 changed files with 1,237 additions and 1,237 deletions.
diff --git a/.github/workflows/postgresql-16-src-meson-perf.yml b/.github/workflows/postgresql-16-src-meson-perf.yml
@@ -91,7 +91,7 @@ jobs:
           bin/createuser sbtest -s
           bin/psql sbtest2 <<< "CREATE EXTENSION pg_tde;"
           bin/psql sbtest2 <<< "SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per');"
-          bin/psql sbtest2 <<< "SELECT pg_tde_set_master_key('test-db-master-key','file-vault');"
+          bin/psql sbtest2 <<< "SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');"
           cp -r ../src/contrib/pg_tde/sysbench .
         working-directory: inst
 

diff --git a/Makefile.in b/Makefile.in
@@ -44,7 +44,7 @@ src/keyring/keyring_vault.o \
 src/keyring/keyring_api.o \
 src/catalog/tde_global_catalog.o \
 src/catalog/tde_keyring.o \
-src/catalog/tde_master_key.o \
+src/catalog/tde_principal_key.o \
 src/common/pg_tde_shmem.o \
 src/common/pg_tde_utils.o \
 src/smgr/pg_tde_smgr.o \

diff --git a/README.md b/README.md
@@ -65,15 +65,15 @@ FUNCTION pg_tde_add_key_provider_file(
 SELECT pg_tde_add_key_provider_file('file','/tmp/pgkeyring');
 ```
 **Note: The `File` provided is intended for development and stores the keys unencrypted in the specified data file.**
-6. Set the master key for the database using the `pg_tde_set_master_key` function.
+6. Set the principal key for the database using the `pg_tde_set_principal_key` function.
 ```sql
-FUNCTION pg_tde_set_master_key (
-                master_key_name VARCHAR(255), 
+FUNCTION pg_tde_set_principal_key (
+                principal_key_name VARCHAR(255), 
                 provider_name VARCHAR(255));
 ```
-**Example**: Set the master key named `my-master-key` using the `file` as a key provider.
+**Example**: Set the principal key named `my-principal-key` using the `file` as a key provider.
 ```sql
-SELECT pg_tde_set_master_key('my-master-key','file');
+SELECT pg_tde_set_principal_key('my-principal-key','file');
 ```
 
 7. You are all set to create encrypted tables. For that, specify `USING pg_tde` in the `CREATE TABLE` statement.

diff --git a/documentation/docs/functions.md b/documentation/docs/functions.md
@@ -33,24 +33,24 @@ where:
 
 All parameters can be either strings, or JSON objects [referencing remote parameters](external-parameters.md).
 
-## pg_tde_set_master_key
+## pg_tde_set_principal_key
 
-Sets the master key for the database using the specified key provider.
+Sets the principal key for the database using the specified key provider.
 
-The master key name is also used for constructing the name in the provider, for example on the remote Vault server.
+The principal key name is also used for constructing the name in the provider, for example on the remote Vault server.
 
-You can use this function only to a master key. For changes in the master key, use the [`pg_tde_rotate_key`](#pg_tde_rotate_key) function.
+You can use this function only to a principal key. For changes in the principal key, use the [`pg_tde_rotate_key`](#pg_tde_rotate_key) function.
 
 ```sql
-SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name');
+SELECT pg_tde_set_principal_key('name-of-the-principal-key', 'provider-name');
 ```
 
 ## pg_tde_rotate_key
 
-Creates a new version of the specified master key and updates the database so that it uses the new master key version.
+Creates a new version of the specified principal key and updates the database so that it uses the new principal key version.
 
 When used without any parameters, the function will just create a new version of the current database
-master key, using the same provider:
+principal key, using the same provider:
 
 ```sql
 SELECT pg_tde_rotate_key();
@@ -59,16 +59,16 @@ SELECT pg_tde_rotate_key();
 Alternatively, you can pass two parameters to the function, specifying both a new key name and a new provider name:
 
 ```sql
-SELECT pg_tde_rotate_key('name-of-the-new-master-key', 'name-of-the-new-provider');
+SELECT pg_tde_rotate_key('name-of-the-new-principal-key', 'name-of-the-new-provider');
 ```
 
 Both parameters support the `NULL` value, which means that the parameter won't be changed:
 
 ```sql
--- creates  new master key on the same provider as before
-SELECT pg_tde_rotate_key('name-of-the-new-master-key', NULL);
+-- creates  new principal key on the same provider as before
+SELECT pg_tde_rotate_key('name-of-the-new-principal-key', NULL);
 
--- copies the current master key to a new provider
+-- copies the current principal key to a new provider
 SELECT pg_tde_rotate_key(NULL, 'name-of-the-new-provider');
 ```
 

diff --git a/documentation/docs/release-notes/release-notes.md b/documentation/docs/release-notes/release-notes.md
@@ -10,7 +10,7 @@
 
 The technical preview of the extension introduces the following key features:
 
-* You can now rotate master keys used for data encryption. This reduces the risk of long-term exposure to potential attacks and helps you comply with security standards such as GDPR, HIPAA, and PCI DSS.
+* You can now rotate principal keys used for data encryption. This reduces the risk of long-term exposure to potential attacks and helps you comply with security standards such as GDPR, HIPAA, and PCI DSS.
 
 * You can now configure encryption differently for each database. For example, encrypt specific tables in some databases with different encryption keys while keeping others non-encrypted.
 

diff --git a/documentation/docs/setup.md b/documentation/docs/setup.md
@@ -63,10 +63,10 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
         ```
 
 
-5. Add a master key
+5. Add a principal key
 
     ```sql
-    SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name');
+    SELECT pg_tde_set_principal_key('name-of-the-principal-key', 'provider-name');
     ```
 
    <i info>:material-information: Info:</i> The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup.

diff --git a/documentation/docs/tde.md b/documentation/docs/tde.md
@@ -7,19 +7,19 @@ Transparent Data Encryption offers encryption at the file level and solves the p
 To encrypt the data, two types of keys are used:
 
 * Database keys to encrypt user data. These are stored internally, near the data that they encrypt.
-* The master key to encrypt database keys. It is kept separately from the database keys and is managed externally. 
+* The principal key to encrypt database keys. It is kept separately from the database keys and is managed externally. 
 
-`pg_tde` is integrated with HashiCorp Vault server to store and manage master keys. Only the back end KV Secrets Engine - Version 2 (API) is supported.
+`pg_tde` is integrated with HashiCorp Vault server to store and manage principal keys. Only the back end KV Secrets Engine - Version 2 (API) is supported.
 
 The encryption process is the following:
 
 ![image](_images/tde-flow.png)
 
 When a user creates an encrypted table using `pg_tde`, a new random key is generated for that table. This key is used to encrypt all data the user inserts in that table. Eventually the encrypted data gets stored in the underlying storage. 
 
-The table itself is encrypted using the master key. The master key is stored externally in the Vault key management store. 
+The table itself is encrypted using the principal key. The principal key is stored externally in the Vault key management store. 
 
-Similarly when the user queries the encrypted table, the master key is retrieved from the key store to decrypt the table. Then the same unique internal key for that table is used to decrypt the data, and unencrypted data gets returned to the user. So, effectively, every TDE table has a unique key, and each table key is encrypted using the master key.
+Similarly when the user queries the encrypted table, the principal key is retrieved from the key store to decrypt the table. Then the same unique internal key for that table is used to decrypt the data, and unencrypted data gets returned to the user. So, effectively, every TDE table has a unique key, and each table key is encrypted using the principal key.
 
 ## Why do you need TDE?
 

diff --git a/documentation/docs/test.md b/documentation/docs/test.md
@@ -24,12 +24,12 @@ To check if the data is encrypted, do the following:
 
     The function returns `t` if the table is encrypted and `f` - if not.
 
-3. Rotate the master key when needed:
+3. Rotate the principal key when needed:
 
     ```sql
     SELECT pg_tde_rotate_key(); -- uses automatic key versionin
     -- or
-    SELECT pg_tde_rotate_key('new-master-key', NULL); -- specify new key name
+    SELECT pg_tde_rotate_key('new-principal-key', NULL); -- specify new key name
     -- or
-    SELECT pg_tde_rotate_key('new-master-key', 'new-provider'); -- change provider
+    SELECT pg_tde_rotate_key('new-principal-key', 'new-provider'); -- change provider
     ```
diff --git a/expected/change_access_method.out b/expected/change_access_method.out
@@ -5,9 +5,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/insert_update_delete.out b/expected/insert_update_delete.out
@@ -5,9 +5,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/keyprovider_dependency.out b/expected/keyprovider_dependency.out
@@ -17,16 +17,16 @@ SELECT pg_tde_add_key_provider_vault_v2('V2-vault','vault-token','percona.com/va
                                 3
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','mk-file');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','mk-file');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 
 -- Try dropping the in-use key provider
 DELETE FROM percona_tde.pg_tde_key_provider WHERE provider_name = 'mk-file'; -- Should fail
 ERROR:  Key provider "mk-file" cannot be deleted
-DETAIL:  The master key for the database depends on this key provider.
+DETAIL:  The principal key for the database depends on this key provider.
 -- Now delete the un-used  key provider
 DELETE FROM percona_tde.pg_tde_key_provider WHERE provider_name = 'free-file'; -- Should pass
 DELETE FROM percona_tde.pg_tde_key_provider WHERE provider_name = 'V2-vault'; -- Should pass

diff --git a/expected/move_large_tuples.out b/expected/move_large_tuples.out
@@ -6,9 +6,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/multi_insert.out b/expected/multi_insert.out
@@ -7,9 +7,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/non_sorted_off_compact.out b/expected/non_sorted_off_compact.out
@@ -7,9 +7,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/pgtde_is_encrypted.out b/expected/pgtde_is_encrypted.out
@@ -1,16 +1,16 @@
 CREATE EXTENSION pg_tde;
-SELECT  * FROM pg_tde_master_key_info();
-ERROR:  Master key does not exists for the database
-HINT:  Use set_master_key interface to set the master key
+SELECT  * FROM pg_tde_principal_key_info();
+ERROR:  Principal key does not exists for the database
+HINT:  Use set_principal_key interface to set the principal key
 SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per');
  pg_tde_add_key_provider_file 
 ------------------------------
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 
@@ -48,11 +48,11 @@ SELECT pgtde_is_encrypted('test_norm');
  f
 (1 row)
 
-SELECT  key_provider_id, key_provider_name, master_key_name
-		FROM pg_tde_master_key_info();
- key_provider_id | key_provider_name |  master_key_name   
------------------+-------------------+--------------------
-               1 | file-vault        | test-db-master-key
+SELECT  key_provider_id, key_provider_name, principal_key_name
+		FROM pg_tde_principal_key_info();
+ key_provider_id | key_provider_name |  principal_key_name   
+-----------------+-------------------+-----------------------
+               1 | file-vault        | test-db-principal-key
 (1 row)
 
 DROP TABLE test_enc;

diff --git a/expected/test_issue_153_fix.out b/expected/test_issue_153_fix.out
@@ -1,17 +1,17 @@
 CREATE EXTENSION pg_tde;
 SET datestyle TO 'iso, dmy';
-SELECT  * FROM pg_tde_master_key_info();
-ERROR:  Master key does not exists for the database
-HINT:  Use set_master_key interface to set the master key
+SELECT  * FROM pg_tde_principal_key_info();
+ERROR:  Principal key does not exists for the database
+HINT:  Use set_principal_key interface to set the principal key
 SELECT pg_tde_add_key_provider_file('file-ring','/tmp/pg_tde_test_keyring.per');
  pg_tde_add_key_provider_file 
 ------------------------------
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-ring');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-ring');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/toast_decrypt.out b/expected/toast_decrypt.out
@@ -5,9 +5,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/toast_extended_storage.out b/expected/toast_extended_storage.out
@@ -6,9 +6,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/trigger_on_view.out b/expected/trigger_on_view.out
@@ -5,9 +5,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/update_compare_indexes.out b/expected/update_compare_indexes.out
@@ -5,9 +5,9 @@ SELECT pg_tde_add_key_provider_file('file-vault','/tmp/pg_tde_test_keyring.per')
                             1
 (1 row)
 
-SELECT pg_tde_set_master_key('test-db-master-key','file-vault');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('test-db-principal-key','file-vault');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/expected/vault_v2_test.out b/expected/vault_v2_test.out
@@ -6,9 +6,9 @@ SELECT pg_tde_add_key_provider_vault_v2('vault-v2',:'root_token','http://127.0.0
                                 1
 (1 row)
 
-SELECT pg_tde_set_master_key('vault-v2-master-key','vault-v2');
- pg_tde_set_master_key 
------------------------
+SELECT pg_tde_set_principal_key('vault-v2-principal-key','vault-v2');
+ pg_tde_set_principal_key 
+--------------------------
  t
 (1 row)
 

diff --git a/meson.build b/meson.build
@@ -43,7 +43,7 @@ pg_tde_sources = files(
 
         'src/catalog/tde_global_catalog.c',
         'src/catalog/tde_keyring.c',
-        'src/catalog/tde_master_key.c',
+        'src/catalog/tde_principal_key.c',
         'src/common/pg_tde_shmem.c',
         'src/common/pg_tde_utils.c',
         'src/pg_tde_defs.c',