AT-TLS Configuration

You must configure every LPAR that drives the zAware agent as enabled for AT-TLS encryption.

Every LPAR that drives the zAware agent must be configured as enabled for Application Transparent Transport Layer Security (AT-TLS) encryption.

RACF Settings

Obtain the certificate that is provided by zAware to be used in the RACF® settings.
To complete, this step requires that zAware is installed and operational and available from a browser session. The steps to obtain the certificate are dependent on the browser version used.
The following example is for the Microsoft Internet Explorer browser:
1. Start the logon process to zAware (https://zaware.url/zAware/). Use the appropriate URL address for your local zAware server. The IBM® zAware login screen opens:
  Figure 1. IBM zAware login screen.
  
  Note: If you are running Windows 7, you must run Internet Explorer as ADMINISTRATOR so that you can save the certificate to a local file.
2. Select View > Security Report. You might see a message such as this:
  Figure 2. Certificate Invalid message.
3. Click View certificates. The Certificate window opens.
4. Select the Details tab.
  Figure 3. Certificate Window.
5. Note the Valid to date value that is shown. You might have to update your zAware certificate before this date to avoid service interruption.
6. Click Copy To File and follow the wizard prompts to save the certificate locally.
  Tip: Use base-64 encoding.
  The result looks like this example:
  Figure 4. Example of certificate file viewed in text editor.
7. Upload this certificate, as text, to your z/OS® LPAR where you configure the RACF and save it in a sequential file with these characteristics:
```
Organization  . . . : PS     
 Record format . . . : VB     
 Record length . . . : 80     
 Block size  . . . . : 27920  
 1st extent tracks . : 1      
 Secondary tracks  . : 0      
 Data set name type  :        
 SMS Compressible. . : NO     
```
  For this example the file is named ZAWARE.CERTX509.D130820. The last part of the file name reminds you that the certificate expires on 2013/08/20.
8. RACF commands for AT-TLS:
  The following RACF commands create a certificate specifically for the userid that the Tivoli® Enterprise Monitoring Server (TEMS) runs under. A site certificate could also be used instead.
  - SETROPTS CLASSACT(FACILITY)
  - SETROPTS CLASSACT(SERVAUTH)
  - RDEF FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
  - PE IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(TEMS_userid) ACC(READ)
    The value for TEMS_userid is the user ID that your Tivoli Enterprise Monitoring Server started tasks runs under. It can be found by looking at your Tivoli Enterprise Monitoring Server started task, JESMSGLG message ID IEF695I as shown in the following example:
    IEF695I START jobname WITH JOBNAME jobname IS ASSIGNED TO USER TEMS_userid, GROUP grpname
  - SETROPTS RACLIST(FACILITY) REFRESH
  - RDEF SERVAUTH EZB.INITSTACK.system_name.TCPIP UACC(NONE)
  - PE EZB.INITSTACK.system_name.TCPIP CLASS(SERVAUTH) ID(OMVSKERN) ACC(READ)
  - SETROPTS RACLIST(SERVAUTH) REFRESH
  - RACDCERT ADDRING(keyring) ID(TEMS_userid)
    The value that you use for keyring is carried forward to your Communications Manager settings as seen in the example ttls.policy file under the AT-TLS configuration, in step 3.
  - RACDCERT ADD('ZAWARE.CERTX509.D130820') TRUST WITHLABEL('trustlbl') ID(TEMS_userid)
    This command defines the certificate that is contained in the data set ZAWARE.CERTX509.D130820 to RACF. This certificate expires periodically. Replacing this file with the new certificate allows communications to flow again.
  - RACDCERT CONNECT(ID(TEMS_userid) LABEL('trustlbl') RING(keyring) DEFAULT USAGE(PERSONAL)) ID(TEMS_userid)
    This command grants permission to use the certificate to your Tivoli Enterprise Monitoring Server started task.
  - SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH
    This command activates the ADDRING change, assuming the DIGTRING CLASS is present in the RACLIST list in your environment.

AT-TLS configuration

Policy configuration settings for AT-TLS must be entered by an authorized system programmer.

Optional: If you have the IBM z/OS Management Facility (z/OSMF), you can use it to specify your AT-TLS policy.
Use z/OSMF to define your policy and the result is similar to the example definitions described in step 3.
The following is an example z/OSMF screen capture for the Configuration Assistant:

Figure 5. IBM z/OS Management Facility.
Follow these steps when you use z/OSMF:
- Specify the zOS Image that has the AT-TLS policy
  - Specify the TCP/IP stack name that uses the AT-TLS policy
- Under AT-TLS Perspective specify the following settings:
  
  Reusable Objects
  
  Traffic Descriptors
  
  Select Action ADD
  Give this descriptor a name and description.
  
  Under List of traffic types in this traffic descriptor, select Action ADD
  
  Details Tab
  
  Specify all local and remote ports. Indicate the TCP connect direction is Outbound only, and TLS handshake role is Client.
  
  Key Ring Tab
  
  Use simple name to specify the key ring that is created in the RACF settings.
  
  Advanced Tab
  
  Specify Application Controlled as On.
  
  Requirement Maps
  
  Select Action ADD
  Give this requirement map a name and description.
  
  Traffic Descriptor
  
  Select the traffic descriptor name that you created earlier in this procedure.
  
  Security Level
  
  The suggested setting is Default_Ciphers.
  
  z/OS Images
  
  Stack Connectivity Rules
  
  Select Action ADD
  Click Next
  
  Give this connectivity rule a name.
  
  Local data endpoint
  
  Select Address group as All_IP_Addresses or IPv4 address or IPv6 address or subnet range.
  
  Remote data endpoint
  
  Select IPv4 address or IPv6 address and specify the IP address for your zAware appliance.
  
  Requirements Map
  
  Use Select an existing requirements map and name the map that you created.
  Click Select next to Traffic Descriptor and Security Level
  
  Click Next tab
  
  Click Finish tab
  
  Install Configure Files
  
  Select the row that you created, click Show Configuration File.
  
  The resulting file is similar to the example ttls.policy file in step 3 with the addition of a TTLSCipherParms segment.

Configure the policy definitions.

As an example, assume that the TCPIP started task is named TCPIP. TCPIP has a PROFILES DD statement that points to the stack 's settings. The Communications Server provides for invocation of System SSL in the TCP transport layer of the stack. Application Transparent Transport Layer Security (AT-TLS) support is controlled by the TTLS or NOTTLS parameter on the TCPCONFIG statement in the TCP/IP profile. Ensure TTLS is specified.

The Policy Agent address space is likely called PAGENT. If this address space is not already running, copy EZA.SEZAINST(PAGENT) to a PROCLIB library and set it for automatic start at each IPL. Do this step by adding the following statement:

PAGENT to SYS1.PARMLIB(COMMNDxx)
COM='S PAGENT                                PAGENT'

The JCL for PAGENT has a single step that runs program PAGENT, (//PAGENT EXEC PGM=PAGENT). It has a DD statement like:

//STDENV   DD PATH=

This statement defines where the policy statements begin. If this statement is not already set, then set it as follows:

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

systemdir is the directory for the LPAR being configured. In this example, it is named SYSA. Ensure that the file contains PAGENT_CONFIG_FILE=//'sys1.tcpparms(PAGENT)'. You can choose whatever file name is appropriate for your installation 's naming conventions. In this example, it is named SYS1.TCPPARMS. Edit the file SYS1.TCPPARMS (PAGENT) and find or enter the statement:

TcpImage TCPIP  /SYSA/etc/pagent/TCPIP.policy FLUSH PURGE

The TcpImage statement identifies the z/OS UNIX file or MVS™ data set that contains policy for that stack. In /SYSA/etc/pagent/TCPIP.policy you either see or insert the statement:

TTLSConfig /SYSA/etc/pagent/ttls.policy

The TTLSConfig statement identifies the z/OS UNIX file or MVS data set that contains the local AT-TLS policy. The TTLSConfig statement is required for each stack that receives AT-TLS policy. In this example, the UNIX System Services directory is /SYSA/etc/pagent/ttls.policy.

Example entries for the file ttls.policy:

TTLSGroupAction    KDEBEGRPACT                   
{                                                
  TTLSEnabled  On                                
  TRACE 15                                       
}  
                                              
TTLSEnvironmentAdvancedParms      KDEBEADV       
{                                                
 ApplicationControlled  On                       
 ClientAuthType         PassThru                 
}   
                                             
TTLSEnvironmentAction    ZAWAREENV               
{                                                
   TTLSKeyringParms                              
   {                                             
      Keyring   keyring        <== same Keyring name used with RACF
   }                                             
   HandShakeRole   Client                        
   TTLSEnvironmentAdvancedParmsRef    KDEBEADV   
}    
                                            
TTLSConnectionAction          KDEBECONNOUT       
{                                                
  HandShakeRole   Client                         
}        
                                        
TTLSRule                    ZAWARE               
{                                                
  RemoteAddr   n.nn.nn.nnn                    <== the IP address used on your z/OS LPAR 
                                                  to communicate with the zAware server 
  Direction    Outbound                          
  TTLSGroupActionRef         KDEBEGRPACT         
  TTLSEnvironmentActionRef   ZAWAREENV           
  TTLSConnectionActionRef    KDEBECONNOUT        
}

Refresh the Policy Agent to incorporate any changes by using operator commands.
1. Optional: Bring your TCPIP stack down and back up.
  Do this step only the first time you enable TCPIP to use AT-TLS or if you previously did not have a policy agent setup.
  
  For example, use the following commands:
  P TCPIP
  
  S TCPIP
  
  Tip: If you normally start other tasks when you start TCPIP, you might want to stop those tasks also when you stop TCPIP and then start them again when you start TCPIP.
2. Refresh the Policy Agent.
  If the Policy Agent is running, use the command F PAGENT,REFRESH
  
  If PAGENT is not running, then start it.
Messages similar to the following are displayed:
```
EZZ4250I AT-TLS SERVICES ARE AVAILABLE FOR TCPIP
```
```
EZZ8771I PAGENT CONFIG POLICY PROCESSING COMPLETE FOR TCPIP : TTLS
```
```
EZD1586I PAGENT HAS INSTALLED ALL LOCAL POLICIES FOR TCPIP
```