How to configure a AT-TLS connection from z/OS applications

Configure an IBM® z/OS® Communications Server Application Transparent Transport Layer Security (AT-TLS) for secure connections from your z/OS application to IBM z/OS Connect.

This task is applicable when IBM z/OS Connect is used as an API requester.

About this task

To configure secure connections between the z/OS application and the z/OS Connect server:
  • In the z/OS application:
    1. Specify the hostname and the port number for z/OS Connect server in the BAQURI and BAQPORT parameters in the CEEOPTS DD statement. Ensure that BAQPORT specifies the z/OS Connect server port. If an inbound AT-TLS policy is defined, use the z/OS Connect HTTP port number, otherwise use the z/OS Connect HTTPS port number. For more information, see Configuring other z/OS applications to access IBM z/OS Connect for API calls.
    2. Set up AT-TLS, configure a key ring and policy files, as shown below.
  • In the z/OS Connect server side, see How to configure TLS with RACF key rings.
You must create a key ring to store the Certificate Authority (CA) root certificate and the server certificate that is signed by the (CA) private key. Store the CA certificate in the z/OS Connect truststore and the certificate in the server keystore. The following diagram shows Certificate Authority (CA) root certificate, the key ring, the server keystore, and the server truststore that are required for secure connections between the z/OS Connect server and the communication stub.
Figure 1. Secure connection configuration for z/OS applications to call API requesters
Diagram shows how AT-TLS references the certificate stored on the keyring

Procedure

The following steps demonstrate how to generate the Certificate Authority (CA) root certificate, the server certificate, and the key ring.

  1. On the z/OS subsystem, use the RACDCERT command to generate the CA root certificate, the certificate, and the key ring.
    1. Create a key ring.
      The following example creates a key ring, ZOSCONN-APIR-KEYRING.
      /*-----------------------------------------------------------*/  
/*  Create a key ring (ZOSCONN-APIR-KEYRING in this example).*/ 
/*-----------------------------------------------------------*/  
RACDCERT ADDRING(ZOSCONN-APIR-KEYRING) ID(OMVSADM)
    2. Create the CA root certificate for the server.
      The following example generates a CA certificate and connect it to the key ring ZOSCONN-APIR-KEYRING.
       /*-----------------------------------------------------------*/  
 /*  Create a certificate to use as the Certificate Authority */
 /*  (CA), export to dataset, and connect to the key ring,    */
 /*  ZOSCONN-APIR-KEYRING.                                    */  
 /*-----------------------------------------------------------*/  
RACDCERT CERTAUTH GENCERT -                                       
 SUBJECTSDN(CN('IMSCA') OU('ZCEE') O('US IBM SVL') C('US')) -    
 KEYUSAGE(CERTSIGN) WITHLABEL('IMSCA')                            
 RACDCERT CERTAUTH EXPORT(LABEL('IMSCA')) DSN(CERTAUTH.CERT)     
RACDCERT CONNECT(CERTAUTH LABEL('IMSCA') -
 RING(ZOSCONN-APIR-KEYRING)) ID(OMVSADM)
  2. Create a server certificate, signed by the CA, for API requester clients to authenticate with the server.
    In the following example, ZOSCONNCERT is the label for the z/OS Connect server certificate, signed by the IMSCA certificate authority, in PKCS12 format.
     /*-----------------------------------------------------------*/
 /*  Create z/OS Connect server certificate, export to     */
 /*  dataset, and connect to ZOSCONN-APIR-KEYRING.            */
 /*-----------------------------------------------------------*/
RACDCERT GENCERT -
 SUBJECTSDN(CN('ZCEESERVER.MYCOM.COM') T('MY ZCEE SERVER') -
 OU('ZCEE') O('US MYCOM COM') L('SANJOSE') SP('SANJOSE') C('US'))-
 SIZE(2048) WITHLABEL('ZOSCONNCERT') -
 SIGNWITH(CERTAUTH LABEL('IMSCA')) ID(OMVSADM)
