Define AT-TLS policy rules

Update the AT-TLS policy with rules to secure communication between Tivoli Management Services on z/OS components.

Before you begin

The AT-TLS policy describes the AT-TLS rules. The location of the AT-TLS policy is specified in the Policy Agent configuration file.

The information in this topic provides guidance and recommendations on what is needed in the AT-TLS rules for securing communication between your Tivoli Management Services on z/OS components. Complete setup and management of AT-TLS rules requires additional RACF and IBM z/OS Communication Server administration, as follows:

Ensure that the basic setup for Policy Agent is done. For information about policy-based networking and data protection, see z/OS Communications Server: IP Configuration Reference.
Enablement of AT-TLS and encrypted communication between your Tivoli Management Services on z/OS components requires a certificate and key ring. For more information, see Create digital certificates and key ring using RACF.

Related information:

z/OS Communications Server: IP Configuration Guide: Application Transparent Transport Layer Security data protection
z/OS Communications Server: IP Configuration Guide: AT-TLS policy configuration
z/OS Communications Server: IP Configuration Guide: Getting started with AT-TLS
z/OS Communications Server: IP Configuration Reference: AT-TLS policy statements
z/OS Communications Server: IP Configuration Reference: TTLSRule statement

About this task

Review the following requirements for defining AT-TLS rules for secure communication between your Tivoli Management Services on z/OS components:

You must define a rule (and corresponding environment action statements) for both the server and the client. In an OMEGAMON environment, all Tivoli Management Services on z/OS components can act as both the server and the client, depending on the nature of request. The following rules are required:
- For server: Rule for inbound connection with HandshakeRole as Server
- For client: Rule for outbound connection with HandshakeRole as Client
Important: Because all Tivoli Management Services on z/OS components can send data, all components can be both server and client.
Rules must include the Jobname parameter set to the mask for the OMEGAMON started tasks; the mask is OMEG* in the example later in this topic. If needed, you can narrow the scope of a rule by including additional criteria, such as rule parameters that specify IP address or port range. For details about available rule parameters, see TTLSRule statement.
Note: Limiting your rule by port or port range requires the use of the POOL and EPHEMERAL:Y modifiers when configuring the ports in your runtime environment.

Important: Depending on the components installed at your site, new rules created for Tivoli Management Services on z/OS components might overlap with your existing rules. If you encounter overlapping rules, you can create one or more additional rules that are more specific to bypass the conflict. It is recommended that you code the specific rules preceding the general rules so that the specific rules have higher priority and are applied before the general rules. It is possible that you might need to modify your runtime environment (for example, changing port number assignments) to satisfy the implementation of new AT-TLS rules.
Both inbound and outbound rules should have the ApplicationControlled parameter enabled.
Tip: This setting allows you to use secure protocols (for example, IP.SPIPE and HTTPS) at the same time as protocols that are not secure (for example, IP.PIPE and HTTP) in the same environment. This configuration is helpful during migration to a secure protocol.

The following AT-TLS policy properties are set in this task, as follows:

TTLSRule: Jobname

(Required) Specifies the mask for the OMEGAMON started tasks. This value is OMEG* in the example, which is the started task prefix set in Configuration Manager.

TTLSRule: Direction

(Required) Specifies the direction from which a connection must be initiated for this action to be performed.

Inbound means that the rule applies to connection requests that arrive inbound to the local host. An application must issue an accept request to service this connection.
Outbound means that the rule applies to connection requests that are issued from the local host. An application must issue a connect request to initiate a connection.

TTLSRule: Priority

Specifies the optional priority setting. Priority setting is required when more than one rule can match a specific connection. In this example, the priority for the server rule is 10 and the priority for the client rule is 20; the client rule has the higher priority.

TTLSEnvironmentAction: HandshakeRole

Specifies the SSL handshake role to be taken for connections in this AT-TLS environment. Valid values are:

Client: Perform the SSL handshake as a client.
Server: Perform the SSL handshake as a server.
ServerWithClientAuth: Perform the SSL handshake as a server requiring client authentication. With this setting, you can indicate the type of client certificate validation to be performed using the TTLSEnvironmentAdvancedParms:ClientAuthType parameter.

TTLSKeyringParms: Keyring

Specifies the key ring name, which is ITMkeyring in the example.

TTLSEnvironmentAdvancedParms: ApplicationControlled

