Start of changeSetting up secure communication for the Distributed Data ServerEnd of change

This topic describes how to enable secure communication with the DDS using Application Transparent - Transport Layer Security (AT-TLS).

Note: Using AT-TLS to secure communication with the DDS affects all DDS clients. If AT-TLS is used to enable secure communication with the DDS, all DDS clients, for example, the RMF CIM provider, have to use secure communication with the DDS. Unsecure communication with the DDS is no longer possible and will fail.

Before you can start with the DDS setup, you must enable the Policy Agent for AT-TLS. Information about setting up AT-TLS communication is provided in z/OS Communications Server: IP Configuration Guide.

For information about policies, see

The example in Figure 1 uses a RACF® key ring. The key ring must contain a valid default certificate, otherwise the certificate label to be used must be specified using the TTLSEnvironmentAdvancedParms ServerCertificateLabel. The DDS server started task user ID (e.g. GPMSERVE) must have access to the key ring. Consider using a certificate from a trusted Certificate Authority (CA), since this may be required by RMF DDS Clients.

After you have completed your Policy Agent configuration, use the REFRESH command to refresh the Policy Agent configuration: 
MODIFY PAGENT,REFRESH

For more information, see z/OS Security Server RACF Security Administrator's Guide. For other security management products, refer to your security product documentation.

RMF Distributed Data Server AT-TLS rule

The following example shows a rule that enables secure communication with the DDS.

Figure 1. Sample Policy Agent policy for secure communication setup for the DDS
# RMF Distributed Data Server Rule 
TTLSRule                          DDSServerRule        
{                                                      
  LocalPortRange                  8803                 
  Jobname                         GPMSERVE             
  Direction                       Inbound              
  Priority                        1                    
  TTLSGroupActionRef              DDSServerGRP         
  TTLSEnvironmentActionRef        DDSServerENV         
}                                                      
TTLSGroupAction                   DDSServerGRP         
{                                                      
  TTLSEnabled                     On    
  Trace                           1       	
}                                                      
TTLSEnvironmentAction             DDSServerENV         
{                                                      
  HandshakeRole                   Server               
  TTLSKeyringParms                                     
  {                                                    
     Keyring                      DDSServerKeyring     
  }                                                    
  TTLSEnvironmentAdvancedParms                         
  {                                                    
     ServerCertificateLabel       RMFDDS               
     SSLv2                        Off                  
     SSLv3                        Off                  
     TLSv1                        Off                  
     TLSv1.1                      Off                  
     TLSv1.2                      On                   
  }
}
TTLSRule: Jobname
The name value specifies the job name of the application. GPMSERVE is the job name of the DDS.
TTLSRule: LocalPortRange
The local port the application is bound to for this rule's action to be performed. 8803 is the default HTTP Port of the DDS.
TTLSRule: Direction
Specifies the direction the connection must be initiated from for this rule's action to be performed. In this example, Inbound is specified, which means that the rule applies to connection requests that arrive to the local host.
TTLSRule: Priority
An integer value in the range 1 - 2000000000 that represents the priority associated with the rule. The highest priority value is 2000000000.

When using multiple rules for the DDS server, the more specific the rule, the higher its priority should be. Generic rules without detailed specifications of the incoming connections should have a low priority.