RACDCERT EXPORT(LABEL('ZOSCONNCERT')) DSN(ZCONN.CERT.P12DER) -
 FORMAT(PKCS12DER) PASSWORD('imsmobile') ID(OMVSADM)
RACDCERT CONNECT(LABEL('ZOSCONNCERT') -
 DEFAULT RING(ZOSCONN-APIR-KEYRING)) -
 ID(OMVSADM)

 /*-----------------------------------------------------------*/        
 /*  Permit user IDs associated with server and client to     */        
 /*  access the certificates.                                 */        
 /*-----------------------------------------------------------*/        
SETROPTS RACLIST(DIGTCERT) REFRESH                                      
RDELETE FACILITY (IRR.DIGTCERT.LIST    IRR.DIGTCERT.LISTRING)           
RDEFINE  FACILITY  IRR.DIGTCERT.LISTRING   UACC(NONE)                   
RDEFINE  FACILITY  IRR.DIGTCERT.LIST       UACC(NONE)                   
PERMIT   IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(OMVSADM) ACCESS(ALTER)
PERMIT   IRR.DIGTCERT.LIST     CLASS(FACILITY) ID(OMVSADM) ACCESS(ALTER)
SETROPTS CLASSACT(FACILITY)                                             
SETROPTS RACLIST(FACILITY) REFRESH                                      
//
  3. Exchange CA certificates with the z/OS Connect server.
    Work with your z/OS Connect security administrator to
    • Export the CA root certificate created for the z/OS application and add it to the z/OS Connect server's truststore. This will allow the z/OS Connect server to trust the certificate sent from the z/OS application.
    • Export the z/OS Connect server's CA certificate and add it to the z/OS application RACF key ring. This will allow the z/OS application to trust the certificate sent from the z/OS Connect server.
    For more information, see How to configure TLS with RACF key rings.

The following steps demonstrate high-level AT-TLS configuration steps on the client application side:

  1. Create Policy Agent files and store the files in z/OS UNIX System Services (USS) file system directory that can be accessed when you start the policy agent.
    1. Create a Policy Agent main configuration file containing a TcpImage statement for the z/OS Connect 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.
  2. Activate the RACF® SERVAUTH class using the TSO command: SETROPTS CLASSACT(SERVAUTH)
  3. Set up InitStack access control:
    1. Define the EZB.INITSTACK.SYSNAME.TCPNAME profile for each AT-TLS stack.
    2. Permit administrative applications to use the stack before AT-TLS is initialized.
      The following sample JCL sets up InitStack access control (based on the member EZARACF in sample data set SEZAINST): 
      //TLSRACF JOB MSGLEVEL=(1,1),USER=OMVSADM,PASSWORD=ALL1SDUN,            
//        CLASS=A,MSGCLASS=A                                            
//*                                                                     
/*ROUTE PRINT THISCPU/IMSTST43                                          
//   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.TCPNAME CLASS(SERVAUTH) ID(*) ACCESS(READ) - 
       WHEN(PROGRAM(PAGENT,EZAPAGEN))                                   
SETROPTS GENERIC(SERVAUTH) REFRESH                                      
SETROPTS RACLIST(SERVAUTH) REFRESH                                      
SETROPTS WHEN(PROGRAM) REFRESH                                          
//
  4. Enable AT-TLS by adding the following lines to the SYS1.TCPPARMS(PROFILE) member. 
    ;Enable AT-TLS Support
TCPCONFIG TTLS
  5. Restart TCP/IP, if it is currently running, by issuing P TCPIP and then S TCPIP.
  6. 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. Modify the path to syslog.conf based on your setup. 
      /usr/sbin/syslogd -f /etc/syslog.conf &
  7. Start the policy agent with the following command. Modify the path to your Policy Agent file based on your setup. 
    /usr/sbin/pagent -c /etc/sysname_pagent.conf -l SYSLOGD &
    Verify that the TCP/IP stack has received the AT-TLS policy and has issued console message EZZ4248E.