Using Fortanix Data Security Manager with EDB Postgres for TDE

1.0 Introduction

This article describes the integration procedure for Fortanix-Data-Security-Manager (DSM) and Postgres Enterprise Database (EDB) to enable Transparent Data Encryption (TDE).

This article provides detailed information on the following:

• Enabling secure communication and authentication between Fortanix DSM and Postgres EDB through the utilization of Key Management Interoperability Protocol (KMIP) and certificates.

• Configuring and initializing Fortanix DSM.

• Generating client certificates to enhance security as part of the integration process.

• Generating Postgres master key and encrypting the database.

2.0 KMIP and Certificate Requirements

This section outlines the essential requirements for Key Management Interoperability Protocol (KMIP) and certificates in the integration process. KMIP plays a crucial role in enabling secure communication between EDB Postgres and Fortanix DSM. It leverages Transport Layer Security (TLS) for establishing a secure connection, and Fortanix DSM utilizes this protocol for authenticating KMIP clients to effectively manage and utilize keys stored within Fortanix DSM.

Additionally, X.509 certificates are employed to facilitate secure communication and authentication between both Fortanix DSM and Postgres. Fortanix DSM is configured with a server certificate signed by an internal Certificate Authority (CA). Furthermore, it is necessary to generate a client certificate for EDB Postgres using tools like OpenSSL. This certificate can either be signed externally or self-signed.

3.0 Prerequisites

Ensure the following:

• A functioning EDB Postgres distribution.

• Fortanix DSM version 4.4 or later must be installed and operational.

• Ensure that Fortanix DSM is accessible by EDB Postgres on port 5696 (default) or any custom KMIP port you have configured.

• Users should have access to OpenSSL or another suitable tool for generating a client certificate and private key in the Privacy Enhanced Mail (PEM) format.

• Python and the PyKMIP utility should be installed on your server.

  NOTE

  These are only applicable to versions 15.2 and later of EDB Postgres Advanced Server and versions 15.2 and later of EDB Postgres Extended Server, as these versions support TDE.

4.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

4.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

4.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

4.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group. For example, Postgres.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create a new group.

The new group has been added to the Fortanix DSM successfully.

4.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 4.3: Creating a Group from the list of groups to associate this application with the group.

3. Click the SAVE button to add the new application.

The new application has been added to the Fortanix DSM successfully.

4.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the app created in the Section 4.4: Creating an Application to go to the detailed view of the app.

2. From the top of the app’s page, copy the app UUID to be used in Section 4.7: Generating the Certificate as the value of Common Name (CN) to generate a self-signed certificate and a private key.

4.6 Creating a Security Object

Perform the following steps to generate a key in the Fortanix DSM for use with your database WRAP and UNWRAP commands for encryption:

1. Click the Security Objects menu item in the DSM left navigation bar and click the + button on the Security Objects page to add a security object.

   

2. On the Add New Security Object page, enter the following details:

   • Security Object name: Enter the name of your security object. For example, PostgreSQL_EDB_MK.

   • Group: Select the group as created in Section 4.3: Creating a Group.

   • Select the GENERATE radio button.

   • Choose a type: Select the AES key type.

   • Key Size: Indicates the size of the key in bits.

   • Key operations permitted: Select the required operations to define the actions that can be performed with the cryptographic keys, such as encryption, decryption, signing, and verifying.

     NOTE

     Ensure that the Encrypt and Decrypt permissions are selected.

   • Add the required attributes if required using ADD ATTRIBUTES.

   • Enter the key Deactivation Date and key Activation Date.

3. Click the GENERATE button to create the new security object.

The specific key UUID required for your PGDATAKEYWRAPCMD and PGDATAKEYUNWRAPCMD commands is the ID displayed at the top of your key information page in Fortanix DSM.

4.7 Generating the Certificate

In the event that an application or client requires certificate-based authentication to Fortanix DSM, it is essential to embed the app UUID within the certificate as the value of the Common Name (CN), as described above. For example, CN: ae044928-f670-48d1-a4aa-111baf5640a6.

Perform the following steps to create a self-signed certificate, ensuring you have the app UUID to include in the self-signed certificate:

1. Log in to your EDB Postgres distribution system as the database superuser using the following command:

   sudo su - enterprisedb

2. Create a dsm folder on the Linux machine and enter the folder with the following commands:

   mkdir dsm
   cd dsm

3. Run the following command to generate an RSA key for authentication with Fortanix DSM:

   edbopenssl req -newkey rsa:2048 -nodes -keyout client-key.pem -x509 -days 365 -out client-cert.pem

   When prompted for the Common Name, enter the app UUID you recorded earlier.
   This process will generate two essential files:

   • client-cert.pem

   • client-key.pem

   

   NOTE

   The given procedure is with Self Signed Certificate, but Fortanix DSM can also support CA Signed Certificate, if preferred by the user.

