Enabling TLS/SSL for z/OS Load Balancing Advisor (optional)

For AT-TLS, the following customization tasks are required before starting the TCP/IP stacks and the Advisor and Agent applications:

Enable AT-TLS in the TCP/IP stack.
Specify the TTLS parameter on the TCPCONFIG statement in the TCP/IP profile. For additional information about AT-TLS, see Application Transparent Transport Layer Security data protection. For information about the TCPCONFIG statement, see z/OS Communications Server: IP Configuration Reference.
Set up authorization for the pasearch command, if the command will not be issued from a superuser.
Create a SERVAUTH profile of EZB.PAGENT.sysname.image.ptype, where the ptype value is set to TTLS or to a wildcard value. For more information, see Steps for configuring the Policy Agent and z/OS Security Server RACF Security Administrator's Guide.
Enable AT-TLS configuration for the Policy Agent.
Specify the CommonTTLSConfig and TTLSConfig statements in the Policy Agent configuration file for each stack. On the TTLSConfig statement, specify the path of the stack-specific AT-TLS policy file to be installed for the server. For additional information about the CommonTTLSConfig and TTLSConfig statements, see z/OS Communications Server: IP Configuration Reference.
Define AT-TLS policies in new or existing Policy Agent configuration files.
Specify the AT-TLS policies in the configuration files that are identified with the CommonTTLSConfig and TTLSConfig statements. Ensure that the Load Balancing Advisor policy definitions are defined on all systems in the sysplex on which the Advisor can run.

The Load Balancing Advisor is a server application. For general information about setting up AT-TLS for a server, see Table 1.

The following example shows the TTLSConfig policy file statements in the path file for the load balancer connections to the Advisor. Port 3860 is the default port.
```
TTLSRule                 LBAdvisorLBRule  
{
   LocalPortRange            3860  
   Direction                 Inbound    
   TTLSGroupActionRef        LBAdvisorLBGroup   
   TTLSEnvironmentActionRef  LBAdvisorLBEnvironment    
}
TTLSGroupAction          LBAdvisorLBGroup  
{
   TTLSEnabled               On    
}
TTLSEnvironmentAction    LBAdvisorLBEnvironment
{
   TTLSKeyRingParms  
   {    
      Keyring                server_key_ring  
   }
   TTLSEnvironmentAdvancedParms
   {
      # TTLS will verify a user ID is associated with certificate
      ClientAuthType         SAFCheck
      ApplicationControlled  On
   }
   HandshakeRole             ServerWithClientAuth
   TTLSCipherParmsRef        RequireEncryption
   Trace                     7
}
```
In this example, all external load balancers must use TLS/SSL and supply a client certificate that will be validated in the key ring and must be associated with a user ID on the SAF-compliant security product on the local z/OS® system. This type of policy allows additional finer-grain SAF checks using optional SERVAUTH profiles. You can use other, less restrictive, policies; however, if you use less restrictive policies, the Advisor, Agent, and ADNR require that you specify the configuration parameters for those connections (lb_id_list or agent_id_list statements in the Advisor configuration file, host_connection statement in the Agent configuration file, and host_connection_addr statement in the ADNR configuration file).

The following example shows the TTLSConfig policy file statements in the path file for the Agent connections to the Advisor. Port 8100 is the port that is used in the sample Advisor configuration file:
```
TTLSRule                 LBAdvisorAgentRule  
{
   LocalPortRange            8100  
   Direction                 Inbound    
   TTLSGroupActionRef        LBAdvisorAgentGroup   
   TTLSEnvironmentActionRef  LBAdvisorAgentEnvironment    
}
TTLSGroupAction          LBAdvisorAgentGroup  
{
   TTLSEnabled               On    
}
TTLSEnvironmentAction    LBAdvisorAgentEnvironment
   {
   TTLSKeyRingParms  
   {
      Keyring                server_key_ring  
   }
   TTLSEnvironmentAdvancedParms
   {
      # TTLS will verify a user ID is associated with certificate
      ClientAuthType         SAFCheck
      ApplicationControlled  On
   }
   HandshakeRole             ServerWithClientAuth
   TTLSCipherParmsRef        RequireEncryption
   Trace                     7
}

# Set of TLS Ciphers with Encryption
TTLSCipherParms RequireEncryption
{
   V3CipherSuites        TLS_RSA_WITH_RC4_128_MD5
   V3CipherSuites        TLS_RSA_WITH_RC4_128_SHA
   V3CipherSuites        TLS_RSA_WITH_DES_CBC_SHA
   V3CipherSuites        TLS_RSA_WITH_3DES_EDE_CBC_SHA
}
```
The Load Balancing Agent is a client application. For general information about setting up AT-TLS for a client, see Table 1.

You must configure the policy on the TCP/IP stack where the Agents will run with the same SSL protocol, key ring, and cipher suite (if encrypting data) for which the Advisor is configured.

