Setting up AT-TLS SSL for IMS Connect

You can set up IBM® z/OS® Communications Server Application Transparent Transport Layer Security (AT-TLS) to set up Secure Socket Layer (SSL) on TCP/IP connections to IMS Connect. Setting up AT-TLS is the recommended method for enabling SSL for IMS Connect.

Perform the following procedure to set up SSL for IMS Connect by setting up AT-TLS:

Procedure

On each z/OS system where you run IMS Connect, create a server key ring with a server certificate and the necessary certificate authority certificates.
Create Policy Agent files:
1. Create a Policy Agent main configuration file containing a TcpImage statement for the server stack.
  Set the TcpImage statement to point to the image configuration file.
2. Create a Policy Agent image configuration file containing a TTLSConfig statement for the server stack.
  Set the TTLSConfig statement to point to the TTLSConfig policy file.
3. Create and configure a Policy Agent TTLSConfig policy file, and add the AT-TLS policy statements to this file.
  Most of the SSL settings are in this file. Set the security suite you want to support, and specify which ports to use SSL.
4. Store all the configuration files in a z/OS UNIX System Services file system directory that can be accessed when you start the Policy Agent.
Activate the RACF® SERVAUTH class.
Issue the following command from TSO:
```
SETROPTS CLASSACT(SERVAUTH)
```

Set up InitStack access control:

Define the EZB.INITSTACK.SYSNAME.TCPNAME profile for each AT-TLS stack.
Permit administrative applications to use the stack before AT-TLS is initialized.

The following is sample JCL to set up InitStack access control (based on the member EZARACF in sample data set SEZAINST):

//TLSRACF JOB MSGLEVEL=(1,1),USER=USERNAME,PASSWORD=PASSWORD,
//        CLASS=A,MSGCLASS=A                                          
//*                                                                   
/*ROUTE PRINT THISCPU/IMSNAME                           
//   EXEC PGM=IKJEFT01                                                
//SYSTSPRT DD SYSOUT=*                                                
//SYSABEND DD SYSOUT=*                                                
//SYSTSIN DD *                                                        
SETROPTS RACLIST (SERVAUTH)                                           
SETROPTS CLASSACT(SERVAUTH)                                           
SETROPTS GENERIC (SERVAUTH)                                           
RDEFINE SERVAUTH EZB.INITSTACK.SYSNAME.TCPNAME UACC(NONE)
PERMIT EZB.INITSTACK.SYSNAME.TCPIP CLASS(SERVAUTH) ID(*) ACCESS(READ) -
       WHEN(PROGRAM(PAGENT,EZAPAGEN))                                 
SETROPTS GENERIC(SERVAUTH) REFRESH                                    
SETROPTS RACLIST(SERVAUTH) REFRESH                                    
SETROPTS WHEN(PROGRAM) REFRESH                                        
//

From the z/OS console, you can find the SYSNAME in the SYS= field. To find the TCPNAME, issue the D A,L command.

Enable AT-TLS. Perform one of the following steps:
- Add the following lines to the SYS1.TCPPARMS(PROFILE) member:
```
;Enable AT-TLS support
TCPCONFIG TTLS
```
- Put the following lines in a separate file and run the V TCPIP,,O,SYS1.TCPPARMS(filename) (VARY) command:
```
;Enable AT-TLS support
TCPCONFIG TTLS
```
  Note: If you perform this step, skip steps 6 and 8.
If TCP/IP and IMS Connect are running, stop TCP/IP and IMS Connect.
To stop IMS Connect, issue the IMS Connect WTOR command CLOSEHWS.
Configure and start the syslog daemon (syslogd):
1. Review your syslogd configuration (/etc/syslog.conf) to verify that messages written by the Policy Agent and TCP/IP stacks are saved in the intended files.
  AT-TLS syslogd messages are written to the daemon facility by default. A sample configuration file is provided by z/OS in /usr/lpp/tcpip/samples/syslog.conf.
2. Start syslogd with the following command:
```
/usr/sbin/syslogd -f /etc/syslog.conf &
```
Note: To stop this job, run the following command: kill process_ID. To find the process_ID, run the following command: ps -A.
Start the TCP/IP stack.
Run the following command from the z/OS console:
```
S TCPIP
```
Start the Policy Agent and verify that there were no policy errors in processing the policy files:
1. Run the following command:
```
/usr/sbin/pagent -c /etc/sysname_pagent.conf -l SYSLOGD &
```
  The pagent executable is in /usr/sbin.
2. Verify that the TCP/IP stack has received the AT-TLS policy and has released console message EZZ4248E.
Note: To stop this job, run the following command: kill process_ID. To find the process_ID, run the following command: ps -A.
Update the IMS Connect configuration member (HWSCFGxx) and start IMS Connect:
1. In HWSCFGxx, specify the ports that you want to use for SSL as regular non-SSL ports.
  Perform one or both of the following steps:
  - If you are connecting to IMS TM, specify the ports in the PORT and PORTID parameters on the TCPIP statement.
  - If you are connecting to IMS DB, specify the ports in the DRDAPORT parameter on the ODACCESS statement.
  If a specified port matches one of the SSL ports from the sysname_pagent_TTLS.conf file, an SSL client can connect to that port. If no specified ports match an SSL port from the sysname_pagent_TTLS.conf file, only non-SSL clients can connect to it.
2. If you are migrating from using IMS Connect's SSL function to using AT-TLS, then complete the following steps:
  - Remove the SSLENVAR parameter. The member that is defined in this parameter is no longer required. This is because the SSL ciphers and protocols that were defined in the parameter's member are now defined in the Policy Agent TTLSConfig policy file, which you created earlier in this procedure.
  - Remove the SSLPORT parameter and specify the port number in the PORT or PORTID parameter.
    Here is an example that specifies port 8888 to use IMS Connect's SSL function:
    TCPIP=(HOSTNAME=TCPIP,PORTID=(9999,9998,LOCAL),
    To change port 8888 to use AT-TLS, remove SSLPORT and specify port 8888 in the PORTID parameter:
    TCPIP=(HOSTNAME=TCPIP,PORTID=(9999,9998,8888,LOCAL),
    IMS Connect treats port 8888 as a normal port. Traffic coming through this port does not go through IMS Connect's SSL function. All the SSL processing would be done by the z/OS AT-TLS stack instead.
    
    Note: AT-TLS is the recommended method to enable SSL for IMS Connect.
3. Start IMS Connect by running JCL.

Configure the IMS Universal database resource adapter for SSL support in a container-managed environment.
Configure IMS Universal drivers for SSL support in a stand-alone environment.