TLS 1.2 Support | IBM z/OS Mainframe Support| CLIv2 - TLS 1.2 Support - Call-Level Interface Version 2

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

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
Lake
VMware
Product
Call-Level Interface Version 2
Release Number
20.00
Published
January 2024
Language
English (United States)
Last Update
2024-05-14
dita:mapPath
bmn1691484839905.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
fvz1470444150352
Product Category
Teradata Tools and Utilities

MF-GTW CLIv2 supports TLS 1.2 using IBM’s System SSL library.

Configuration Variables

In order to use the TLS 1.2 feature, specify one or more of the following variables to CLI:
  • SSLMODE
  • SYSSSL_KEYRING_FILE
  • SYSSSL_KEYRING_STASH
  • SYSSSL_KEYRING_PW

These configuration variables can be specified as environment variables or through CLI’s clispb.dat configuration. This is described here:

SSLMODE={disable | allow | prefer | require | verify-ca | verify-full}

disable: unencrypted connection using non-TLS port.

allow: attempt unencrypted connection using non-TLS port first, then try encrypted connection using TLS port.

prefer: attempt encrypted connection using TLS port first, then try unencrypted connection using non-TLS port.

require/verify-ca: encrypted connection using TLS port. Verify the certificate chain.

verify-full: similar to verify-ca, but additionally performs host name verification.

For more information about each SSLMODE, see How to Secure Connections using TLS.

SSLMODE=require and SSLMODE=verify-ca have no difference because System SSL verifies the certificate chain by default.
The following environment variables are used for specifying key database file with password:
  • SYSSSL_KEYRING_FILE: filename of the key database file.
  • SYSSSL_KEYRING_STASH: name of the key database password stash file
  • SYSSSL_KEYRING_PW: password for the key database file
The mainframe client can access stored certificates via the following certificate store types:
  • SAF key Ring
  • Key database file
  • PKCS#11 token
The following configuration variables are used to specify the details of the mainframe client’s certificate store:
  • SYSSSL_KEYRING_FILE: filename of the key database file.
  • SYSSSL_KEYRING_STASH: name of the key database password stash file
  • SYSSSL_KEYRING_PW: password for the key database file
You can specify one of the following two ways:
  • SYSSSL_KEYRING_FILE and SYSSSL_KEYRING_STASH
  • SYSSSL_KEYRING_FILE and SYSSSL_KEYRING_PW

However, SYSSSL_KEYRING_STASH is recommended for security purpose.

When using a SAF key ring or PKCS#11 token, specifying SYSSSL_KEYRING_FILE is sufficient and neither SYSSSL_KEYRING_STASH nor SYSSSL_KEYRING_PW are required.

A SAF key ring can be specified through one of the following mechanisms:
  • For a self-signed certificate added to system’s SITE key ring
    • SYSSSL_KEYRING_FILE=*SITE*/*
  • For a signed certificate with certificate authority chain added to system’s CERTAUTH key ring
    • SYSSSL_KEYRING_FILE=*AUTH*/*
  • For certificate(s) added to the user’s KEY ring (substitute accordingly)
    • SYSSSL_KEYRING_FILE=<keyring_user>/<keyring_name>
A PKCS#11 token can be specified through the following mechanism (substitute accordingly):
  • SYSSSL_KEYRING_FILE=*TOKEN*/<tokenname>
Key database file contains the root CA certificate to validate the server certificate which is installed on the Teradata database server.

In general, a bundle certificate (server certificate + intermediate CA certificate + root CA certificate) is installed in the server as follows: /opt/teradata/tdat/tgtw/site/tls/certs/gtwcert.pem

-----BEGIN CERTIFICATE-----
<server certificate>
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
<intermediate CA certificate>
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
<root CA certificate>
-----END CERTIFICATE-----

Specifying TLS Configuration Details as Environment Variables

These environment variables can be specified in either JCL or clispb.dat. If an environment variable is specified in both JCL and clispb.dat, the value from the JCL overrides the value from the clispb.dat.

Example in JCL:

//ENVFILE DD *
SSLMODE=verify-full
SYSSSL_KEYRING_FILE=/home/myuserid/sample.kdb
SYSSSL_KEYRING_STASH=/home/myuserid/sample.sth
/*
//CEEOPTS DD *
ENVAR("_CEE_ENVFILE_S=DD:ENVFILE")
/*

Example in clispb.dat:

SSLMODE=verify-full
SYSSSL_KEYRING_FILE=/home/myuserid/sample.kdb
SYSSSL_KEYRING_STASH=/home/myuserid/sample.sth