Configure Multi-tenancy

The steps below describe how to set up multi-tenancy with open_pg_tde. Multi-tenancy allows you to encrypt different databases with different keys. This provides granular control over data and enables you to introduce different security policies and access controls for each database so that only authorized users of specific databases have access to the data.

If you don’t need multi-tenancy, use the global key provider. See the configuration steps from the Configure open_pg_tde section.

For how to enable WAL encryption, refer to the Configure WAL Encryption section.

Considerations

You can use external key providers to manage encryption keys. The recommended approach is to use the Key Management Store (KMS). For more information, see Configure Key Management (KMS) .

Note

If no error is reported when running the commands below, the operation completed successfully.

Enable extension

Load the open_pg_tde at startup time. The extension requires additional shared memory; therefore, add the open_pg_tde value for the shared_preload_libraries parameter and restart the postgresql cluster.

1. Use the ALTER SYSTEM command from psql terminal to modify the shared_preload_libraries parameter. This requires superuser privileges.

   ALTER SYSTEM SET shared_preload_libraries = 'open_pg_tde';
   

2. Start or restart the postgresql cluster to apply the changes.

   • On Debian and Ubuntu:

   sudo systemctl restart postgresql
   

   • On RHEL and derivatives

   sudo systemctl restart postgresql-17
   

3. Create the extension using the CREATE EXTENSION command. You must have the privileges of a superuser or a database owner to use this command. Connect to psql as a superuser for a database and run the following command:

   CREATE EXTENSION open_pg_tde;
   

   The open_pg_tde extension is created for the currently used database. To enable data encryption in other databases, you must explicitly run the CREATE EXTENSION command against them.

   Tip

   You can have the open_pg_tde extension automatically enabled for every newly created database. Modify the template template1 database as follows:

   psql -d template1 -c 'CREATE EXTENSION open_pg_tde;'
   

Key provider configuration

You must do these steps for every database where you have created the extension. For more information on configurations, please see the Configure Key Management (KMS) topic.

1. Set up a key provider.

   With KMIP serverWith a keyring file (not recommended)

   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.

   For testing purposes, you can use the Eviden KMS 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.

   SELECT open_pg_tde_add_database_key_provider_kmip(
     'provider-name',
     'kmip-addr', 
     `port`, 
     '/path_to/client_cert.pem', 
     '/path_to/client_key.pem', 
     '/path_to/server_certificate.pem'
   );
   

   where:

   • provider-name is the name of the provider. You can specify any name, it’s for you to identify the provider.
   • kmip-addr is the IP address of a domain name of the KMIP server
   • port is the port to communicate with the KMIP server. Typically used port is 5696.
   • server-certificate is the path to the certificate file for the KMIP server.
   • client-cert is the path to the client certificate.
   • client-key is the path to the client key.

   Warning: This example is for testing purposes only:

   SELECT open_pg_tde_add_database_key_provider_kmip(
       'kmip', 
       '127.0.0.1', 
       5696, 
       '/tmp/client_cert_jane_doe.pem', 
       '/tmp/client_key_jane_doe.pem', 
       '/tmp/server_certificate.pem'
   );
   

   This setup is intended for development and stores the keys unencrypted in the specified data file.

   SELECT open_pg_tde_add_database_key_provider_file(
       'provider-name', 
       '/path/to/the/keyring/data.file'
   );
   

   Warning: This example is for testing purposes only:

   SELECT open_pg_tde_add_database_key_provider_file(
       'file-keyring', 
       '/tmp/open_pg_tde_test_local_keyring.per'
   );
   

2. Create a key

   SELECT open_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 is associated with this provider and it is the location where it is stored and fetched from.

   Warning: This example is for testing purposes only:

   SELECT open_pg_tde_create_key_using_database_key_provider(
       'test-db-master-key', 
       'file-keyring'
   );
   

   Note

   The key is auto-generated.

3. Use the key as principal key

   SELECT open_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.

   Warning: This example is for testing purposes only:

   SELECT open_pg_tde_set_key_using_database_key_provider(
       'test-db-master-key',
       'file-keyring'
   );