Using Thales REST API for EDB TDE integration

You can configure TDE to use an external key from Thales CipherTrust Manager to wrap the data encryption key. This integration uses Thales REST API to allow cryptographic operations by directly connecting to Thales CipherTrust Manager, bypassing other intermediate protocols.

To implement this integration, EDB provides two scripts that simplify processes:

• edb_tde_createkey.py uses the REST API to help you create an AES key on CipherTrust Manager.

• edb_tde_crypto.py uses the REST API to help you set up encryption and decryption commands with the created AES key.

Overview

The configuration process consists in the following steps:

1. Prerequisites

2. Installing the EDB TDE Thales REST API client integration packages

3. Creating a certificate for authentication

4. Creating an AES key on Thales CipherTrust Manager

5. Integrating with TDE for encryption and decryption

Prerequisites

• Ensure you have Python3 installed. You can check with python3 --version. Otherwise, install it.
• Ensure your Python3 installation includes the base64 encode and decode library (included by default).
• Install the /jq command line JSON parser.

Installing the EDB TDE Thales REST API client packages

edb_tde_createkey.py and edb_tde_crypto.py are provided via a downloadable package you can obtain from the EDB repository.

See Installing EDB TDE Thales REST for instructions.

Creating a certificate for authentication

Create a Certificate Signing Request (CSR) and then provide that CSR to a Certificate Authority (CA), so it can generate a certificate.

1. Access your Thales CipherTrust Manager instance.

2. Navigate to the CSR tool under CA:

   

3. Create a CSR. Ensure you select the RSA option, 2048 size and then select Create:

   

4. In the same pop-up window, after the certificate has been created, select save csr and save private key to download a CSR.pem and key.pem file.

   

5. Provide a CSR to a certificate authority (CA) so it can generate a certificate. Navigate to CA > Local.

   

6. Select a CA. You can use the default local CA provided by CipherTrust. Then, select Upload CSR:

   

7. Enter the previously assigned Display name, paste the contents of the downloaded CSR.pem file and select Issue Certificate:

   

8. Download the Certificate.pem certificate:

   

9. Update your user configuration to allow certificate-based login. Navigate to Access Management > Users and select your user.

10. Under LOGIN, enable Allow user to login using certificate, and enter a Certificate Subject Distinguished Name with CN= prefix:

    

You should now have downloaded three pem files: CSR.pem, key.pem and Certificate.pem. Ensure you store them in an accessible location.

Creating an AES key on Thales CipherTrust Manager

To create an AES 256 key, you can execute the downloaded script, which ensures the necessary key configuration parameters for EDB TDE are given.

1. Point at the IP of the server hosting the Thales CipherTrust Manager instance:

   → WrapCopy

   export SERVER_IP='44.200.166.163'

2. Provide paths where the Certificate.pem and key.pem files are stored:

   → WrapCopy

   export CERTIFICATE_PATH='/home/edb/Downloads/Certificate.pem'
   export KEY_PATH='/home/edb/Downloads/key.pem'

3. Reference the Thales username you used to create the AES key:

   → WrapCopy

   export SERVER_USER='user' 

4. Execute edb_tde_createkey.py to create they key. To execute it correctly, you need:

   • A key name to identify your key. Replace key_name in the example with an identifiable name of your choice.

   • The uid of the user that created the certificate. You can find the user uid in the Thales CipherTrust Manager, under Access Management > Users, select your user. The user uid information is a sequence of digits and letters, e.g. local|285xxxfb-xxxb-4xxx-9339-2d58xxx60ae6.

   • The path to the edb_tde_createkey.py script installed by the packages. In RPM-based systems, the default location is /usr/edb/tde/rest/client/edb_tde_createkey.py and in Debian, /usr/lib/edb/tde/rest/client/edb_tde_createkey.py.

   Replace these values in the example:

   → WrapCopy

   python3 /usr/edb/tde/rest/client/edb_tde_createkey.py \
     <key_name> "<local|285xxxfb-xxxb-4xxx-9339-2d58xxx60ae6>"

   Output

   {"id":"f3d59d0a8fce45c7bdf3311bc51c4606292def6195674cf393bda793892f23cb"
   "uri":"kylo:kylo:vault:keys:key_name-v0"
   "account":"kylo:kylo:admin:accounts:kylo"
   "application":"ncryptify:gemalto:admin:apps:kylo"
   "devAccount":"ncryptify:gemalto:admin:accounts:gemalto"
   "createdAt":"2025-03-12T10:01:03.945017Z","name":"key_name"
   "updatedAt":"2025-03-12T10:01:03.945017Z"
   "activationDate":"2025-03-12T10:01:03.941793Z","state":"Active"
   "usage":"blob","usageMask":12,"meta":{"ownerId":"local
   a0a89746-5db8-47d3-a64f-149b89d552a5"},"objectType":"Symmetric Key"
   "aliases":[{"alias":"key_name","type":"string","index":0}]
   "sha1Fingerprint":"5d1b81ce34778509"
   "sha256Fingerprint":"8b5c455ea3a5689409ef50a0b762d94ed64c8e331116bec6be042
   12bc302c9e","defaultIV":"a4aa6956fe05512b63841f51be28b4ae","version":0
   "algorithm":"AES","size":256,"unexportable":false,"undeletable":false
   "neverExported":true,"neverExportable":false,"emptyMaterial":false
   "uuid":"94eab205-95c6-46f3-a2a1-c620ad6bc052"
   "muid":"94eab205-95c6-46f3-a2a1-c620ad6bc052b7a73ffc-c494-4f89-b994-404b00
   e6897"}

   Note

   Note down the key id (first line of output), as you will need it later.

Alternatively, you can create a key manually using the Thales CipherTrust Manager portal.

Integrating with TDE for encryption and decryption

Next, export the encryption and decryption commands as environment variables for initdb to pick up when creating a TDE-enabled database server.

1. Provide an initialization vector. This can be the Thales default IV or a custom IV:

   → WrapCopy

   export SERVER_IV='rPC3svypJzKoNaw6w7iVqw=='

2. Set the wrapping and unwrapping commands that will perform encryption and decryption. To set them correctly, you need:

   • The key_name you assigned to the key during creation.

   • The AES key id, which you can find in the output of the key creation command or look up in the Thales CipherTrust Manager portal.

   • The path to the edb_tde_crypto.py script installed by the packages. In RPM-based systems, the default location is /usr/edb/tde/rest/client/edb_tde_crypto.py, and in Debian, /usr/lib/edb/tde/rest/client/edb_tde_crypto.py.

   Replace these values in the example:

   → WrapCopy

   export PGDATAKEYWRAPCMD='python3 /usr/edb/tde/rest/client/edb_tde_crypto.py encrypt <key_name> | jq -r '.ciphertext' > "%p"'
   export PGDATAKEYUNWRAPCMD='python3 /usr/edb/tde/rest/client/edb_tde_crypto.py decrypt %p <id> | jq -r '.plaintext' | base64 -d'

3. You can now initialize a TDE-enabled database cluster with initdb --data-encryption. TDE will fall back on the exported PGDATAKEYWRAPCMD and PGDATAKEYUNWRAPCMD commands for the wrapping and unwrapping of data encryption keys.