Uploaded image for project: 'EXASOL Roadmap'
  1. EXASOL Roadmap
  2. EXASOL-2936

TLS for all Exasol drivers



    • Type: New Feature
    • Status: Resolved
    • Priority: Normal
    • Resolution: Fixed
    • Fix Version/s: Exasol 7.1.0
    • Component/s: None
    • Labels:



      Exasol 7.1 has introduced TLS as the default cryptographic protocol for all connections. Thus, all connections created using Exasol-provided 7.1 drivers will try to establish TLS connections to Exasol per default. Previously, only WebSocket connections supported TLS.

      As a part of the TLS handshake, the drivers require SSL/TLS certificate used by Exasol to be verified. This is the standard practice that increases the security of connections by preventing man-in-the-middle attacks, for example.

      Action Required

       If the certificate used by Exasol is not signed by a publicly recognized certificate authority (CA) or if the necessary CA certificate has not been provided to the client to use for verification, the connection will fail.

       If another certificate has not been uploaded using EXAoperation, a self-signed certificate is used by Exasol per default. Since this certificate is self-signed, TLS connections to Exasol will fail by default. If this self-signed certificate should nevertheless be used, the certificate verification method must be changed.

       A custom (i.e. non-default) certificate to be used by Exasol can be uploaded via EXAoperation. For more information on using a TLS certificate with Exasol, please see the following.

      Certificate Verification

      Since a single option for the verification of SSL/TLS certificates used by Exasol is not feasible for all environments, there are three possible methods to use for this.

      1. Full, TLS-standard verification (default)
      2. Fingerprint-based verification
      3. No verification

      The following table provides an overview of how to set the verification methods for each driver. The first two columns show how to explicitly set the default method, the second one is identical, but shorter by making use of the default.
      For further details, see below.

        Standard Verification (default - explicit) Standard Verification (default - implicit) Fingerprint-based Verification No Verification
      JDBC jdbc:exa:exadb1.example.com:8563;validateservercertificate=1 jdbc:exa:exadb1.example.com:8563 jdbc:exa:exadb1.example.com/<fingerprint>:8563 jdbc:exa:exadb1.example.com:8563;validateservercertificate=0
      ODBC EXAHOST=exadb1.example.com
      EXAHOST=exadb1.example.com EXAHOST=exadb1.example.com/<fingerprint>:8563 EXAHOST=exadb1.example.com
      ADO.NET Server=exadb1.example.com;Port=8563;SSLCertificate=VERIFYSERVER Server=exadb1.example.com;Port=8563 Server=exadb1.example.com/<fingerprint>;Port=8563 Server=exadb1.example.com;Port=8563;SSLCertificate=VERIFYNONE

      Standard Verification

      This is the standard certificate verification process used by default. The certificate is verified to be valid for the Exasol node (host or IP address check) from which it was received and that the certificate is properly signed by a recognized CA.

      If the certificate and the client's corresponding CA certificates are properly configured, then no additional configuration is necessary.

      This method provides the highest level of security.


      If creating a connection fails for any reason, an error message indicating the problem will be provided. Additionally, the fingerprint of the server's certificate will be provided in case the problem cannot be fixed, but the certificate should still be trusted using fingerprint-based verification.

      TLS connection to host (exadb1.example.com) failed: unable to get local issuer certificate. If you trust the server, connect to it using the fingerprint: 72975B4D331DEEB44FA41FB858A5417E163151BBFB45376574706800A8DCCE30.
      TLS connection to host (exadb1.example.com) failed: hostname mismatch. If you trust the server, connect to it using the fingerprint: 72975B4D331DEEB44FA41FB858A5417E163151BBFB45376574706800A8DCCE30.

      Fingerprint-based Verification

      If it is not possible or desired for the client to verify the SSL/TLS certificate using the standard verification process, an additional method using the certificate's fingerprint has been provided to check it. For example, if the certificate is self-signed, this method can still check that the certificate used by Exasol is the expected certificate even if the signatures cannot be verified.

      This method still provides some level of security, as opposed to simply disabling certificate verification entirely.

      To employ this method, the fingerprint (SHA-256 hash) of the certificate is provided in the client's connection string following the host and a forward slash. Using this, the client can compare this given hash to the computed hash of the certificate received during the TLS handshake with Exasol. If the hashes match, the connection is allowed. If they do not match, the connection is rejected because the client assumes it is communicating with a host which is not allowed.


      If creating a connection fails for any reason, an error message indicating the problem will be provided.

      Fingerprint did not match. The fingerprint provided: 72975B4D331DEEB44FA41FB858A5417E163151BBFB45376574706800A8DCCE30. Server's certificate fingerprint: 72975B4D331DEEB44FA41FB858A5417E163151BBFB45376574706800A8DCCE31.
      More than one fingerprint was provided.

      Certificate fingerprint

      The fingerprint of the certificate currently in use by Exasol can be viewed in EXAoperation.

      However, a certificate's fingerprint can also be generated manually using openssl. This could be useful as a manual check or, for example, if another certificate has been manually set using the Exasol parameter -tlsCertificatePath.

      $> openssl x509 -noout -fingerprint -sha256 -in certificate.pem 
      SHA256 Fingerprint=72:97:5B:4D:33:1D:EE:B4:4F:A4:1F:B8:58:A5:41:7E:16:31:51:BB:FB:45:37:65:74:70:68:00:A8:DC:CE:30

      To directly generate the fingerprint without colons, the following can be used as well.

      $> openssl x509 -in certificate.pem -outform der | sha256sum

      Connection string format

      The fingerprint can be provided following the host and a '/' character. A port can then be specified following the fingerprint.

      # single host
      $> exaplus -c exadb1/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30
      # single host with port
      $> exaplus -c exadb1/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30:8563
      # multiple hosts
      $> exaplus -c exadb1,exadb2/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30
      # multiple hosts with port
      $> exaplus -c exadb1,exadb2/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30:8563
      # multiple IP addresses with port
      $> exaplus -c

      To use the fingerprint-based method with JDBC, the fingerprint should be provided in the connection string as described above.


      To use the fingerprint-based method with ODBC, the fingerprint should be provided in the connection string as described above.


      For Windows "Connection string" should be changed accordingly in DSN.


      To use the fingerprint-based method with ADO.NET, the fingerprint should be provided in the connection string as described above.


      No Verification

      If it is not possible or desired to perform any verification of the certificate at all, then verification can be completely disabled. By disabling certificate verification, however, a man-in-the-middle attack is possible because it cannot be verified that the client actually connected to the specified server in the connection string. As such, this method is not recommended.

      This method provides the lowest level of security.

      $> exaplus -c exadb1:8563 -jdbcparam validateservercertificate=0

      To disable certificate verification with JDBC, the following parameter should be set in the connection string: validateservercertificate=0.


      To disable certificate verification with ODBC, the following parameter should be set in the odbc.ini file: SSLCertificate=SSL_VERIFY_NONE.


      For Windows the corresponding "key=value" pair should be added to the "Additional connection string parameters" field in the "Advanced" tab of DSN.


      To disable certificate verification with ADO.NET, the following parameter should be set in the connection string: SSLCertificate=VERIFYNONE.


      Supported Versions

      Exasol driver-initiated connections (i.e. non-WebSocket connections) are supported in Exasol and all Exasol drivers as of version 7.1.0. Additionally, support for Exasol driver-initiated connections has been added to Exasol versions 6.2.15+ and 7.0.10+.

      The compatibility matrix below provides an overview of TLS support.

        6.2 Driver encryption (ODBC, JDBC, ADO.NET) 7.0 Driver encryption (ODBC, JDBC, ADO.NET) 7.1.0+ Driver encryption (ODBC, JDBC, ADO.NET) WebSocket encryption
      Database Version Exasol 6.2.x ChaCha20 ChaCha20 ChaCha20
       TLS Support (6.2.15+)
       TLS Support
      Database Version Exasol 7.0.x ChaCha20 ChaCha20 ChaCha20
       TLS Support (7.0.10+)
       TLS Support
      Database Version Exasol 7.1.x ChaCha20 ChaCha20  TLS Support  TLS Support

       If a 7.1.0+ driver is used to connect to an Exasol version that does not support TLS, then the driver will automatically establish a connection using the legacy ChaCha20 encryption method. Since the driver doesn't know the database version before establishing the connection, the driver will always create a TLS connection first and then switch to the legacy ChaCha20 encryption protocol, if necessary, after receiving the version information from the Exasol. The TLS connection will be closed before opening the ChaCha20 connection.

       Because a TLS connection is always created first, either the certificate must be valid, the check must be deactivated, or the fingerprint must be used. To avoid this and the additional TLS login, it is recommended to set the legacy encryption connection string parameter for older databases.

       Also for the latest versions where TLS is the preferred method for encryption, ChaCha can still be used if necessary.

      Legacy Encryption

      If for some reason the use of ChaCha20 is preferred to TLS, it can be manually enabled using the following settings.

        Legacy Encryption Parameter
      JDBC jdbc:exa:exadb1.example.com:8563;legacyencryption=1
      ODBC UseLegacyEncryption=Y
      ADO.NET Server=exadb1.example.com;Port=8563;LegacyEncryption=yes

      SDK - Call Level Interface

      To connect to the server you have to use EXAServerConnect() like before. In 7.1.0 and newer SSL will the default encryption in the client-server communication.
      You can use EXASetConnectAttr() to change the connection behavior by means of the following attributes:

      Keys Description
      EXA_SOCKET_ENCRYPTION (string) Can be "Y" or "N", default "Y"
      EXA_SSL_CERTIFICATE (string) A certificate file name or "SSL_VERIFY_NONE" or "SSL_VERIFY_SERVER". Default: "SSL_VERIFY_SERVER"
      EXA_FINGERPRINT(string) Fingerprint used for SSL server verification, default NULL
      EXA_SSL_CA_PATH (string) Path where to search for certificates, default NULL
      EXA_USE_LEGACY_ENCRYPTION (string) Can be "Y" or "N", default "N"

      The fingerprint can also be added to the host name used to connect, like in Exasol ODBC: "<my_host_nane>/<fingerprint_string>" as parameter to EXAServerConnect().

      If nothing else specified, the driver will use the certificate from the system store, like ODBC does.

      IMPORT / EXPORT from EXA also uses SDK and, therefore, starting from DB version 7.1.0 it requires certificate / fingerprint / legacy encryption.

      Driver Documentation





            CaptainEXA Captain EXASOL
            CaptainEXA Captain EXASOL
            0 Vote for this issue
            2 Start watching this issue