The following example shows the TTLSConfig policy file statements for a Load Balancing Agent. On the TTLSConfig statement, specify the path of the stack-specific AT-TLS policy file to be installed for the client. For more information about the TTLSConfig statement, see z/OS Communications Server: IP Configuration Reference. Port 8100 is the port that is used in the sample Agent configuration file.
```
TTLSRule                     LBAgentRule 
{ 
   RemotePortRange               8100 
   Direction                     Outbound
   TTLSGroupActionRef            LBAGroup
   TTLSEnvironmentActionRef      LBAgentEnvironment
}
TTLSGroupAction              LBAGroup
{
   TTLSEnabled                   On 
}
TTLSEnvironmentAction        LBAgentEnvironment
{
   TTLSKeyRingParms
   {
      Keyring                  client_key_ring
   }
	  HandshakeRole                 CLIENT
	  TTLSCipherParmsRef            RequireEncryption
	  Trace                         7
}

# Set of TLS Ciphers with Encryption
TTLSCipherParms RequireEncryption
{
   V3CipherSuites        TLS_RSA_WITH_RC4_128_MD5
   V3CipherSuites        TLS_RSA_WITH_RC4_128_SHA
   V3CipherSuites        TLS_RSA_WITH_DES_CBC_SHA
   V3CipherSuites        TLS_RSA_WITH_3DES_EDE_CBC_SHA
}
```
For additional information, see:
- Policy-based networking.
- Application Transparent Transport Layer Security data protection. Table 1 is for the Advisor, and Table 1 is for the Agent and for load balancers.
- AT-TLS policy statements in z/OS Communications Server: IP Configuration Reference
- CommonTTLSConfig and TTLSConfig statements in z/OS Communications Server: IP Configuration Reference.
- Online help for the IBM® Configuration Assistant for z/OS Communications Server
Create z/OS server (Advisor) and client (Agent, ADNR, external load balancer) key rings and necessary certificate authority certificates.
The server key ring needs to contain a server certificate, and any certificates that are used to sign it. The server needs access to the private keys of the server certificate. The client key ring needs the root certificate that is used to sign the server certificates.

For a TLS/SSL primer and some step-by step examples, see TLS/SSL security. For more information about managing key rings and certificates with RACF® and the RACDCERT command, see z/OS Security Server RACF Security Administrator's Guide. For detailed information about managing key rings and certificates with gskkyman, see z/OS Cryptographic Services System SSL Programming.
Send the external load balancer's certificate to the z/OS host.
Associate each user ID (for the Advisor, Agents, ADNRs, and external load balancers) with a certificate.
Use the RACDCERT ADDRING command to define a key ring in RACF and to associate it with your application's user ID. Use the RACDCERT CONNECT command to connect certificates to the key ring. For detailed information about setting up your certificate environment, see z/OS Security Server RACF Security Administrator's Guide.
Create client side certificates for the external load balancers. See the load balancer documentation for instructions.
Define client user IDs on the TCP/IP stacks on which the Advisor will run by issuing security product commands to establish authorization for the user IDs.
You can configure the Advisor's clients (Agents, ADNR, and external load balancers) to present security credentials, including a user ID. If you configure this, you must set up the security manager on the Advisor system to accept these credentials.

Using a security product like RACF, perform the following steps to control access to the Load Balancing Advisor, Agents, and ADNR.
1. Use the following commands to ensure that the SERVAUTH class is active and RACLISTed, and that RACLIST processing is enabled:
```
SETROPTS CLASSACT(SERVAUTH)
SETROPTS RACLIST (SERVAUTH)
```
2. Use the following commands to define the following SERVAUTH class profiles on each system on which the Advisor might run.
```
RDEFINE SERVAUTH EZB.LBA.LBACCESS.sysname.tcpsysplexgroupname UACC(NONE)
RDEFINE SERVAUTH EZB.LBA.AGENTACCESS.sysname.tcpsysplexgroupname UACC(NONE)
```
  where sysname is the MVS™ system name or a wildcard (*) and tcpsysplexgroupname is the TCP/IP sysplex group name. If you are not using subplexing, use the default subplex identifier EZBTCPCS or a wildcard (*). For example, on system MVSSYS using the default subplex, the profile name is EZB.LBA.LBACCESS.MVSSYS.EZBTCPCS.
3. Use the following commands to grant access to the SERVAUTH class for the user IDs associated with the Agents, ADNR, and the external load balancers on each system on which the Advisor might run:
```
PERMIT   EZB.LBA.LBACCESS.sysname.tcpsysplexgroupname -
   CLASS(SERVAUTH) ACCESS(READ) ID(userid)
PERMIT   EZB.LBA.AGENTACCESS.sysname.tcpsysplexgroupname -
   CLASS(SERVAUTH) ACCESS(READ) ID(userid)
```
4. Use the following command to refresh the SERVAUTH class:
```
SETROPTS RACLIST(SERVAUTH) REFRESH
```
For specific instructions, see the EZARACF sample in SEZAINST.
Requirements:
- The AT-TLS policies and SERVAUTH profiles must be coordinated to provide the appropriate level of security. For example:
  - If a connection is presented to the Advisor and the AT-TLS check indicates that this is not a secure connection, then no subsequent SAF check is performed but an IP address ACL check (using the statements in the Load Balancer Advisor configuration files) is performed. If the IP address ACL check is successful, the connection is accepted.
  - If you always want a SAF level check to be performed, then ensure that the AT-TLS policy requires client certificates that are associated with user IDs defined on the local SAF-compliant security product. Also ensure that the SAF profile is defined and the correct user IDs are permitted READ access to the profile. If a secure connection is presented to the Advisor, and the SAF profile exists but the user ID is not authorized to the profile, then the connection will fail and no ACL check will be performed.
  - If the SERVAUTH profile is not defined, then the Load Balancer Advisor performs the IP Address (and port where appropriate) access control list checks before permitting a connection to the Load Balancer Advisor.
- If the Advisor might run on more than one system, perform set up on all those systems or use a wildcard (*).
For additional information, see z/OS Security Server RACF Security Administrator's Guide.