Enabling secure communication between z/OS Debugger and the remote debugger for incoming debug sessions

This section assists you in setting up a secure communication by using the z/OS® Communications Server: IP Application Transparent – Transport Layer Security (AT-TLS) service when you use the TCPIP suboption in the TEST runtime option. By exploiting the Secure Sockets Layer (SSL) functions of AT-TLS, z/OS Debugger provides a secure (encrypted) communication with the remote Eclipse debugger.

The setup assumes that the remote debugger is the TCP/IP server and z/OS Debugger is the TCP/IP client.

Carry out the following steps:

Add a client certificate.
Export a copy of a client certificate from the keystore that the remote debugger uses. This client certificate is used by AT-TLS to authenticate the TCP/IP server (remote debugger) during SSL handshaking. If the remote debugger does not have a certificate, you can use the following Java™ runtime utility to create a keystore and certificate and to export a client certificate.

Create a keystore and certificate

keytool -genkey

Export a client certificate

keytool -export

Note: Refer to the appropriate Java documentation for the full set of parameters required for the keytool command.
Each Eclipse IDE user must configure the debug daemon to start on a secured port with the location and password of the keystore created previously. These settings can be found on Preferences > Run/Debug > Debug Daemon preference page. For more information, see Debug Daemon preferences.
Upload the certificate to z/OS in binary mode and store it as a SITE or CERTAUTH certificate in RACF® or other equivalent security facility. The following examples use the RACDCERT command to add a certificate:
```
RACDCERT SITE
ADD(’USERID1.DTPDT.CERT1’) WITHLABEL(’DTPDT-CERT1’) TRUST

RACDCERT CERTAUTH
ADD(’USERID1.DTPDT.CERT1’) WITHLABEL(’DTPDT-CERT1’) TRUST  
```
where USERID1.DTPDT.CERT1 is a file that contains the uploaded certificate and DTPDT-CERT1 is a label of the certificate in RACF.
The following information is used in the previous examples:

USERID1.DTPDT.CERT1

A file that contains the uploaded certificate.

DTPDT-CERT1

A label of the certificate in RACF.

Note: Both SITE and CERTAUTH certificates work with the key ring *SITE*/* parameter in TTLSKeyRingParms definition below. If you use a CERTAUTH certificate, also define the *AUTH*/* parameter.

Add an AT-TLS rule.

The rule allows AT-TLS to enable SSL when z/OS Debugger connects to the remote debugger on a specified port. The following example shows that the remote debugger listens to the secure port 9101. In your development environment, you must determine which secure port the remote debugger listens to and use it in the RemotePortRange statement.

 TTLSRule DTPDTRL1                            
{                                            
 RemotePortRange 9101                       <=== secure port                        
 Direction Outbound                         <=== outbound direction    
 TTLSGroupActionRef DTPDTRL1GrpAct             
 TTLSEnvironmentActionRef DTPDTRL1EnvAct       
}                                            
TTLSGroupAction DTPDTRL1GrpAct                 
{                                            
 TTLSEnabled On                             <=== enable rule 
 Trace 30                                    
}                                            
TTLSEnvironmentAction DTPDTRL1EnvAct           
{                                            
 TTLSKeyRingParms                            
 {                                           
  Keyring *SITE*/*                          <=== virtual key ring 
 }                                           
 HandShakeRole Client                        
}

AT-TLS currency

A TLS v1.2 protocol is available that uses more secured algorithms during SSL handshake operations. To use the protocol, take the following steps.

For z/OS Version 1 Release 13

Two APARs OA39422 and PM62905 are required to enable TLS v1.2 in z/OS v1.13.
AT-TLS rule update. The following code is an example for secure port 9102:

TTLSRule DTPDTRL2                              
{                                              
 RemotePortRange 9102                          
 Direction Outbound                            
 TTLSGroupActionRef DTPDT2GrpAct               
 TTLSEnvironmentActionRef DTPDT2EnvAct         
}                                              
TTLSGroupAction DTPDT2GrpAct                   
{                                              
 TTLSEnabled On                                
 Trace 30                                      
 TTLSGroupAdvancedParms                        
 {                                             
  Envfile /etc/pagent/DTPDT2grp.env <== DTPDT2grp.env contains GSK_PROTOCOL_TLSV1_2=ON
 }                                  <== system SSL environment variable.
}                                              
TTLSEnvironmentAction DTPDT2EnvAct             
{                                              
 TTLSKeyRingParms                              
 {                                             
  Keyring *SITE*/*                             
 }                                             
 HandShakeRole Client
}

For z/OS Version 2 Release 1

TLS v1.2 support is included in z/OS v2.1 base.
AT-TLS rule update. The following code is an example for secure port 9102:

TTLSRule DTPDTRL2                              
{                                              
 RemotePortRange 9102                          
 Direction Outbound                            
 TTLSGroupActionRef DTPDT2GrpAct               
 TTLSEnvironmentActionRef DTPDT2EnvAct         
}                                              
TTLSGroupAction DTPDT2GrpAct                   
{                                              
 TTLSEnabled On                                
 Trace 30                                      
}                                              
TTLSEnvironmentAction DTPDT2EnvAct             
{                                              
 TTLSKeyRingParms                              
 {                                             
  Keyring *SITE*/*                             
 }                                             
 HandShakeRole Client
 TTLSEnvironmentAdvancedParms
 {
  TLSv1.2 On 
 }
}