TTLSEnvironmentAction: HandshakeRole
Specifies the SSL handshake role to be taken for connections in this AT-TLS environment. In this example, Server is specified which means that the SSL handshake is performed as a sever.
TTLSKeyringParms: Keyring
Specifies the z/OS® UNIX path and file name of the key database file, the ring name of the SAF key ring, or the name of the z/OS PKCS #11 token. In this example, the RACF key ring DDSServerKeyring is specified.
TTLSEnvironmentAdvancedParms: ServerCertificateLabel
Specifies the label of the certificate for a server application to authenticate the server. In this example, the DDS server certificate with the label RMFDDS is used.
TTLSEnvironmentAdvancedParms: SSLv2
Specifies the state of the SSL Version 2 protocol. In this example, Off is specified, which means that the SSL Version 2 protocol is disabled.
TTLSEnvironmentAdvancedParms: SSLv3
Specifies the state of the SSL Version 3 protocol. In this example, Off is specified, which means that the SSL Version 3 protocol is disabled.
TTLSEnvironmentAdvancedParms: TLSv1
Specifies the state of the TLS Version 1 protocol. In this example, Off is specified, which means that the TLS Version 1 protocol is disabled.
TTLSEnvironmentAdvancedParms: TLSv1.1
Specifies the state of the TLS Version 1.1 protocol. In this example, Off is specified, which means that the TLS Version 1.1 protocol is disabled.
TTLSEnvironmentAdvancedParms: TLSv1.2
Specifies the state of the TLS Version 1.2 protocol. In this example, On is specified, which means that the TLS Version 1.2 protocol is enabled.

AT-TLS rule for clients, using secure communication with the RMF Distributed Data Server

The following example shows a rule to enable a client running on z/OS to establish secure communication with the DDS. The RACF key ring DDSClientKeyring must contain the server certificate that is used by the RMF Distributed Data Server rule.