4.8 Updating the Authentication Method

Perform the following steps to change the authentication method:

1. Go to the detailed view of the app created in Section 4.4: Creating an Application and click the Change the authentication method button and select the Certificate option to change the authentication method to Certificate.

2. Click the SAVE button.

3. The certificate content can be read using the command cat client-cert.pem and copied as shown in the picture below:

   

4. On the Add certificate dialog box, click the UPLOAD NEW CERTIFICATE button to upload the certificate file or paste the content of the certificate generated in previous section.

5. Select both the check boxes to confirm your understanding about the action.

6. Click the UPDATE button to save the changes.

5.0 Installing TDE-KMIP Client on the Server

If you do not have the KMIP client installed, perform the following steps to install the edb-tde-kmip-client on your system as a root user:

1. Open a terminal or command prompt.

2. Execute the installation command based on your system.

   For example,

   1. If you are using a Linux RHEL server, run the following command:

      dnf install edb-tde-kmip-client

   2. If you are using an Ubuntu server, run the following command:

      apt-get install edb-tde-kmip-client

6.0 Creating the pykmip.conf File

Perform the following steps to configure the pykmip.conf file:

1. On the system where your EDB Postgres distribution is located, navigate to /usr/lib/edb/kmip/ to access the edb_tde_kmip_client.py client.

2. In the /usr/lib/edb/kmip directory, create a file named pykmip.conf and provide the following configuration details:

   • Host: The Fully Qualified Domain Names (FQDN) of the KMIP hosts.

   • Port: The KMIP port, typically set to 5696.

   • Keyfile: The path to the PEM-encoded client certificate key file.

   • Certfile: The path to the PEM-encoded client certificate file.

   • ca_certs: The path to the Fortanix DSM certificate chain. The Fortanix DSM certificate chain shall be retrieved from the browser when navigating to the respective DSM URL (example: eu.smartkey.io).
     For example:

     [client]
     host=<DSM_URL>
     port=5696
     keyfile=/var/lib/edb/dsm/client-key.pem 
     certfile=/var/lib/edb/dsm/client-cert.pem
     ca_certs=/var/lib/edb/dsm/ca.pem 

     For more information on the pykmip.conf file and its contents, refer to the PyKMIP documentation.

7.0 Verifying Encryption and Decryption

To ensure that the key you have created can successfully encrypt and decrypt data, execute the following two commands as the superuser on your system with the EDB Postgres distribution:

7.1 Encrypt the Data

Run the following command: If encryption is successful without any error, the file test.bin will be created. The corresponding encryption logs are available in the Fortanix DSM.

python3 /usr/edb/kmip/client/edb_tde_kmip_client.py encrypt --out-file=test.bin --pykmip-config-file=/var/lib/edb/dsm/pykmip.conf --key-uid='173bb3c8-ef16-4e4e-b066-54fe72cdd296' --variant=pykmip

Where,

• KMIP client Location: /usr/edb/kmip/client/edb_tde_kmip_client.py

• Output file: test.bin

• Location of PyKMIP configuration file: /var/lib/edb/dsm/pykmip.conf

• Encrypted key output: TDE key output.

• Variant: Allows for KMIP compatibility with Fortanix.

7.2 Decrypt the Data

Run the following command:

python3 /usr/edb/kmip/client/edb_tde_kmip_client.py decrypt --in-file=test.bin --pykmip-config-file=/var/lib/edb/dsm/pykmip.conf --key-uid='173bb3c8-ef16-4e4e-b066-54fe72cdd296' --variant=pykmip

If successful, the decryption command will produce the output of the original "secret." The corresponding encryption and decryption logs are available in the Fortanix DSM.

8.0 Performing initdb for the Database

After creating the key and verifying encryption and decryption, you can export the PGDATAKEYWRAPCMD and PGDATAKEYUNWRAPCMD to wrap and unwrap your encryption key and initialize your database.

Perform the following steps:

1. Navigate to the /bin directory where your executables are located. For example:

   cd /usr/edb/as15/bin

2. Perform your initdb as required for your database, for example:

   ./initdb --data-encryption -D /var/lib/edb/as15/data

3. If the initialization is successful, your output should confirm this.

   

4. Start your database using the following command:

   ./pg_ctl -D /var/lib/edb/as15/data -l logfile start

   

5. Navigate to your /data directory to view the postgresql.conf file. Ensure that your data_encryption_key_unwrap_command, which you have set with export PGDATAUNWRAPCMD, is present under the Authentication section in the postgresql.conf file.

For more information on how Transparent Data Encryption (TDE) is integrated with EDB Postgres Advanced Server and EDB Postgres Extended Server, refer to the EDB Transparent Data Encryption documentation.