Example: Configuring AT-TLS for secure communication

This topic shows the exemplary setup of the Policy Agent to secure communication for the CIM server.

• SSL protection only (see Prerequisite: Common certificate setup and SSL protection only)
• SSL protection including certificate based authentication (see Prerequisite: Common certificate setup and SSL protection including certificate based authentication)
• SSL protected indication delivery (see Prerequisite: Common certificate setup and SSL protected indication delivery)

For a more detailed explanation about Policy Agent AT-TLS policy see z/OS Communications Server: IP Configuration Guide about Policy Agent and policy applications and Application Transparent Transport Layer Security (AT-TLS) policy statements.

Prerequisite: Common certificate setup

To enable AT-TLS to secure the communication, a valid server certificate, the associated server private key, and the certificate of trusted Certificate Authority's (CA) are needed. These examples are using a key ring named CFZCIMServerRing to store these credentials. This key ring must be accessible by the CIM server user ID (e.g. CFZSRV), and the server certificate must be the default certificate.

For a sample setup with RACF®, see z/OS Security Server RACF Security Administrator’s Guide about RACF and digital certificates, implementation scenario 1 or 2. For handling certificates and key rings, please refer to the documentation of your SAF product.

SSL protection only

Simple SSL protection means that the communication between the client and the server is encrypted without having established a trust relationship between the client and the server. So the client still needs to send a user ID and a password for authentication.

To set up AT-TLS with simple SSL protection for the CIM server, a policy for the Communications Server Policy Agent has to be created that restricts AT-TLS to the CIM server port 5989 and to inbound TCP/IP communication.

Sample Policy Agent policy for a simple SSL protection:

Example

TTLSRule              CFZCIMServerRuleInbound
{
   Jobname                  CFZCIM*
   LocalPortRange           5989
   Direction                Inbound
   TTLSGroupActionRef       grp_StartUp
   TTLSEnvironmentActionRef CFZCIMServerEnvActionInbound
}

TTLSEnvironmentAction CFZCIMServerEnvActionInbound
{
  HandshakeRole     Server
  TTLSEnvironmentAdvancedParms
  {
     ClientAuthType    PassThru
  }
  TTLSKeyRingParms
  {
     Keyring           CFZCIMServerRing
  }
}

# Common StartUp Group that new Rules may use
# Shows how each connection maps to policy
TTLSGroupAction grp_StartUp
{
 TTLSEnabled On
 Trace 0             # Log Errors and Info messages to syslogd
}

CIM server specific notes to the AT-TLS Policy parameters:

TTLSRule: Jobname

Jobname identifies where this rule applies. In the example, it is the started task job name. If you set up the connection this way, the configuration does not influence other parts of the system.

TTLSRule: LocalPortRange

This property must match the HTTPS port definition of the CIM server.

SSL protection including certificate based authentication

Since the CIM server is aware of AT-TLS, you can use SSL secured communications and certificates based authentication between the CIM client and the CIM server. The CIM server queries AT-TLS if the client is identified by a client certificate and mapped to a local user ID.

Authentication based on SSL certificates means:

• the communication between the client and the server is encrypted,
• the trust relationship is established, and
• the client certificate is matched to a local z/OS user ID.

No user ID and password have to be provided by the client. All subsequent authorization checking is done with the mapped user ID.

The CIM client sends an SSL certificate to AT-TLS, AT-TLS sends the certificate to RACF and RACF associates the certificate to the appropriate user ID, which then can access the CIM server. Vice versa, the CIM server returns its responses to client requests using SSL certificates.

This method of authentication provides more security than sending user IDs and passwords between client and server.

If you want to use this enhanced method based on certificates, you must create the inbound/outbound rules as follows:

