DRAFT - NOT FOR PUBLICATION
Setting up AT-TLS for Tivoli Management Services on
z/OS components
To protect your data, you should encrypt all communication channels that are used by Tivoli Management
Services on z/OS components. You can use Application Transparent Transport Layer Security (AT-TLS) to
achieve secure communication.
Setting up AT-TLS for use with Tivoli Management Services on z/OS components is required if you plan
to use HTTPS for communication between the Tivoli Enterprise Monitoring Server (TEMS) and other
components, such as the SOAP server, the IBM Tivoli Monitoring Service Console, the tacmd CLI, and
TEMS REST services.
Note: This section assumes that general AT-TLS setup has been implemented at your site. For more
information about AT-TLS, see Application Transparent Transport Layer Security data protection.
To update AT-TLS to enable secure connections for Tivoli Management Services on z/OS components,
complete the following steps:
1. “Create digital certificates and key ring using RACF” on page 1.
2. “Define AT-TLS policy rules” on page 3.
Note: The examples that are provided are intended as a guide; you can organize your certificates and AT-
TLS rules differently, depending on the requirements of your site.
Create digital certificates and key ring using RACF
Create the certificates and key ring for use with AT-TLS to secure communication between Tivoli
Management Services on z/OS components.
Before you begin
Certificates are used for authentication. You can use RACF for handling certificates for secure
communications, as described in this topic.
Tip: You can also generate certificates outside of z/OS according to your organization policy and then
import the certificates to RACF or Integrated Cryptographic Service Facility (ICSF).
For other security management products, refer to your product documentation for information about
handling certificates and key rings.
Related information
• z/OS Security Server RACF Security Administrator's Guide: RACF and digital certificates. For a
sample setup that uses RACF, see Scenario 1: Secure server with a certificate signed by a certificate
authority and Scenario 2: Secure server with a locally signed certificate.
• z/OS Planning for Multilevel Security and the Common Criteria: Authentication via client digital
certificates
About this task
The following requirements apply when setting up your certificates and key ring for use with AT-TLS to
secure communications between Tivoli Management Services on z/OS components:
• Generate certificates.
• Create the key ring that will be used in the AT-TLS rules, and add the OMEGAMON started task user ID
as the owner.
• Add the certificate chain to the created key ring: root, intermediate, personal certificates (certificates
might vary depending from company policies).
DRAFT - NOT FOR PUBLICATION
The following procedure provides example RACF commands to perform these steps. In the example,
ITMUSER is the z/OS user ID under which the OMEGAMON started tasks run, and ITMkeyring is the
name of the key ring.
Note: The examples are intended as a guide; you can organize your certificates differently, depending on
the requirements of your site.
Procedure
1. Enter the following RACF command to add user authority for the RACF RACDCERT command. In this
example, ITMUSER is the z/OS user ID under which the OMEGAMON started tasks run.
SETROPTS CLASSACT(DIGTCERT DIGTRING)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ACCESS(CONTROL) ID(ITMUSER)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(ITMUSER)
SETROPTS RACLIST (DIGTRING) REFRESH
SETROPTS RACLIST (DIGTCERT) REFRESH
SETROPTS RACLIST (FACILITY) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
Tip: Permits to IRR.DIGTCERT profiles in FACILITY class is one way to grant key ring access
permission. Another way, which is more precise, is to create a profile and grant permission to it in the
RDATALIB class. Access control to profiles is required only in some cases (for example, if the SITE
certificate is used in the key ring as PERSONAL). For more information, see RACF authorization and
Usage notes.
2. Enter the following RACF command to generate a certificate authority (CA) certificate:
RACDCERT CERTAUTH
GENCERT
SUBJECTSDN(OU('<sysname>CA')
O('IBM')
L('Raleigh')
SP('NC')
C('US'))
NOTAFTER(DATE(2030-12-31))
WITHLABEL('<SYSNAME>CA')
KEYUSAGE(CERTSIGN)
3. Enter the following RACF command to generate a site certificate:
RACDCERT ID(ITMUSER)
GENCERT
SUBJECTSDN(CN('sysname.tivlab.raleigh.ibm.com')
OU('<SYSNAME>')
O('IBM')
L('Raleigh')
SP('NC')
C('US'))
NOTAFTER(DATE(2030-12-31))
WITHLABEL('<SYSNAME>Certificate')
SIGNWITH(CERTAUTH LABEL('<SYSNAME>CA'))
4. Enter the following RACF commands to define the key ring, store the certificate, and activate your
changes. In this example, ITMkeyring is the name of the key ring.
RACDCERT ID(ITMUSER)
ADDRING(ITMkeyring)
RACDCERT ID(ITMUSER)
CONNECT(CERTAUTH LABEL('<SYSNAME>CA')
RING(ITMkeyring))
RACDCERT ID(ITMUSER)
CONNECT(ID(ITMUSER)
LABEL('<SYSNAME>Certificate')
RING(ITMkeyring) DEFAULT)
2 Setting up AT-TLS for Tivoli Management Services on z/OS components
DRAFT - NOT FOR PUBLICATION
SETROPTS REFRESH RACLIST(STARTED)
5. For a configuration with multiple systems where the remote TEMS and hub TEMS run on different
LPARs, the CA certificate must be exported and saved in a data set. You must add the CA certificate to
the key ring for remote clients.
RACDCERT CERTAUTH
EXPORT(LABEL('<sysname>CA'))
DSN('<output-data-set-name>')
What to do next
“Define AT-TLS policy rules” on page 3
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 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:
• Ensure that the basic setup for the Policy Agent is done. For information about policy-based networking
and data protection, see z/OS Communications Server: IP Configuration Reference.
• To enable AT-TLS and encrypted communication between your Tivoli Management Services on z/OS
components, you require a certificate and key ring. For more information, see “Create digital certificates
and key ring using RACF” on page 1.
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
About this task
Review the following requirements for defining AT-TLS rules for secure communication between your
Tivoli Management Services on z/OS components:
• 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
Note: Because all Tivoli Management Services on z/OS components can send data, all components can
be both servers and clients.
• Rules need to be bound on the Jobname parameter by mask for the OMEGAMON started tasks;
the mask in the example is OMEG*. OMEGAMON uses ephemeral ports for inbound and outbound
connections so rules cannot be bound on port or port range.
• Both inbound and outbound rules should have the ApplicationControlled parameter enabled.
Tip: 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. This configuration is
helpful during migration to a secure protocol.
The following AT-TLS policy properties are set in this task, as follows:
Setting up AT-TLS for Tivoli Management Services on z/OS components 3
DRAFT - NOT FOR PUBLICATION
TTLSRule: Jobname
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
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. 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.
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.
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.
1. Define the rule and corresponding environment action statements 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
}
Figure 1. Sample AT-TLS rule and environment action for the server
4 Setting up AT-TLS for Tivoli Management Services on z/OS components
DRAFT - NOT FOR PUBLICATION
2. Define the rule and corresponding environment action statements for the 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
}
Figure 2. Sample AT-TLS rule and environment action for client systems
3. Create the group action statement.
TTLSGroupAction KDEBEGRPACT
{
TTLSEnabled On
TRACE 2
}
Figure 3. Sample AT-TLS group action
4. Create the environment action advanced parameters.
TTLSEnvironmentAdvancedParms KDEBEADV
{
ApplicationControlled On
TLSv1 Off
TLSv1.1 Off
TLSv1.2 On
TLSv1.3 On
}
Figure 4. Sample AT-TLS environment action advanced parameters
Setting up AT-TLS for Tivoli Management Services on z/OS components 5
DRAFT - NOT FOR PUBLICATION
5. Create the list of cipher suites.
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
}
Figure 5. Sample AT-TLS environment cipher specifications
Note: Make sure to review the list of cipher suites to match up-to-date security recommendations.
6. 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.
6 Setting up AT-TLS for Tivoli Management Services on z/OS components
