SSL Certificates

This guide addresses common SSL certificate issues encountered when connecting TDK to databases.

Self-Signed Certificates and Certificate Authority (CA)

If you are using a self-signed certificate or an organization-wide Certificate Authority (CA), you may encounter SSL handshake errors when connecting to the database. To resolve this issue, you need to import the certificate to a Java truststore used by TDK.

SQLServer does not encourage self-signed certificates. To avoid SSL errors, you can try to add trustServerCertificate=true to the JDBC url (i.e. jdbc:sqlserver://<host>:<port>/<database>[;option=key];trustServerCertificate=true). This will allow TDK to trust the self-signed certificate keeping transport encryption enabled, potentially lowering security.

  1. Get a truststore file. In case you have a certificate in PEM format, you can convert it to a PKCS12 formatted file using the following command (you may need to install JDK):

keytool -import \
  -alias database \
  -file <path to your certificate.pem> \
  -keystore truststore.p12 \
  -storepass <truststore password> \
  -storetype PKCS12 \
  -noprompt

  1. Create a ConfigMap in Kubernetes or use a volume mount in Docker to mount the truststore file to the backend and agent containers.

  2. Add the following environment variable to the backend and agent containers to override the default truststore: JAVA_TOOL_OPTIONS: -Djavax.net.ssl.trustStore=<path to the truststore.p12 file> -Djavax.net.ssl.trustStorePassword=<truststore password> -Djavax.net.ssl.trustStoreType=PKCS12

Obsolete TLS or Signing Algorithm Version

TDK follows Java Cryptographic Architecture (JCA) standard. In rare cases, there might be a mismatch between the TLS version or signing algorithm used by the database and the one supported by JCA. In such cases, you may need to update the database configuration to support a more recent version of TLS or a different signing algorithm.

Alternatively, you can exclude your algorithm from the JCA configuration.

The instruction below is may expose your system to security vulnerabilities. Proceed with caution and only if you are sure that the algorithm you are excluding is already used in your environment.

  1. Create a file java.security with the following content:

jdk.tls.disabledAlgorithms=<list of algorithms to disable>
jdk.certpath.disabledAlgorithms=<list of algorithms to disable>

You can form the list by checking the output of the following command:

docker run --entrypoint java synthesizedio/synthesized-agent:latest -XshowSettings:security -version

Look for the jdk.tls.disabledAlgorithms and jdk.certpath.disabledAlgorithms entries in the output. Remove any algorithms you want to enable from the list before copying them into your file.

  1. Save the changes and mount the modified java.security file both to backend and agent containers. This can be done by creating a ConfigMap in Kubernetes or using a volume mount in Docker. Add the following environment variable to the backend and agent containers to override standard JCA configuration properties: JAVA_TOOL_OPTIONS: -Djava.security.properties=<path to the modified java.security file>