• Note:

  It is important to understand that it will not be sufficient to configure AT-TLS for SSL encryption for the communication. You also must configure the CIM server's HTTPS port.

  To set up AT-TLS with authentication based on SSL certificates for the CIM server, a policy for the Communications Server Policy Agent has to be created that restricts AT-TLS to the CIM server port 5989 and to inbound TCP/IP communication. Also the SAF facility has to be set up to match certificate subjects to local z/OS® user IDs.

  For setting up the SAF facility to map certificates to local user IDs, see z/OS Security Server RACF Security Administrator’s Guide about RACF and digital certificates, Certificate Name Filtering.

  Sample Policy Agent policy for authentication based on SSL certificates: 

  Example

  TTLSRule              CFZCIMServerRuleInbound
  {
     Jobname                  CFZCIM*
     LocalPortRange           5989
     Direction                Inbound
     TTLSGroupActionRef       grp_StartUp
     TTLSEnvironmentActionRef CFZCIMServerEnvActionInbound
  }
  
  TTLSEnvironmentAction CFZCIMServerEnvActionInbound
  {
    HandshakeRole             ServerWithClientAuth
    TTLSEnvironmentAdvancedParms
    {
       ClientAuthType    SAFCheck
    }
    TTLSKeyRingParms
    {
       Keyring           CFZCIMServerRing
    }
  }
  
  # Common StartUp Group that new Rules may use
  # Shows how each connection maps to policy
  TTLSGroupAction grp_StartUp
  {
   TTLSEnabled On
   Trace 0             # Log Errors and Info messages to syslogd
  }

  CIM server specific notes to the AT-TLS Policy parameters:

  TTLSRule: Jobname

  Jobname identifies where this rule applies. In this example it is the started task job name. If you set up the connection this way, the configuration does not influence other parts of the system.

  TTLSRule: LocalPortRange

  This property must match the HTTPS port definition of the CIM server.

SSL protected indication delivery

This topic shows an exemplary setup for the usage of RACF to deliver secured indications with AT-TLS.

Delivering secured indications from the CIM server to an indication listener means that the CIM server establishes an encrypted connection to deliver indications. Whether a trusted relationship is established or not depends on the listener configuration.

In case a trusted relationship is established, the CIM server is a client to the indication listener and therefore an outbound policy has to be specified with AT-TLS. To deliver secured indications, the job name of the CIM server and the port specified in the indication handler destination property must match. An indication is defined by the application programmer so there has to be an agreement between the application programmer and the system programmer that port secured indications are sent from the CIM server to the indication listeners.

Sample Policy Agent policy for the delivery of secured indications:

Example

TTLSRule              CFZCIMServerRuleOutbound
{
   Jobname                  CFZCIM*
   RemotePortGroupRef       CFZCIMServerRemotePortGroup
   Direction                Outbound
   TTLSGroupActionRef       grp_StartUp
   TTLSEnvironmentActionRef CFZCIMServerEnvActionOutbound
}

TTLSEnvironmentAction CFZCIMServerEnvActionOutbound
{
  HandshakeRole        Client
  TTLSKeyRingParms
  {
    Keyring  CFZCIMServerRing
  }
}

PortGroup     CFZCIMServerRemotePortGroup
{
   PortRange
   {
     Port 5989
   }

   PortRange
   {
     Port 6000-7000
   }
}

# Common StartUp Group that new Rules may use
# Shows how each connection maps to policy
TTLSGroupAction grp_StartUp
{
 TTLSEnabled On
 Trace 0             # Log Errors and Info messages to syslogd
}

CIM server specific notes to the AT-TLS Policy parameters:

TTLSRule: Jobname

Jobname identifies where this rule applies. In this example it is the started task job name. If you set up the connection this way, the configuration does not influence other parts of the system.

PortGroup

All indications which do have a port specified within the indication handler destination property and do match to any PortRange defined within the PortGroup are delivered secure via AT-TLS. If the destination property protocol is specified as https and no other port is specified, port 5989 will be used by the CIM server. So please ensure that always port 5989 is within a PortRange. In this example, all indications with port 5989 and port 6000-7000 are delivered in a secured way.