Skip to main content

How To Guide Setting up an Encrypted Connection between Estate Manager and Database

Introduction​

This guide provides information on setting up an encrypted connection between Estate Manager Processing (EMP) service and the database. This has been tested against MySQL and MariaDB databases.

Overview​

This guide will cover the following:

  • Prerequisites - Describes the conditions and criteria that should be met before following the document.

  • Keystore creation - Describes the steps to create a Java keystore.

  • Truststore creation - Describes the steps to create a Java truststore.

  • Importing the certificate - Describes the steps to import the database certificate.

  • Application changes - Describes the changes in the EMP service to use the encrypted connection.

Prerequisites​

  • Databases should be configured to use encrypted connections.

  • Users should have sufficient knowledge in asymmetric encryption.

  • Users should have sufficient knowledge in Java keystore, truststore and keytool utility.

  • Users should have sufficient knowledge in Linux file systems and Docker container volumes.

  • Users should have sufficient knowledge in deploying Enactor applications.

Note: This guide will not cover configuring databases to use encrypted connections.

Keystore Creation​

Tomcat's keystore will be used to initiate the SSL handshake by default. This will lead to an unknown Certificate Authority (CA) exception since tomcat's keystore is self-signed. To overcome this issue, a custom empty keystore needs to be passed.

Create a keystore using the following command:

keytool -genkey -alias keystore -validity 365 -keyalg RSA -keystore keystore.jks

Answer the keytool DN prompts.

Provide a strong keystore password and make a note of it. This password will be needed later.

The keystore file will be written in the current directory.

Empty the keystore using the following command:

Note: Ther keystore will not be needed to be emptied if the keystore can be verified through a known CA.

keytool -delete -alias keystore -keystore keystore.jks

Truststore Creation​

Tomcat's truststore can be used to import the database certificate. This section can be skipped if Tomcat's truststore is used. Considering uniformity, a custom truststore will be created.

Note:
Tomcat's truststore file location - /enactor/app/home/trust/.truststore

Tomcat's truststore password - changeit

Create a truststore using the following command:

keytool -genkey -alias truststore -validity 365 -keyalg RSA -keystore truststore.jks

Answer the keytool DN prompts.

Provide a strong truststore password and make a note of it. This password will be needed later.

Truststore file will be written in the current directory.

Importing the Database Certificate​

Obtain the database server certificate that needs to be imported to the truststore.

Import the database server certificate to the truststore using the following command (db.pem is the certificate name):

keytool -import -alias db-root -keystore truststore.jks -file db.pem

Verifying the Certificate Import​

Confirm that the certificate is imported correctly using the following command:

keytool -list -v -keystore truststore.jks

Application Configuration Changes​

Access to Keystore and Truststore Files​

Keystore and truststore files should be accessible by the EMP container. Note that the Enactor application home directory (/enactor/app/home) is mounted to the underlying host machine's storage through Docker volumes. Place both keystore and truststore files inside the host machine's corresponding directory.

File permission for both keystore and truststore files needs to be modified. User tomcat_admin(user id - 1100) should have access to these files.

Execute below commands:

chown 1100:1100 keystore.jks
chown 1100:1100 truststore.jks

Database Connection URL in EMP​

Database URL needs to be modified to setup encrypted connection between the application and the database.

Database URL is configured in the common-em.env file with the attribute ENACTOR_DB_JDBC_URL.

Following is an example of how this is modified:

ENACTOR_DB_JDBC_URL=jdbc:mysql:\/\/<db-host-name>:<dbport>\/<databasename>?defaultFetchSize=1000\&amp;useCursorFetch=true\&amp;useLegacyDatetimeCode=false\&amp;serverTimezone=Europe%2FLondon\&amp;useUnicode=true\&amp;characterEncoding=UTF8\&amp;useSSL=true\&amp;requireSSL=true\&amp;verifyServerCertificate=true\&amp;clientCertificateKeyStoreUrl=file:/enactor/app/home/keystore.jks\&amp;clientCertificateKeyStorePassword=<keystorepassword>\&amp;clientCertificateKeyStoreType=JKS\&amp;trustCertificateKeyStoreUrl=file:/enactor/app/home/truststore.jks\&amp;trustCertificateKeyStorePassword=<truststorepassword>\&amp;trustCertificateKeyStoreType=JKS

The following additional parameters are passed in the database URL:

  • useSSL

  • requireSSL

  • verifyServerCertificate

  • clientCertificateKeyStoreUrl

  • clientCertificateKeyStorePassword

  • clientCertificateKeyStoreType

  • trustCertificateKeyStoreUrl

  • trustCertificateKeyStorePassword

  • trustCertificateKeyStoreType

Note: Make sure to modify all the database URL references in other components like Customer Manager, Order Manager if they are deployed in the environment.