Using Fortanix Data Security Manager with EDB Postgres for TDE

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

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

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

Screenshot 2024-05-16 163815.png

Figure 2: Logging In

3.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 to add a new group.
    Screenshot 2024-05-16 163755.png
    Figure 3: Add Groups
  2. On the Adding new group page, enter the following details:
    • Title: Enter a title for your group.
    • Description (optional): Enter a short description for the group.
    • Add Group Quorum Policy: Specify the quorum policy for the group. This setting determines the number of approvals required for security-sensitive operations within the group. Adjust this policy based on your security requirements. For detailed information, refer to User's Guide: Group Quorum Policy documentation.
  3. Click the SAVE button to create the new group.

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

3.4 Creating an App

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

  1. Click the Apps menu item in the DSM left navigation bar and click the + button to add a new app.
    Screenshot 2024-05-16 163738.png
    Figure 4: Add Application
  2. On the Adding new app page, enter the following details:
    • App name: Enter the name of your application.
    • Interface (optional): Select the interface type as KMIP from the drop down menu.
    • ADD DESCRIPTION (optional): Enter a short description for the application.
    • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.
      • Set app secret key size: Select the required size of the application secret key in bytes from the drop down menu.
    • Assigning the new app to groups: Select one or more group names from the drop down menu to associate this application with that group(s).
  3. Click the Save button to add the new application.

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

3.5 Copying an API Key

Perform the following steps to copy the API key from the Fortanix DSM:

  1. Click the Apps menu item in the DSM left navigation bar and click the required app from the list of apps.
  2. On the INFO tab, click the VIEW API KEY DETAILS button.
  3. From the API Key Details dialog box, copy the API Key of the app to use it later while configuring the Fortanix DSM. 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 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 in the previous section. 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 create dsm directory:
    mkdir dsm
  2. Run the following command to change the directory to dsm:
    cd dsm
  3. Run the following command to generate an RSA key for authentication with Fortanix DSM:
    openssl 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