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.
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.
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:
- Log in to the Fortanix DSM user interface.
- 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.
- On the Create Application page, enter the following details:
- App name: Enter a name to identify your EDB Postgres database (customizable).
- Interface: Select the interface as REST API.
- Authentication method: Select the authentication method as API Key. This will be updated later.
Assign the new app to group: The keys generated by EDB Postgres will be associated with this group.
Figure 1: Create EDP Postgres App
- 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:
- Run the following command to change the directory to
- 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
This process will generate two essential files:
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:
- Run the following commands to create a folder for certificates and keys:
- Run the following command to navigate to directory
- 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
6.0 Updating the Certificate in Fortanix DSM
Perform the following steps to update the certificate in the account level authentication method:
- Navigate to Settings → CLIENT CONFIGURATION → KMIP tab.
- Enable the Allow secrets with unknown operations option.
- Click the SAVE button.
Figure 2: Update Client Configuration
7.0 Changing Application Authentication Method
Perform the following steps to update the certificate in the application:
- 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.
- 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: Select Certificate
- Click the UPDATE button to update the app authentication method to certificate.
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:
- Open a terminal or command prompt.
- 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
- On the system where your EDB Postgres distribution is located, navigate to the directory where you have saved your
.pemfiles and the
- In that directory, create a file named
pykmip.confand provide the following configuration details:
- Host: The Fully Qualified Domain Names (FQDN) of the KMIP hosts.
Port: The KMIP port, typically set to
- 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 more information on the
pykmip.conffile 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:
- Log in to the system with your EDB Postgres distribution as the database superuser.
- 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')
>>> 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.)
- Go to Fortanix DSM and click the Groups menu item.
- From the Groups table, click the group and in the detailed view of that group, select the Security Objects tab.
- Verify that the key you created, such as "edbtestkey01" in this example, is listed.
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:
- Log in to Fortanix Data Security Manager and select the required Account.
- From the left navigation bar, select the Groups menu item.
- Click the group and in the detailed view of that group, select the Security Objects tab.
- To create a key, click the ADD SECURITY OBJECT button.
Figure 6: Add Security Object Button
- Provide a name for the security object, and any additional Metadata as needed.
Figure 7: Add Security Object Details
- The specific key UUID required for your
PGDATAKEYUNWRAPCMDcommands is the ID displayed at the top of your key information page in Fortanix DSM.
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
KMIP client Location:
Location of PyKMIP configuration file:
- 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: Log Details
12.0 Performing initdb for the Database
After creating the key and verifying encryption and decryption, you can export the
PGDATAKEYUNWRAPCMD to wrap and unwrap your encryption key and initialize your database.
Perform the following steps:
- Log in to your EDB Postgres distribution system as the database superuser. For example:
sudo su - enterprisedb
- Navigate to the
/bindirectory where your executables are located. For example:
- 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'
- 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'
- Perform your
initdbas required for your database, for example:
./initdb --data-encryption -D /var/lib/edb/as15/data
./initdb -D /var/lib/edb/as15/data -y
- If the initialization is successful, your output should confirm this.
- Start your database and navigate to your
/datadirectory to view the
./pg_ctl -D /var/lib/edb/as15/data -l logfile start
- Ensure that your
data_encryption_key_unwrap_command, which you have set with export
PGDATAUNWRAPCMD, is present under the Authentication section in the
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.