1. Fortanix
  2. Fortanix Data Security Manager (DSM)
  3. Integration / Use-case
  4. Transparent Data Encryption

Using Fortanix Data Security Manager with EDB Postgres for TDE

Last Updated: 

1.0 Introduction

This document describes the integration procedure for Fortanix Data Security Manager (DSM) and Postgres Enterprise Database (EDB) to enable Transparent Data Encryption (TDE). This document 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.

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.

2.1 Prerequisites

Before proceeding with the integration of Fortanix DSM and EDB Postgres for Transparent Data Encryption, ensure you have 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.

3.0 Configuring the Fortanix DSM Application and Account

Fortanix DSM facilitates KMIP client authentication through applications (apps). To establish a successful connection between EDB Postgres and Fortanix DSM for authentication, EDB Postgres requires the extraction of the Fortanix DSM internal CA certificate.
Perform the following steps to set up an application in Fortanix DSM:

  1. Log in to the Fortanix DSM user interface.
  2. Click the Application menu item from the Fortanix DSM left navigation bar and create a new application. For detailed instructions on adding a group or application, refer to User’s Guide: Getting Started with Fortanix Data Security Manager - UI.
  3. On the Create Application page, enter the following details:
    1. App name: Enter a name to identify your EDB Postgres database (customizable).
    2. Interface: Select the interface as REST API.
    3. Authentication method: Select the authentication method as API Key. This will be updated later.
    4. Assign the new app to group: The keys generated by EDB Postgres will be associated with this group.
      FIGURE 1.png
      Figure 1: Create EDP Postgres App
  4. After you have added the application, copy the app UUID from the app table view by clicking the overflow menu and selecting the Copy UUID option. This app UUID will serve as the Common Name (CN) when generating the client certificate. For example: app UUID = dec49b69-9961-4010-a596-c79df4477f6b.

4.0 Creating a Certificate with App UUID as Common Name

In the event that an application or client requires authentication to Fortanix DSM using only a certificate, it is essential to embed the app UUIID within the certificate as the value of the Common Name (CN). 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. Run the following command to change the directory to dsm:
    mkdir dsm
  2. 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

5.0 Configuration on EDB Postgres Node

Perform the following steps to set up a folder for certificates and keys on your EDB Postgres node:

  1. Run the following commands to create a folder for certificates and keys:
    pwd /var/lib/edb
  2. Run the following command to navigate to directory dsm directory:
    cd dsm
  3. Run the following command to create a self-signed certificate, ensuring you have the app UUID readily available as it will be used to update the Common Name for the self-signed certificate.
    openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -x509 -days 365 -out client-cert.pem
    This command will generate two files:
    • client-cert.pem
    • client-key.pem
      Screenshot 2023-11-10 225839.png

6.0 Updating the Certificate in Fortanix DSM

Perform the following steps to update the certificate in the account level authentication method:

  1. Navigate to Settings →  CLIENT CONFIGURATION →  KMIP tab.
  2. Enable the Allow secrets with unknown operations option.
  3. Click the SAVE button.
    FIGURE 2.png
    Figure 2: Update Client Configuration

7.0 Changing Application Authentication Method

Perform the following steps to update the certificate in the application:

  1. In the detailed view of the app, under the INFO tab, click the Change authentication method option from the drop down menu and select Certificate as the new authentication method for the app.
    Screenshot 2023-11-10 230109.png
  2. In the Add certificate form, click the UPLOAD NEW CERTIFICATE to upload the new certificate or paste the generated certificate in the Upload Certificate text box provided.
    FIGURE 3.png
    Figure 3: Select Certificate
  3. Click the UPDATE button to update the app authentication method to certificate.
    FIGURE 4.png
    Figure 4: Add Certificate

8.0 Installing TDE-KMIP Client on the Server

Before proceeding, make sure that your system already has the required software, including Python and PyKMIP, 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, if you are using a RHEL8 server, run the following command:
    dnf install edb-tde-kmip-client