When using a server certificate from a trusted certificate authority (CA), the virtual RACF CA key ring *AUTH*/* can be used.

Figure 2. Sample Policy Agent rule for secure communication for DDS clients
Start of change
# RMF Distributed Data Server Client Rule
TTLSRule                          DDSClientRule
{
   RemotePortRange                8803
   RemoteAddr                     1.0.0.0
   Direction                      Outbound
   TTLSGroupActionRef             DDSClientGRP
   TTLSEnvironmentActionRef       DDSClientENV
}
TTLSGroupAction                   DDSClientGRP
{
   TTLSEnabled                    On
   Trace                          1
}
TTLSEnvironmentAction             DDSClientENV
{
   HandshakeRole                  Client
   TTLSKeyringParms
   {
      Keyring                     DDSClientKeyring
   }
   Start of changeTTLSEnvironmentAdvancedParms                         
   {                                                    
     SSLv2                        Off                  
     SSLv3                        Off                  
     TLSv1                        Off                  
     TLSv1.1                      Off                  
     TLSv1.2                      On                   
    }
End of change}
End of change
TTLSRule: RemoteAddr
The remote IP address specification that must match for this rule's action to be performed—that is, the IP address of the DDS to which the client is connecting.
TTLSRule: RemotePortRange
The remote port to which the application must be connecting for this rule's action to be performed. The default HTTP port of the DDS is 8803.
TTLSRule: Direction
Specifies the direction from which the connection must be initiated to perform this rule's action. In this example, Outbound is specified, which means that the rule applies to connection requests that are initiated by the application.
TTLSEnvironmentAction: HandshakeRole
Specifies the SSL handshake role to be taken for connections in this AT-TLS environment. In this example, Client is specified, which means that the SSL handshake is performed as a client.
TTLSKeyringParms: Keyring
Specifies the z/OS UNIX path and file name of the key database file, the ring name of the SAF key ring, or the name of the z/OS PKCS #11 token. In this example, the RACF key ring DDSClientKeyring is specified.
Start of changeTTLSEnvironmentAdvancedParms: SSLv2End of change
Start of changeSpecifies the state of the SSL Version 2 protocol. In this example, Off is specified, which means that the SSL Version 2 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: SSLv3End of change
Start of changeSpecifies the state of the SSL Version 3 protocol. In this example, Off is specified, which means that the SSL Version 3 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1End of change
Start of changeSpecifies the state of the TLS Version 1 protocol. In this example, Off is specified, which means that the TLS Version 1 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1.1End of change
Start of changeSpecifies the state of the TLS Version 1.1 protocol. In this example, Off is specified, which means that the TLS Version 1.1 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1.2End of change
Start of changeSpecifies the state of the TLS Version 1.2 protocol. In this example, On is specified, which means that the TLS Version 1.2 protocol is enabled.End of change

RMF Distributed Data Server AT-TLS rule with client certificate authentication

The DDS supports the communication scenario in which a client authenticates itself via a client certificate that is associated with a RACF user ID. No user ID/password authentication is performed in this case. To enable this communication mode, the CLIENT_CERT(ACCEPT) option must be set in the DDS parmlib member.

The following example shows a rule that uses a RACF key ring. The RACF key ring DDSServerKeyring must contain the server certificate that is used by the rule. The server certificate must either be the default certificate, or the certificate label to be used must be specified using the TTLSEnvironmentAdvancedParms ServerCertificateLabel. The DDS server started task user ID (for instance, GPMSERVE) must have access to the key ring. Consider using a certificate from a trusted certificate authority (CA), since this may be required by RMF DDS clients.

The DDSServerKeyring must also contain the client certificate associated with a RACF user ID. If your access to Monitor III data is protected by RACF resource profile ERBSDS.MON3DATA, the associated user ID must have READ access.

For more information, see z/OS Security Server RACF Security Administrator's Guide.

Figure 3. Sample Policy Agent rule for secure communication with client certificate authentication for the DDS
Start of change
# RMF Distributed Data Server Rule
TTLSRule                          DDSServerClientCertRule
{
   LocalPortRange                 8803
   Jobname                        GPMSERVE
   RemoteAddr                     1.0.0.0
   Direction                      Inbound
   TTLSGroupActionRef             DDSServerClientCertGRP
   TTLSEnvironmentActionRef       DDSServerClientCertENV
   Priority                       2
}
TTLSGroupAction                   DDSServerClientCertGRP
{
   TTLSEnabled                    On
   Trace                          1
}
TTLSEnvironmentAction             DDSServerClientCertENV
{
   HandshakeRole                  ServerWithClientAuth
   TTLSKeyringParms 
   {
      Keyring                     DDSServerKeyring
   }
   TTLSEnvironmentAdvancedParms             
   {                                        
      ClientAuthType              SAFCheck
      ServerCertificateLabel      RMFDDS
      SSLv2                        Off                  
      SSLv3                        Off                  
      TLSv1                        Off                  
      TLSv1.1                      Off                  
      TLSv1.2                      On  
   }
}
End of change
TTLSRule: Jobname
The name value specifies the job name of the application. GPMSERVE is the job name of the DDS.
TTLSRule: LocalPortRange
The local port to which the application is bound for this rule's action to be performed. The default HTTP port of the DDS is 8803.
TTLSRule: RemoteAddr
The remote IP address specification that must match for this rule's action to be performed. You can use this option to specify that this rule applies only to a subset of client connections, where the clients are running on a specific system. When using multiple rules for the DDS server, be sure to use the TTLSRule Priority setting.
TTLSRule: Priority
An integer value in the range 1 - 2000000000 that represent the priority associated with the rule. The highest priority value is 2000000000.

When using multiple rules for the DDS server, the more specific a rule, the higher its priority should be.

TTLSRule: Direction
Specifies the direction from which the connection must be initiated for this rule's action to be performed. In this example, Inbound is specified, which means that the rule applies to connection requests that arrive at the local host.
TTLSEnvironmentAction: HandshakeRole
Specifies the SSL handshake role to be taken for connections in this AT-TLS environment. In this example, ServerWithClientAuth is specified, which means that the SSL handshake is performed as a sever, and a client certificate is required.
TTLSKeyringParms: Keyring
Specifies the z/OS UNIX path and file name of the key database file, the ring name of the SAF key ring, or the name of the z/OS PKCS #11 token. In this example, the RACF key ring DDSServerKeyring is specified.
TTLSEnvironmentAdvancedParms: ClientAuthType
Specifies the type of client certificate validation to be performed for connections in this AT-TLS environment. Client certificates are requested only if HandshakeRole is set to ServerWithClientAuth. That option needs to be set to SAFCheck, which requires the client to present a certificate, to perform a client certificate validation and to have a client certificate which is associated with an user ID defined to the security product. If the option is not set to SAFCheck, the DDS will not use client certificate authentication.
TTLSEnvironmentAdvancedParms: ServerCertificateLabel
Specifies the label of the certificate for a server application to authenticate the server. In this example, the DDS Server certificate with the label RMFDDS is used.
Start of changeTTLSEnvironmentAdvancedParms: SSLv2End of change
Start of changeSpecifies the state of the SSL Version 2 protocol. In this example, Off is specified, which means that the SSL Version 2 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: SSLv3End of change
Start of changeSpecifies the state of the SSL Version 3 protocol. In this example, Off is specified, which means that the SSL Version 3 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1End of change
Start of changeSpecifies the state of the TLS Version 1 protocol. In this example, Off is specified, which means that the TLS Version 1 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1.1End of change
Start of changeSpecifies the state of the TLS Version 1.1 protocol. In this example, Off is specified, which means that the TLS Version 1.1 protocol is disabled.End of change
Start of changeTTLSEnvironmentAdvancedParms: TLSv1.2End of change
Start of changeSpecifies the state of the TLS Version 1.2 protocol. In this example, On is specified, which means that the TLS Version 1.2 protocol is enabled.End of change

AT-TLS for clients, using secure client certificate authentication with the RMF Distributed Data Server

The following example shows a rule to enable a client running on z/OS to establish secure communication to the DDS with client certificate authentication. No user ID/password authentication is performed. The RACF key ring DDSClientKeyring must contain the server certificate used by the RMF Distributed Data Server rule and the client certificate. The client certificate must either be the default certificate, or the certificate label to be used must be specified using the TTLSEnvironmentAdvancedParms CertificateLabel. Also, the client certificate must be associated with a RACF user ID. If your access to Monitor III data is protected via RACF resource profile ERBSDS.MON3DATA, the associated user ID must have READ access.

Figure 4. Sample Policy Agent rule for secure communication for DDS clients with client certificate authentication
# RMF Distributed Data Server Client Rule for Client Certificate Authentication
TTLSRule                           DDSClientCertRule
{
   RemotePortRange                 8803
   RemoteAddr                      1.0.0.0
   Direction                       Outbound
   TTLSGroupActionRef              DDSClientCertGRP
   TTLSEnvironmentActionRef        DDSClientCertENV
}
TTLSGroupAction                    DDSClientCertGRP
{
   TTLSEnabled                     On
   Trace                           1
}
TTLSEnvironmentAction              DDSClientCertENV
{
   HandshakeRole                   Client
   TTLSKeyringParms
   {
      Keyring                      DDSClientKeyring
   }
   TTLSEnvironmentAdvancedParms 
   {
      CertificateLabel             RMFDDSCLIENT
   }
}
TTLSRule: RemotePortRange
The remote port to which the application must be connecting for this rule's action to be performed. The default HTTP port of the DDS is 8803.
TTLSRule: RemoteAddr
The remote IP address specification that must match for this rule's action to be performed—that is, the IP address of the DDS to which the client is connecting.
TTLSRule: Direction
Specifies the direction from which the connection must be initiated for this rule's action to be performed. In this example, Outbound is specified, which means that the rule applies to connection requests that are initiated by the application.
TTLSEnvironmentAction: HandshakeRole
Specifies the SSL handshake role to be taken for connections in this AT-TLS environment. In this example, Client is specified, which means that the SSL handshake is performed as a client.
TTLSKeyringParms: Keyring
Specifies the z/OS UNIX path and file name of the key database file, the ring name of the SAF key ring, or the name of the z/OS PKCS #11 token. In this example, the RACF key ring DDSClientKeyring is specified.
TTLSEnvironmentAdvancedParms: CertificateLabel
Specifies the label of the certificate to be used for authentication. In this example, the DDS client certificate with the label RMFDDSCLIENT is used.