Configuring the Policy Agent on IBM Z for use with Data Gate

z/OS® Communications Server stores all configuration settings for AT-TLS in a central component called the Policy Agent. As the name suggests, this agent executes a policy, which is a set of configurable instructions. You must adapt the policy for encrypted network traffic between a client LPAR and Data Gate.

Before you begin

Important: Configuring the Policy Agent requires the OpenShift® route hostname and the IP address and route port of the Data Gate instance. If you have not yet created a Data Gate instance, you can still configure the Policy Agent as described here with proper planning for the hostname, IP address, and port. If the Data Gate instance is already created, the route hostname and route port are listed on the Data Gate instance page (in My instances). The IP address of the Data Gate instance can be determined using the ping command.

About this task

The following steps show how to configure the Policy Agent for a single client LPAR and a Data Gate instance. It is a walk-through based on examples. The following IP addresses, user ID, and key ring are used in the examples:

Data Gate IP address	`9.30.198.104`
route hostname	`<route hostname>`
route port	443
TSO user ID of key ring owner	ID of Db2® started task user, for example `DB2USER`
Key ring	`DB2AKEYRING`

Procedure

Use TSO to log on to the z/OS client LPAR that connects to the Data Gate instance.
Open the Policy Agent configuration file in an editor, such as ISPF.
Add a TTLSCipherParms element that specifies the encryption algorithms to be used for the TLS connection.
Specify the following CIPHERS:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
Note: AES 128 is faster, but AES 256 is more secure. You can enforce the use of a specific cipher by specifying one cipher only. By default, AES 128 is used if you specify both.

The following example uses the V3CipherSuites4Char keyword to specify these ciphers by using a combination of two 4-digit hexadecimal numbers:
```
TTLSCipherParms              StunnelParms
{
   V3CipherSuites4Char       C02FC030
}
```
Alternatively, you can specify the ciphers in the following way:
```
TTLSCipherParms StunnelParms
{
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
}
```
Important: Only use the ciphers listed in the example above. Do not specify other ciphers.

Add a TLS group action that enables AT-TLS security:

TTLSGroupAction              StunnelGroup
{
       TTLSEnabled                       On
}

Specify a TLS environment that includes the following information:

The key ring containing the root certificate
Use of TLS version 1.2 as the only supported protocol
Client authentication pass-thru (optional)
ClientHandshakeSNI is required and specifies the route hostname in ClientHandshakeSNIList. A valid route hostname follows this pattern:
```
<dg-instance-prefix>.apps.<cluster-subdomain>.<domain>
```
That is, a name prefix must be followed by apps, the name of the cluster subdomain and the domain name.
CLIENT as the handshake role
The TTLSCipherParms element defined before
The trace level (use different trace levels for production (0) and problem diagnosis (7 or 255)

According to the example, this results in the following specification:

TTLSEnvironmentAction        StunnelClientEnvironment
{
       TTLSKeyRingParms
         {
           Keyring                       DB2USER/DB2AKEYRING   
         }
	TTLSEnvironmentAdvancedParms
  	 {
              SSLv2 Off
	       SSLv3 Off
	       TLSv1 Off
	       TLSv1.1 Off
	       TLSv1.2 On
	       TLSv1.3 Off
	       ClientAuthType PassThru
		CLIENTHANDSHAKESNI REQUIRED
              CLIENTHANDSHAKESNIMATCH OPTIONAL                    
              CLIENTHANDSHAKESNILIST <route hostname>

   	}
       HandshakeRole                     CLIENT
       TTLSCipherParmsRef                StunnelParms
       Trace                             7
}

Add an outbound TTLS rule that combines the remote address, the port range, the TTLS group action, and the TTLS environment action.

For the current example, this rule looks similar to the following:

TTLSRule                     StunnelDWP1Sim148
{
       REMOTEPORTRANGE                   443            
       REMOTEADDR                        9.30.198.104
       Direction                         Outbound
       TTLSGroupActionRef                StunnelGroup
       TTLSEnvironmentActionRef          StunnelClientEnvironment
}

Activate the changed AT-TLS policy by refreshing the Policy Agent with the following TSO command:
```
F PAGENT,REFRESH
```