TLS WebSocket Feature - ODBC Driver for Teradata

The TLS WebSocket feature is a new feature introduced in ODBC Driver for Teradata 17.10 to allow the driver to communicate with Teradata database via TLS connection instead of Teradata-proprietary encryption mechanism. This feature also provides protection from man-in-the-middle (MITM) attacks.

Supported Platforms

Related Driver Parameters

• SSLMode - The TLS mode the driver operates in.
• SSLProtocol - The minimum version of TLS that the driver allows for connection.Currently only TLSv1.2 is supported.
• SSLCA - The full path and name of a .pem file containing one or more certificates for trusted Root and Intermediate CAs. If SSLMode is not set to Verify-CA or Verify-Full, then SSLCA or SSLCAPath will be ignored.
• SSLCAPath - The full path of the directory containing the root certificates for trusted CAs. The default value is default of the operating environment. If SSLMode is not set to Verify-CA or Verify-Full, then SSLCA or SSLCAPath will be ignored.
• HTTPS_PORT - The port number used for TLS connection. Default is set to 443.
• TdmstPortNumber - The port number used for non-TLS connection. Default is set to 1025.

Supported SSLMode

• Prefer - This is the driver default. Driver prioritizes connecting with HTTPS port. If failed, then driver would fall back to try connecting with TDMST port.
• Allow - Driver takes priority connecting with TDMST port. If that connection fails, then the driver falls back to try connecting with HTTPS port.
• Disable - Driver only connects on TDMST port.
• Require - Driver only connects on the HTTPS port.
• Verify-CA - Same as “Require” mode with additional server CA verification.
• Verify-Full - Same as “Verify-CA” mode with additional host name identity validation.

Using OS System Certificate Trust Store

To use SSLMode “VerifyCA” & “VerifyFull” with default of the operating environment, add the gtwcert.pem to the OS’s System Trust Store.

Installing the Certificate (For Windows)

1. Press Windows Key+R (Run) and type "mmc".
2. Select File > Add/Remove Snap-in.
3. Select Certificates and click Add.
4. Choose Computer account and click Next.
5. Next
6. Choose Local computer and click Finish.
7. Click OK.
8. Expand and click Certificates (Local Computer)\Trusted Root Certification Authorities\Certificates in the left tree view.
9. In the middle you may find the list of SSL/TLS certificates currently trusted by the OS.
10. Right-click Certificates under Trusted Root Certification Authorities, All Tasks >Import.
11. Click Next, and browse the gtwcert.pem file obtained from the TLS database.
12. Keep clicking Next until Finish.
13. The import was successful dialog box appears, and it ensures that the cetitificate is successfully imported.

Uninstalling the Certificate

1. Right-click the highlighted Certificate in the Microsoft Management Console.
2. Choose Delete.
3. Click Yes.

Installing certificates on Linux varies depending on the particular version of Linux. Please refer to the documentation for your distribution. Below are some sample instructions:

Installing the Certificate (CentOS 6 or above)

1. Run sudo cp /path/to/gtwcert.pem /etc/pki/ca-trust/source/anchors/.
2. Run sudo update-ca-trust

Uninstalling the Certificate

1. Run sudo rm /etc/pki/ca-trust/source/anchors/gtwcert.pem.
2. Run sudo update-ca-trust.

Installing the Certificate (SLES 11)

1. Run sudo cp /path/to/gtwcert.pem /etc/ssl/certs.
2. Run sudo chmod 644 gtwcert.pem to set permission for certificate.
3. Run sudo c_rehash /etc/ssl/certs.

Uninstalling the Certificate

1. Run sudo rm /etc/ssl/certs/gtwcert.pem.
2. Run sudo c_rehash /etc/ssl/certs.

Installing the Certificate (SLES 12 or above)

1. Run sudo cp /path/to/gtwcert.pem /etc/pki/trust/anchors.
2. Run sudo update-ca-certificates.

Uninstalling the Certificate

1. Run sudo rm /etc/pki/trust/anchors/gtwcert.pem.
2. Run sudo update-ca-certificates.

Installing the Certificate (Red Hat 7.7)

1. Run sudo cp /path/to/gtwcert.pem /etc/pki/ca-trust/source/anchors/.
2. Run sudo update-ca-trust.

Uninstalling the Certificate

1. Run sudo rm /etc/pki/ca-trust/source/anchors/gtwcert.pem.
2. Run sudo update-ca-trust

Installing the Certificate (Ubuntu 16, 18)

1. Run sudo cp /path/to/gtwcert.pem /usr/local/share/ca-certificates/gtwcert.crt.
   Certificate MUST have “.crt” extension. Simply rename “.pem” to “.crt”.
2. Run sudo update-ca-certificates.
   Ensure you get "1 added, 0 removed" output message.

Uninstalling the Certificate

1. Run sudo rm /usr/local/share/ca-certificates/gtwcert.crt.
2. Run sudo update-ca-certificates.

Sample Instructions for AIX and Solaris Platforms

• For AIX, refer to the article 'IBM AIX: Import CA certificate' in https://www.ibm.com/support/pages/ibm-aix-import-ca-certificate
• For Solaris, refer to the article 'Adding CA Certificates to the Oracle Solaris CA Keystore' in https://docs.oracle.com/cd/E37838_01/html/E61024/kmf-addcacert.html

Deterministic Behavior of Prefer/Allow SSLMode

ODBC driver supports the deterministic behavior from Teradata database for Pref er/Allow SSL mode. This enhances the utilization of port selection used for database connection.During the process of connecting to a Teradata database, ODBC driver receives information of which port (for example, HTTPS or TDMST) the database actively listens to. Based on this information, there are 3 possible scenarios of information received from the Teradata database:

1. TDMST port enabled and HTTPS port disabled ODBC driver, SSLMode=Allow or SSLMode=Prefer

   ODBC driver consistently connects to the TDMST port or returns an error.

2. HTTPS port enabled & TDMST port disabled ODBC driver, SSLMode=Allow or SSLMode=Prefer

   ODBC driver consistently connects to the HTTPS port or returns an error.

3. Both TDMST and HTTPS ports enabled
   • ODBC driver, SSLMode=Allow

     ODBC driver connects to the TDMST port or returns an error indicating that the TDMST port is enabled, but the driver fails to connect to it.

   • ODBC driver, SSLMode=Prefer

     ODBC driver connects to the HTTPS port or returns an error indicating that the HTTPS port is enabled, but the driver fails to connect to it.

The deterministic behavior of Prefer/Allow SSL mode is dependent on the TLS setting of Teradata Gateway. Currently there are four modes, namely disable, enable, require and nolegacy, that the Teradata Gateway can be set to. You can run the following commands to check or change the setting:

• tdatcmd
• gtwcontrol -h
• gtwcontrol --TLS [disable|enable|require|nolegacy][,trace=yes|no|all]

Client Confidentiality Type

ODBC driver supports new Client Confidentiality Types that correspond to the different SSL modes available and fallback scenarios when communicating with Teradata database.