17.20 - 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 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.
  When Teradata Gateway TLS settingis 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, refer to Deterministic Behavior of Prefer/Allow SSLMode.

• Allow - 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 settingis set to “enable” with TLS certificate being correctly setup, ODBC driver for Teradata only attempts connection using TDMST port. If the connection fails, then a corresponding error message is returned.

  For more information, refer to 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” with the operating environment default, add the certificate 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

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.