TLS for all Exasol drivers

Details

Detail name Value
Changelog Number 6507
Type New Feature
Status Resolved
Fix Versions Exasol 7.1.0
Resolution Date 2021-08-03

Overview

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.
https://docs.exasol.com/7.1/administration/on-premise/access_management/tls_certificate.htm

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
SSLCertificate=SSL_VERIFY_SERVER		 EXAHOST=exadb1.example.com EXAHOST=exadb1.example.com/<fingerprint>:8563 EXAHOST=exadb1.example.com
SSLCertificate=SSL_VERIFY_NONE
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.

Exceptions

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.

Exceptions

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
72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30

Connection string format

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

Exaplus
# 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 10.0.0.1..2/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30:8563
JDBC

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

jdbc:exa:exadb1.example.com/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30:8563
ODBC

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

[710tls]
Driver=/path/EXASolution_ODBC-7.1/lib/linux/x86_64/libexaodbc-uo2214lv2.so
EXAHOST=exadb1.example.com/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30:8563
EXAUID=user
EXAPWD=password

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

ADO.NET

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

Server=exadb1.example.com/72975b4d331deeb44fa41fb858a5417e163151bbfb45376574706800a8dcce30;Port=8563

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
$> exaplus -c exadb1:8563 -jdbcparam validateservercertificate=0
JDBC

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

jdbc:exa:exadb1.example.com:8563;validateservercertificate=0
ODBC

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

[710tls]
Driver=/path/EXASolution_ODBC-7.1/lib/linux/x86_64/libexaodbc-uo2214lv2.so
EXAHOST=exadb1.example.com:8563
EXAUID=user
EXAPWD=password
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.

ADO.NET

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

Server=exadb1.example.com;Port=8563;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 LegacyEncryption=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

https://docs.exasol.com/connect_exasol/drivers/odbc.htm
https://docs.exasol.com/connect_exasol/drivers/jdbc.htm
https://docs.exasol.com/connect_exasol/drivers/ado_net.htm