17.10 - About TLS in Client Applications - Call-Level Interface Version 2

Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems

Product
Call-Level Interface Version 2
Release Number
17.10
Release Date
October 2021
Content Type
Programming Reference
Publication ID
B035-2418-061K
Language
English (United States)

TLS can be enabled in client applications by setting the SSLMODE connection parameter. The following table lists the valid values for SSLMODE and describes their function:

sslmode Values Description
disable D Establish an unencrypted connection using the non-TLS port. If data_encryption=Y is specified in clispb.dat or DBCAREA, the TeraGSS encryption mechanism is used.
allow A Establish an unencrypted connection using the non-TLS port. If data_encryption=Y is specified in clispb.dat or DBCAREA, the TeraGSS encryption mechanism is used. If the server is configured to accept connections on the non-TLS port but the attempt to connect to the non-TLS port fails (for example, timeout), the connection attempt will fail and return an error.

This is the default value for CLI.

Encrypted (TLS) connection is used in the fallback scenarios when the administrator disabled the non-TLS port and enabled the TLS port.

prefer P Establish an encrypted (TLS) connection if the server supports TLS and the TLS port is enabled. If the server is configured to accept connections on the TLS port but the attempt to connect to the TLS port fails (for example, timeout), the connection attempt will fail and return an error.

Unencrypted connection to the non-TLS port is used in the following fallback scenarios:

  • Administrator disabled the TLS port
  • The server does not support TLS.
require R Establish an encrypted (TLS) connection if the server supports TLS connections. The connection attempt fails if TLS connection cannot be established. Do not fallback to the non-TLS port.
verify-ca C Similar to require, but additionally verify the server Certificate Authority (CA) certificate against the configured trusted CA certificates. The connection attempt fails if no valid matching CA certificates are found.
verify-full F Similar to verify-ca, but additionally perform host name identity verification by checking the host name the client uses for connecting to the server against the identity in the certificate that the server sends to the client. The client checks whether the host name that it uses for connecting matches either the Subject Alternative Name value or the Common Name value in the server certificate.

The connection fails if there is a mismatch. For encrypted connections, this option helps prevent man-in-the-middle attacks.

In verify-full mode, the host name is matched against the certificate's Subject Alternative Name attribute(s), or against the Common Name attribute if no Subject Alternative Name of type "DNS Name" is present. If the certificate's name attribute starts with an asterisk (*), the asterisk will be treated as a wildcard, which will match all characters except a dot (.). This means the certificate will not match subdomains. If the connection is made using an IP address instead of a host name, the IP address will be matched (without doing any DNS lookups).

The SSLMODE parameter can be set in the following locations:

clispb.dat (For more information, refer to System Parameter Block (SPB) Processing.)

Add the following line to clispb.dat:

sslmode=disable | allow | prefer | require | verify-ca | verify-full

Environment variable

Set the following environment variable prior to running the client application:

Non-Windows:

$ export SSLMODE=disable | allow | prefer | require | verify-ca | verify-full

Windows:

C:\> set SSLMODE=disable | allow | prefer | require | verify-ca | verify-full

DBCAREA sslmode

Set the following parameter in the DBCAREA structure:

dbcarea.sslmode = ‘D’ | ‘A’ | ‘P’ | ‘R’ | ‘C’ | ‘F’

DBCAREA Connection string

The connect_ptr parameter in the DBCAREA structure can be set to a string containing the sslmode attribute:

dbcarea.connect_ptr = “sslmode=disable | allow | prefer | require | verify-ca | verify-full”

Also remember to set the dbcarea.connect_len parameter to the length of the string assigned to dbcarea.connect_ptr.

The order of precedence for the above methods is as follows:

  • clispb.dat
  • Environment variable
  • dbcarea.sslmode
  • dbcarea.connect_ptr

DBCAREA o_sslmode

Once a successful TLS connection is made, the actual SSLMODE used for the connection will return in the DBCAREA parameter o_sslmode. This parameter is set regardless of which method was used to set SSLMODE. For SSLMODE values allow (‘A’) and prefer (‘P’), o_sslmode will be set to ‘D’ if a non-TLS connection was used, or ‘R’ if a TLS connection was used. For all other SSLMODE values, o_sslmode will contain the specified SSLMODE value (for example, D, R, C, F).