Creating and deploying a policy file for Application Transparent Transport Layer Security

Application Transparent Transport Layer Security (AT-TLS) is a service that is provided by the z/OS Communication Server Policy Agent (PAGENT) and the TCP/IP stack. The AT-TLS service manages connections on behalf of applications that are running on the z/OS operating system. You create the AT-TLS policy file, install the configuration files, and upload them to the necessary z/OS system, for a host connection.

1. Download and install IBM Configuration Assistant for z/OS Communications Server, V1.13 or later. You create an AT-TLS policy file by using the Configuration Assistant GUI.
   Note: Starting with z/OS Version 1 Release 1, the IBM Configuration Assistant is replaced by dialogs in the z/OS Management Facility (z/OSMF).
2. Start the configuration assistant by clicking Start > All Programs > IBM Programs > IBM Configuration Assistant for z/OS > Configuration Assistant V1R13.
3. From the Perspective menu, select AT-TLS.
4. In the AT-TLS Perspective window, click Add a New z/OS Image.
5. In the New z/OS Image window, enter information in the z/OS image name, Description, z/OS release and Key ring fields, and then click OK.

   This key ring name must be the same name that you used when you first generated a key ring. See Configuring a secure communication between HyperSwap and the client.

6. In the Proceed to the Next Step window, click Yes to add a TCP/IP stack to the z/OS image.
7. In the New TCP/IP Stack Information window, type a stack name in the TCP/IP stack name field, add information to the Description field, and then click OK.
8. In the AT-TLS Perspective window, click Add to create a connectivity rule.
9. In the New Connectivity Rule wizard, click Next.
10. Identify the data endpoints by completing the following fields:
    1. In the Connectivity rule name field, enter a suffix for a name of the rule.
    2. In the Local data endpoint field, select ALL_IP_Addresses.
    3. In the Remote data endpoint field, select ALL_IP_Addresses.
    4. Click Next.
    A generic rule facilitates testing.
11. Click Traffic Descriptor.
12. Click Add to add a traffic descriptor.
13. In the New Traffic Descriptor page, enter information in the Name and Description fields. Click Add.

    In the New Traffic Type notebook, use the Details tab to specify the port configuration for the HyperSwap side of the port.

14. In the New Traffic Type notebook, click the Key Ring tab and specify the certificate label for your key ring and click OK. Click OK again, and then click Close.
15. In the New Connectivity Rule-Select Requirement Map page, click Create a new requirement map. Verify that this new map includes the traffic descriptor that you created in step 12.
    1. In the Name field, enter the name of the requirement map.
    2. Click Security Levels and add a security level. The security level that you select needs to support TLSv1.2.
    3. Click Next.
16. Click Advanced to add any other necessary stacks, if not, then click Finish.
17. Select the enabled rule from the list and click Apply Changes.
18. On the Image Information tab, review the pertinent information and click Application Setup Tasks. Complete the initial setup tasks, including RACF directives and start procedures.
19. In the Application Setup Tasks window, click Display All Instructions to see more detailed information. The Task Configure Installation Setup window opens.
20. In the Task Configure Installation Setup window, click Location Information to input the installation setup. The Installation Location Setup window opens.
    1. Click Instructions to see the documentation that comes bundled with the application.
21. In the Installation Location Setup window, enter your correct FTP information to upload the policy file. Click OK. After the file transfer, refresh or restart the policy agent (PAGENT).
22. In the AT-TLS Perspective window, click Install Configuration Files. The generated policy files are installed for the z/OS image. The List of Configuration Files window opens.
23. In an OMVS session, edit the /etc/pagent/conf.txt file by adding the following lines:

    LogLevel=255
    CommonTTLSConfig /etc/pagent/ttlsPol.txt 
    TTLSConfig/etc/pagent/ttlsPol.txt 

24. In an OMVS session, edit the /etc/pagent/env.txt file by adding the following lines:

    PAGENT_CONFIG_FILE=/etc/pagent/conf.txt
    PAGENT_LOG_FILE=/tmp/pagent2.log 

25. If the member PAGENT does not already exist in SYS1.PROCLIB, copy the sample JCL PAGENT in the TCPIP.SEZAINST library to the system procedure library (for example, SYS1.PROCLIB). Then edit the following line in SYS1.PROCLIB(PAGENT):

    //STDENV   DD PATH='/etc/pagent/env.txt',PATHOPTS=(ORDONLY) 

26. In the List of Configuration files window, view the configuration files and click Install.
27. In the Install Files to Remote host window, confirm the credentials and the FTP logon information. Verify that the file location is /etc/pagent/ttlsPol.txt, and then, click Go. The policy file is installed.
28. Create a data set, datasetname with the following contents:

    TCPCONFIG TTLS

    1. Issue the following command:

       V TCPIP,TCPIP,OBEYFILE,datasetname

29. If PAGENT has not already been started, it needs to be started.

    START PAGENT

30. Then cancel, and restart HSIB.

    START HSIB

##
## AT-TLS Policy Agent Configuration file for:
##      Image: SC30
##      Stack: TCPIP
##
## Created by the IBM Configuration Assistant for z/OS Communications Server
## Version 2 Release 2
## Backing Store = CSM_STORE
## Install History:
## 2017-01-24 20:40:01 : lascu to 9.12.4.211
##
## End of Configuration Assistant information
TTLSRule                                      HS_test~1
{
LocalAddrSetRef                               addr1
RemoteAddrSetRef                              addr1
LocalPortRangeRef                             portR1
Direction                                     Both
Priority                                      255
TTLSGroupActionRef                            gAct1~Basic_HS
TTLSEnvironmentActionRef                      eAct1~Basic_HS
TTLSConnectionActionRef                       cAct1~Basic_HS
}
TTLSGroupAction                               gAct1~Basic_HS
{
TTLSEnabled                                   On
}
TTLSEnvironmentAction                         eAct1~Basic_HS
{
   HandshakeRole                              Server
   EnvironmentUserInstance                    0
   TTLSKeyringParmsRef                        keyR~SC30
}
TTLSConnectionAction                          cAct1~Basic_HS
{
   HandshakeRole                              Server
   TTLSCipherParmsRef                         cipher1~AT-TLS__Silver
   TTLSConnectionAdvancedParmsRef             cAdv1~Basic_HS 
   CtraceClearText                            Off
   Trace                                      2
}
TTLSConnectionAdvancedParms                   cAdv1~Basic_HS
{
TLSv1.2                                       On
HandshakeTimeout                              30
SecondaryMap                                  Off
}
TTLSKeyringParms                              keyR~SC30
{
   Keyring                                    csmkeyring
}
TTLSCipherParms                               cipher1~AT-TLS__Silver
{
   V3CipherSuites                             TLS_RSA_WITH_AES_128_CBC_SHA256
   V3CipherSuites                             TLS_RSA_WITH_AES_256_CBC_SHA256
   V3CipherSuites                             TLS_RSA_WITH_AES_128_GCM_SHA256
}
IpAddrSet                                     addr1
{
   Prefix                                     0.0.0.0/0
}
PortRange                                     portR1
{
   Port                                       5858
}