TLS WebSocket| ODBC Driver for Teradata - TLS WebSocket - ODBC Driver for Teradata

TLS WebSocket is a new feature introduced in ODBC Driver for Teradata 17.10 to allow the driver to communicate with Analytics 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. In most circumstances, the driver prioritizes connecting with HTTPS port. If failed, then driver would fall back to try connecting with TDMST port.
  When Teradata Gateway TLS setting is set to “enable”with TLS certificate being correctly setup, ODBC Driver for Teradata only attempts connection using HTTPS port. If the connection fails, then a corresponding error message is returned.

  For more information, see Deterministic Behavior of Prefer/Allow SSLMode.

• Allow - In most circumstances, the driver takes priority connecting with TDMST port. If that connection fails, then the driver falls back to try connecting with HTTPS port.
  When Teradata Gateway TLS setting is set to “enable” with TLS certificate being correctly set up, ODBC Driver for Teradata only attempts connection using TDMST port. If the connection fails, then a corresponding error message is returned.

  For more information, see Deterministic Behavior of Prefer/Allow SSLMode.

• 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” or “VerifyFull”, you can either specify the TLS certificate location with driver’s parameter SSLCA or SSLCAPath, or specify it with the operating environment default System Trust Store.

Following are examples of installing the TLS certificate using OS’s System Trust Store on different platforms.

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 certificate 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.Check the documentation for your distribution. following are some sample instructions:

Installing the Certificate (CentOS 6 or later)

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 20.00)

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

Client Confidentiality Type

ODBC Driver for Teradata supports new Client Confidentiality Types that correspond to the different SSL modes available and fallback scenarios when communicating with Analytics Database.