Enablement of this setting allows you to use secure protocols (like IP.SPIPE and HTTPS) at the same time as protocols that are not secure (like IP.PIPE and HTTP) in the same environment.

Note: This configuration is helpful during migration to a secure protocol.

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. Valid values are:

PassThru: Bypasses client certificate validation.
Full: Performs client certificate validation if the client presents a certificate.
Required: Requires the client to present a certificate and performs client certificate validation. This is the default.
SAFCheck: Requires the client to present a certificate, performs client certificate validation and requires the client certificate to have an associated user ID defined to the security product.

TTLSCipherParms

Defines the cipher specifications. Make sure to review the list of cipher suites to match up-to-date security recommendations.

Requirement: AES-GCM ciphers require the Integrated Cryptographic Services Facility (ICSF) to be active. The user ID running the AT-TLS application must have READ access to the following resources in the RACF CSFSERV class:

CSF1TRC
CSF1SKD
CSF1SKE
CSF1TRD

For more information, see z/OS Communications Server: IP Configuration Reference: TTLSCipherParms statement and z/OS Cryptographic Services System SSL Programming: RACF CSFSERV resource requirements.

Use the following procedure to define your AT-TLS rules to establish secure communications between the Tivoli Management Services on z/OS components.

Note: The examples are intended as a guide; you can organize your AT-TLS rules differently, depending on the requirements of your site.

Procedure

Add statements to the AT-TLS policy file, as shown in the following policy examples. All rules, actions, parameters, and attributes described in this step are required.

Define the rule and corresponding environment action statements for the server.

Figure 1. Sample AT-TLS rule and environment action for the server


TTLSRule                          KDEBEIN
{
  Jobname                         OMEG*
  Direction                       Inbound
  Priority                        10
  TTLSGroupActionRef              KDEBEGRPACT
  TTLSEnvironmentActionRef        KDEBEENVIN
}

TTLSEnvironmentAction             KDEBEENVIN
{
  HandshakeRole                   Server
  TTLSKeyringParms
  {
    Keyring                       ITMkeyring
  }
  TTLSCipherParmsRef              KDEBECPRM
  TTLSEnvironmentAdvancedParmsRef KDEBEADV
}

Tip: For TTLSEnvironmentAction:HandshakeRole, you can specify ServerWithClientAuth, which indicates that client authentication is required.

Define the rule and corresponding environment action statements for the client.

Figure 2. Sample AT-TLS rule and environment action for client systems


TTLSRule                          KDEBEOUT
{
  Jobname                         OMEG*
  Direction                       Outbound
  Priority                        20
  TTLSGroupActionRef              KDEBEGRPACT
  TTLSEnvironmentActionRef        KDEBEENVOUT
}
TTLSEnvironmentAction             KDEBEENVOUT
{
  HandshakeRole                   Client
  TTLSKeyringParms
  {
    Keyring                       ITMkeyring
  }
  TTLSCipherParmsRef              KDEBECPRM
  TTLSEnvironmentAdvancedParmsRef KDEBEADV
}

Create the group action statement.

Figure 3. Sample AT-TLS group action


TTLSGroupAction                   KDEBEGRPACT
{
  TTLSEnabled                     On
  TRACE                           2
}

Create the environment action advanced parameters.
Figure 4. Sample AT-TLS environment action advanced parameters
```
TTLSEnvironmentAdvancedParms      KDEBEADV
{
  ApplicationControlled           On
  TLSv1                           Off
  TLSv1.1                         Off
  TLSv1.2                         On
  TLSv1.3                         On
}
```
Tip: If you set TTLSEnvironmentAction:HandshakeRole to ServerWithClientAuth, you can specify TTLSEnvironmentAdvancedParms:ClientAuthType to indicate the type of client certificate validation to be performed.

Create the list of cipher suites.

Figure 5. Sample AT-TLS environment cipher specifications

TTLSCipherParms                   KDEBECPRM
{
  V3CipherSuites TLS_AES_128_GCM_SHA256
  V3CipherSuites TLS_AES_256_GCM_SHA384
  V3CipherSuites TLS_CHACHA20_POLY1305_SHA256
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  V3CipherSuites TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  V3CipherSuites TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
}

Refresh the Policy Agent to have your changes take effect. You can refresh the Policy Agent by issuing the MODIFY PAGENT,REFRESH command from the console.