For AT-TLS, the following customization tasks are required before starting the TCP/IP stacks and the Advisor and Agent applications:
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.
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.
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.
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:
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.
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.
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.
SETROPTS CLASSACT(SERVAUTH)
SETROPTS RACLIST (SERVAUTH)
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.
PERMIT EZB.LBA.LBACCESS.sysname.tcpsysplexgroupname -
CLASS(SERVAUTH) ACCESS(READ) ID(userid)
PERMIT EZB.LBA.AGENTACCESS.sysname.tcpsysplexgroupname -
CLASS(SERVAUTH) ACCESS(READ) ID(userid)
SETROPTS RACLIST(SERVAUTH) REFRESH
For specific instructions, see the EZARACF sample in SEZAINST.
For additional information, see z/OS Security Server RACF Security Administrator's Guide.