Example: Configuring AT-TLS for secure communication
This topic shows
the exemplary setup of the Policy Agent to secure communication for
the CIM server.
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.
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 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.
|