9.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 the directory where you have saved your .pem files and the edb_tde_kmip_client.py client.
  2. In that 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.
      For example:
      Screenshot 2023-11-10 230406.png
      For more information on the pykmip.conf file and its contents, refer to the PyKMIP documentation.

10.0 Creating a Key on Fortanix DSM

There are two methods to create a key using Fortanix DSM:

  • Local Creation with Python 3: You can locally create a key using Python 3.
  • Using the Fortanix DSM UI: Alternatively, you can use the Fortanix DSM UI to create a key.

10.1 Create a Key Locally with Python 3

Perform the following steps to create a key on Fortanix DSM using Python 3 locally:

  1. Log in to the system with your EDB Postgres distribution as the database superuser.
  2. Open a Python 3 session and enter the following commands, adjusting them according to your system setup and directory paths:
    >>> from kmip.pie import client
    >>> from kmip import enums
    >>> c = client.ProxyKmipClient(config_file='/tmp/pykmip.conf')
    >>> c.open()
    >>> key_id = c.create(enums.CryptographicAlgorithm.AES, 128, name='edbtestkey01')
    (`edbtestkey01` is the name that we chose for our TDE master key. Alter this per your naming requirements.)
    >>> c.activate(key_id)
    >>> key_id
    >>> 'key_output_shows_here'
    >>> c.close()
  3. Go to Fortanix DSM and click the Groups menu item.
  4. From the Groups table, click the group and in the detailed view of that group, select the Security Objects tab.
  5. Verify that the key you created, such as "edbtestkey01" in this example, is listed.
    FIGURE 5.png
    Figure 5: Select the Key

10.2 Create a Key in Fortanix DSM UI

Perform the following steps to create keys for use with your database WRAP and UNWRAP commands for encryption in the Fortanix DSM UI:

  1. Log in to Fortanix Data Security Manager and select the required Account.
  2. From the left navigation bar, select the Groups menu item.
  3. Click the group and in the detailed view of that group, select the Security Objects tab.
  4. To create a key, click the ADD SECURITY OBJECT button.
    FIGURE 6.png
    Figure 6: Add Security Object Button
  5. Provide a name for the security object, and any additional Metadata as needed.
    FIGURE 7.png
    Figure 7: Add Security Object Details
  6. 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.
    FIGURE 8.png
    Figure 8: Copy the UUID

11.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:

11.1 Encrypt Data

Run the following command:

secret | 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.

11.2 Decrypt 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.
FIGURE 9.png
Figure 9: Log Details

12.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. Log in to your EDB Postgres distribution system as the database superuser. For example:
    sudo su - enterprisedb
  2. Navigate to the /bin directory where your executables are located. For example:
    /usr/edb/as15/bin
  3. Run the following command to export the Wrap key:
    export PGDATAKEYWRAPCMD='python3 /usr/edb/kmip/client/edb_tde_kmip_client.py encrypt --pykmip-config-file=/var/lib/edb/dsm/pykmip.conf --key-uid='173bb3c8-ef16-4e4e-b066-54fe72cdd296' --out-file=%p --variant=pykmip'
  4. Run the following command to export the Unwrap key:
    export PGDATAKEYUNWRAPCMD='python3 /usr/edb/kmip/client/edb_tde_kmip_client.py decrypt --pykmip-config-file=/var/lib/edb/dsm/pykmip.conf --key-uid='173bb3c8-ef16-4e4e-b066-54fe72cdd296' --in-file=%p --variant=pykmip'
  5. Perform your initdb as required for your database, for example:
    ./initdb --data-encryption -D /var/lib/edb/as15/data
    OR
    ./initdb -D /var/lib/edb/as15/data -y
  6. If the initialization is successful, your output should confirm this.
  7. Start your database and navigate to your /data directory to view the postgresql.conf file:
    ./pg_ctl -D /var/lib/edb/as15/data -l logfile start
  8. 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.

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful