TLS encryption - connect_cdc_sqdata - 4.1

Connect CDC (SQData) Secure communications components

Product type
Software
Portfolio
Integrate
Product family
Connect
Product
Connect > Connect CDC (SQData)
Version
4.1
Language
English
Product name
Connect CDC (SQData)
Title
Connect CDC (SQData) Secure communications components
Topic type
How Do I
Installation
Copyright
2024
First publish date
2000
ft:lastEdition
2024-02-07
ft:lastPublication
2024-02-07T13:29:14.268926

Transport Layer Security (TLS) is supported between all components on z/OS and between Connect CDC SQData clients on Linux and Change Data Capture components on z/OS, only.

z/OS TLS Capture and Apply Engines

Connect CDC SQData already operates transparently on z/OS under IBM's Application Transparent Transport Layer Security (AT-TLS) . Under AT-TLS no changes were required to the base code and only port numbers in the configuration need to be changed, as described below. For more information regarding AT-TLS see your z/OS Systems Programmer.

Once IBM's AT-TLS has been implemented on z/OS the following steps are all that is required by Daemon, Capture and Publisher components and on z/OS only, the SQDATA Apply Engine and SQDutil, to be in compliance with TLS:

  1. Request the new secure port to be used by the Daemon
  2. Request Certificates for MASTER, Daemon and APPLY Engine Tasks
  3. Stop all SQDATA tasks
  4. Update APPLY Engine source scripts with the new Daemon port. Note, port's are typically implemented using a Parser parameter so script changes may not be required.
  5. Update SQDUTIL JCL and/or SQDPARM lib member's, if any with the new Daemon port.
  6. Run Parse Jobs to update the Parsed Apply Engines in the applicable library referenced by Apply Engine Jobs.
  7. Update the Daemon tasks with new port
  8. If using the z/OS Master Controller, update the SQDPARM Lib members for the MASTER tasks with new Daemon port
  9. Start all the SQDATA tasks

Note, there are no changes to connection URL's for clients on z/OS.

Linux TLS Apply and Replicate Engines

Linux clients connecting to z/OS Daemons running under IBM's (AT-TLS) and servicing z/OS Change Data Captures now support the TLS handshake. TLS connections to Change Data Capture components running on AIX and Linux are not supported at this time.

The only external prerequisite to enabling TLS on Linux is the GnuTLS secure communications library which implements TLS, DTLS and SSL protocols and technologies including the C language API used by Connect CDC SQData on Linux. On RPM-based Linux distributions, YUM (Yellowdog Updater Modified) can be used to install GnuTLS. For more information regarding YUM or other Package Managers see your Linux Systems Administrator.

Linux clients making TLS connections to z/OS, will by default perform the "typical TLS handshake" where the client uses the server's certificate for authentication and then proceeds with the rest of the handshake process. Specific changes to connection parameters are described below.

The following steps are all that are required on the client side to implement TLS on Linux for the "typical" client side handshake performed by an Engine:

  1. Request the new Port number that was assigned to the z/OS Daemon.
  2. Stop all running Connect CDC SQData Linux Engines, the local Daemon need not be stopped.
  3. Update Engine source DATASTORE URL to use the "cdcs:// URL syntax type to specify that a secure TLS connection is requested (changed from "cdc://" to "cdcs://").
  4. Update Engine source DATASTORE URL to use the TLS z/OS Daemon port. Note, the port number is typically implemented using a Parser parameter so script changes may not be required.
  5. Parse the Apply Jobs to create a new <engine>.prc file in the applicable directory.
  6. Start the Connect CDC SQData Linux clients.

Notes:

  • If the Linux default package manager was used to install the GnuTLS library, we would expect it to be placed in either /lib64 or /usr/lib64. Two softlinks should have been created and libgnutls.so included in the "default library path" for example:

    lrwxrwxrwx 1 root root 20 Jul 8 2020 libgnutls.so -> libgnutls.so.28

    lrwxrwxrwx 1 root root 20 Sep 11 2019 libgnutls.so.28 -> libgnutls.so.28.43.3

    If it is not in the default path we will be unable to locate the library. A special environmental variable can be used but Precisely only recommends doing so in a test environment:

    SQDATA_GNUTLS_LIBRARY=<path_to_softlink/>libgnutls.so

  • If the SQDmon utility is used to connect to a remote z/OS Daemon running under IBM's (AT-TLS) , for example to request an "inventory" or "display" the status of a publisher a new --tls parameter must be specified:

    Syntax:

    sqdmon inventory //<host_name> [-s port_num | --service=port_num] [--identity=<path_to/nacl_id>] [--tls]

  • If the SQDutil is used to connect to a remote Publisher running under IBM's (AT-TLS) , to copy/move CDC records to a file, the "cdcs://" URL syntax type must be specified:

    Syntax:

    sqdutil copy | move cdcs://<host_name>:<port_num>/<agent_name> <target_url> | DD:<dd_name>

  • Although uncommon, if yours is a Mutual Auth aka Mutual Authentication implementation, which also includes authentication of the client by the server, then two environmental variables must be used to identify the client certificate and key. The server will then use the client side certificate to authenticate the client before proceeding with the rest of the handshake.

    SQDATA_TLS_CERT=</directory/file_name>

    SQDATA_TLS_KEY=</directory/file_name>

    The Linux client will by default use the system installed Certificate Authority (CA). If a local CA file is used, it must be specified using a third Environmental variable:

    SQDATA_TLS_CA=</directory/file_name>

Sample z/OS AT_TLS configuration:

While some customers have well established AT-TLS configurations, others are doing it for the first time. The following sample AT-TLS Policy Agent Configuration is known to work with the Connect CDC SQData SQDAEMON, Captures and Publishers on z/OS.
## AT-TLS Policy Agent Configuration file for:
##  
##    Stack: TCPIP
##
## Created by the IBM Configuration Assistant for z/OS Communications Server
## Version 1 Release 13
##
TTLSRule                          SQServer
{
 LocalAddr                       ALL
 RemoteAddr                      ALL
 LocalPortRangeRef               portR1
 RemotePortRangeRef              portR2
 Direction                       Inbound
 Priority                        255
 TTLSGroupActionRef              gAct1~Sqdata
 TTLSEnvironmentActionRef        EnvAct_Server
 TTLSConnectionActionRef         ConAct_Server
}

TTLSRule                          SQClient
{
 LocalAddr                       ALL
 RemoteAddr                      ALL
 LocalPortRangeRef               portR2
 RemotePortRangeRef              portR1
 Direction                       Outbound
 Priority                        255
 TTLSGroupActionRef              gAct1~Sqdata
 TTLSEnvironmentActionRef        EnvAct_Client
 TTLSConnectionActionRef         ConAct_Client
}
TTLSGroupAction                   gAct1~Sqdata
{
 TTLSEnabled                     On
}
TTLSEnvironmentAction             EnvAct_Server
{
 HandshakeRole                   Server
 EnvironmentUserInstance         0
 TTLSKeyringParmsRef             keyR~ZOS2
}
TTLSEnvironmentAction             EnvAct_Client
{
 HandshakeRole                   Client
 EnvironmentUserInstance         0
 TTLSKeyringParmsRef             keyR~ZOS2
}
TTLSConnectionAction              ConAct_Server
{
 HandshakeRole                   Server
 TTLSCipherParmsRef              cipher1~Default_Ciphers
 TTLSConnectionAdvancedParmsRef  cAdv1~Sqdata
 CtraceClearText                 Off
 Trace                           2
}
TTLSConnectionAction              ConAct_Client
{
 HandshakeRole                   Client
 TTLSCipherParmsRef              cipher1~Default_Ciphers
 TTLSConnectionAdvancedParmsRef  cAdv1~Sqdata
 CtraceClearText                 Off
 Trace                           2
}
TTLSConnectionAdvancedParms       cAdv1~Sqdata
{
 SecondaryMap                    Off
}
TTLSKeyringParms                  keyR~ZOS2
{
 Keyring                         OMVSKERN/FTPSRING
}
TTLSCipherParms                   cipher1~Default_Ciphers
{
 V3CipherSuites                  TLS_RSA_WITH_AES_256_CBC_SHA
 V3CipherSuites                  TLS_DHE_RSA_WITH_AES_256_CBC_SHA
 V3CipherSuites                  TLS_DH_RSA_WITH_AES_256_CBC_SHA
 V3CipherSuites                  TLS_DHE_DSS_WITH_AES_256_CBC_SHA
 V3CipherSuites                  TLS_DH_DSS_WITH_AES_256_CBC_SHA
 V3CipherSuites                  TLS_RSA_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites                  TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites                  TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites                  TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites                  TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
 V3CipherSuites                  TLS_RSA_WITH_AES_128_CBC_SHA
 V3CipherSuites                  TLS_DHE_RSA_WITH_AES_128_CBC_SHA
 V3CipherSuites                  TLS_DH_RSA_WITH_AES_128_CBC_SHA
 V3CipherSuites                  TLS_DHE_DSS_WITH_AES_128_CBC_SHA
 V3CipherSuites                  TLS_DH_DSS_WITH_AES_128_CBC_SHA
}
PortRange                         portR1
{
 Port                            2760-2770
}
PortRange                         portR2
{
 Port                            1024-65535
}