For IBM AD V5.1.0.7 and earlier versions, the
communication between IBM AD
Validation Service and IBM AD Connect for
Mainframe is unencrypted socket session. Beginning with
version 5.1.0.8, the optional secure communication, which uses the TLS protocol, is supported by using the AT-TLS feature of IBM
z/OS®z/OS Communication
Server.
The TLS protocol is a client or server
cryptographic protocol. It is based on the earlier Secure Sockets Layer (SSL)
specifications that are developed by Netscape Corporation for securing communications that use
Transmission Control Protocol/Internet Protocol (TCP/IP) sockets. The
TLS and SSL
protocols are designed to run at the application level. Therefore, typically, an application must be
designed and coded to use TLS/SSL protection. On z/OS, the System SSL
component of the Cryptographic Services element implements the full suite of SSL and TLS
protocols (SSL V2, SSL V3, TLS
V1.0, TLS V1.1, and TLS V1.2 as of this writing), including a robust set of
application programming interfaces (APIs) for z/OSC and C++ applications to use.
To make the TLS or SSL protocol more accessible to z/OS applications, z/OS Communications Server V1R7 introduced the AT-TLS feature. AT-TLS starts TLS or SSL primitives in the TCP layer of the
TCP/IP stack on behalf of application programs, based on policy files that
describe the application traffic and how to protect it. With AT-TLS, z/OS applications that are written in almost any language can
enjoy full TLS or SSL protection without requiring source code changes. AT-TLS allows socket applications to access encrypted sessions by invoking
system SSL within the transport layer of the TCP/IP stack.
AT-TLS policy is read, parsed, and installed into the TCP/IP stack by the z/OSCommunication Server Policy Agent (PAGENT), which implements policy-based
networking for the z/OS environment. The application
continues to send and receive clear text over the socket, but data that is sent over the network is
protected by the System SSL component. For more
information about policy-based networking, see z/OS Communications
Server V2R3: IP Configuration Guide, SC27-3650-30.
To configure IBM AD Connect for
Mainframe as a server with TLS/SSL support, perform the following steps. If you have already configured AT-TLS for other servers on your z/OS
system, begin at step 5.
PAGENT runs as a UNIX process, so it can be started either from the UNIX System Service shell or as a z/OS started task. The following example shows how to start PAGENT as a z/OS started task. You can
also find this sample file in TCPIP.SEZAINST(EZAPAGSP).Figure 1. Example: PAGENT JCL started procedure
To run with the
required configuration, you can use environment variables that are configured either in an IBM Multiple Virtual Storage (IBMMVS) data set, or in a z/OSUNIX file that is specified by the STDENV data definition
(DD). The following example shows how to configure the environment variables for PAGENT. You can also find this sample file in SYS1.TCPPARMS(PAGENTV).Figure 2. Example: SYS1.TCPPARMS(PAGENT) data set containing PAGENT environment variables
TZ=PST8PDT7
PAGENT_CONFIG_FILE=//'SYS1.TCPPARMS(PAGENTP)' == > in unix default file is /etc/pagent.conf
PAGENT_LOG_FILE=SYSLOGD == > it could be /tmp/pagent.log
TZ
Specifies the local time zone for the PAGENT process. In the preceding
example, it is set to Pacific Standard Time (GMT -8) and Pacific Daylight Saving Time (GMT -7).
PAGENT_CONFIG_FILE
Specifies the PAGENT configuration file. In the preceding example, the
PAGENT configuration file is a member of the SYS1.TCPPARMS data set. For more information about PAGENT
configuration files, see step 3.
PAGENT_LOG_FILE
Specifies the name of the log file that is used by PAGENT. In the
preceding example, it is set to log PAGENT messages into file SYSLOGD.
Before you start the PAGENT started task, make sure that the
appropriate security authorizations have been set. See the following step for details.
Define the security authorization for PAGENT.
The policies that are managed by PAGENT can affect system operation
significantly. Therefore, you must restrict the access of z/OS user IDs to PAGENT. To do this,
define certain resources and controls in the security manager product of the system, for example,
RACF. To set up the security
definitions of PAGENT to RACF, follow the steps:
Define the PAGENT started task to RACF.
To set up the PAGENT started
task to RACF, you must define a
profile to the STARTED RACF generic
resource class by using the RDEFINE command. The following example shows the RACF commands that are used to set up the
PAGENT started task. You can also find this sample file in SIAYSAMP(RACFPAG1).Figure 3. Example: RACF commands to define the PAGENT started task to RACF
If you also want to log messages into the SYSLOGD file that is mentioned
in Figure 2, use the
RDEFINE command to define a profile for SYSLOGD to the STARTED class, for
example, RDEFINE STARTED SYSLOGD.*.
Define the PAGENT user ID.
Before z/OS V1R13, the user ID for the PAGENT
started task must have the z/OSUNIX superuser authority, which means the z/OSUNIX user ID (UID) for this user must be set to 0, and you
must assign a default group (DFLTGRP) for the user ID. In the following example, PAGENT, the policy agent, runs under the z/OS user ID
PAGENT. The RACF command is used to define the PAGENT user ID to the OMVSGRP
default group with an OMVS segment that has a UID of 0. You can also find this sample file in
SIAYSAMP(RACFPAG2).Figure 4. Example: RACF command to define a user ID for the PAGENT
started task
If the SHARED.IDS profile has been defined in the UNIXPRV class, the UID
value must be unique. If you want to use a UID value that is already in use, you can indicate that
you intend to share the UID value across z/OS user IDs by
adding the SHARED keyword to the UID parameter of the ADDUSER command.
If
you also want to log messages into the SYSLOGD file that is mentioned in Figure 2, use the
ADDUSER command to define a user ID with the superuser authority for the SYSLOGD
started task, for example, ADDUSER SYSLOGD DFLTGRP(OMVSGRP) OMVS(UID(0)
HOME('/')).
Associate the PAGENT user ID with the PAGENT
started task.
Use the RACFRALTER command to associate the PAGENT user ID, which is
created from the preceding step, to the PAGENT started task. See the
following example. You can also find this sample file in SIAYSAMP(RACFPAG3).Figure 5. Example: RACF command to associate the PAGENT user ID with the PAGENT started task
If you also want to log messages into the SYSLOGD file that is mentioned
in Figure 2, use the
RALTER command to associate the SYSLOGD user ID with the SYSLOGD started task,
for example, RALTER STARTED PAGENT.* STDATA(USER(SYSLOGD)).
Give authorized users access to manage the PAGENT started task.
To
restrict management access to the PAGENT started task, you must define a
profile that is named MVS.SERVMGR.PAGENT in the OPERCMDS RACF resource class, and give only authorized users access to this facility. The
following example shows the RACF
commands that are used to configure this access. You can also find this sample file in
SIAYSAMP(RACFPAG4).Figure 6. Example: RACF commands to give authorized users access to manage the PAGENT started task
The pasearchUNIX command can be used to display policy definitions.
The output from this command indicates whether policy rules are active and shows the parsed results
of the policy definition attributes. PAGENT, the policy agent is designed to
ignore unknown attributes, so misspelled attributes result in the default values being
used.
The pasearch output can be used to verify whether policies are
defined correctly. However, you might not want every user to be able to see the policy definitions.
To restrict unauthorized access to the pasearch command, a resource is defined to
the SERVAUTH RACF resource class.
This type of resource can be defined for each TCP/IP stack (TcpImage) and
policy type (ptype) by using the following command:
EZB.PAGENT.sysname.TcpImage.ptype
sysname
The z/OS system name.
TcpImage
The procedure name of the TCP/IP stack that policy information is to be restricted to.
ptype
The policy type that is being requested. The following types are possible:
QoS
Policy Quality of Service
IDS
Policy Intrusion Detection System
IPSec
Policy Internet Protocol Security
TTLS
Policy AT-TLS
The following example shows the RACF commands that are used to restrict access to the pasearchUNIX command. In this example, only the USRT001 and
USRT002 z/OS user IDs are permitted to use the
pasearch command for the TCPIP TCP/IP stack on the
UTEC224 z/OS system. You can also find this sample file in
SIAYSAMP(RACFPAG4).Figure 7. Example: RACF commands to restrict unauthorized users access to the
pasearch
UNIX
command
PAGENT is responsible for reading policies from configuration members
in MVS data sets or in z/OSUNIX file system files.
Before you can define AT-TLS policies, you must configure certain
operational characteristics of PAGENT in a main configuration file. The
following statements can be contained in the main configuration file:
The TcpImage statement
The LogLevel statement
Define the TcpImage statements and appropriate logging level in the main configuration file.
The following example shows definitions in the main configuration file for a single TCP/IP stack environment. You can also find this sample file in UNIX default file /etc/pagent.conf or in
SIAYSAMP(CNFGPAG). In this example, the AT-TLS policies are defined in a
separate image-specific configuration file, TTLSPOL, for the TCPIP TCP/IP image.Figure 8. Example: PAGENT main configuration file
# LogLevel statement
# SYSERR, OBJERR, PROTERR, and WARNING messages are logged.
LogLevel 15
#
# TcpImage statement
# TCP/IP image: TCPIP
# Path to image-specific configuration file: SYS1.TCPPARMS(TTLSPOL)
# FLUSH parameter specified to delete existing policy data in the
# stack on PAGENT start-up or when the configuration files change.
# PURGE parameter specified to delete active policy data from the
# stack and Policy Agent when PAGENT is shut down normally.
TcpImage TCPIP //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE
# Here is an alternate way to specify a common AT-TLS policy for the
# TCPIP image:
#
# TcpImage TCPIP FLUSH PURGE
# TTLSConfig //'SYS1.TCPPARMS(TTLSPOL)' FLUSH PURGE
#
As mentioned in Figure 2,
/etc/pagent.conf is copied to SYS1.TCPPARMS(PAGENTP)),
and this configuration file is specified by using the PAGENT_CONFIG_FILE
environment variable in SYS1.TCPPARMS(PAGENTV).
Configure AT-TLS.
AT-TLS support is
enabled by specifying the TTLS parameter on the TCPCONFIG statement in the TCP/IP profile data set. The information
that is required to negotiate secure connections is provided to the TCP/IP
stack by the AT-TLS policies that are read, parsed, and installed by PAGENT.
When AT-TLS is enabled and a new TCP connection is established, the AT-TLS component in
the TCP layer of the stack searches for an AT-TLS
rule in the policy that matches the characteristics, including local and remote IP addresses, local
and remote ports, the connection direction, and other characteristics. If such a rule is found, TLS
protection is applied to the rule according to the details that are specified in the AT-TLS action that is associated with the rule. If no such a rule is found, the
connection is not protected with TLS.
Tip: To enable TTLS without modifying PROFILE.TCPIP, and without stopping and starting the TCP/IP stack,
define a separate file that contains the TCPCONFIG TTLS statement, and run
the VARY TCPIPOBEYFILE command, as shown in the following example:
1. OBEYFILE called TTLSON in the SYS1.TCPPARMS data set:
TCPCONFIG TTLS
2. On the MVS console, issue this command:
VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSON)
To disable TTLS, perform the following actions:
1. OBEYFILE called TTLSOFF in the SYS1.TCPPARMS data set:
TCPCONFIG NOTTLS
2. On the MVS console, issue this command:
VARY TCPIP,,O,DSN=SYS1.TCPPARMS(TTLSOFF)
To make permanent
changes for TLS support, update the TCP/IP configuration in PARMLIB:
Add the TTLS parameter to the TCPCONFIG
section.
Add the PAGENT parameter to the AUTOLOG
section.
Optionally, you can set up TTLS stack initialization access
control for AT-TLS. When AT-TLS is started during
TCP/IP stack initialization, there might be a delay between the time that
the stack comes up and when PAGENT successfully installs policy information
into the stack. This situation can leave a window of time where the connections that are intended to
be protected by AT-TLS can be established without that protection. While
this window is open, to prevent such connections from being established, define a profile for the
EZB.INITSTACK resource in the SERVAUTH RACF resource class. This type of resource can be defined for each TCP/IP stack by using the following command:
EZB.INITSTACK.sysname.TcpImage
sysname
The system name that is assigned to the z/OSLPAR.
TcpImage
The procedure name of the TCP/IP stack to which access is to be
controlled.
The following example shows how to set up TCP/IP stack initialization
access control for AT-TLS in the profile. You can also find this sample file
in SIAYSAMP(STKINIT).Figure 9. Example: SERVAUTH RACF commands to set up TCP/IP stack
initialization access control for AT-TLS
With such a profile in place, you can control which applications are allowed to
establish TCP connections before PAGENT is started.
To do so, provide the READ access to the
EZB.INITSTACK.sysname.TcpImage profile in the SERVAUTH class
for the z/OS user IDs under which such applications will
run. Before connections are enabled, all other applications are forced to wait until PAGENT is initialized and its policies are installed into the stack. For more
information, see z/OS Communications
Server V2R3: IP Configuration Guide, SC27-3650-30.
As part of the TLS
configuration process in IBM AD
Validation Server, a personal
certificate to present IBM AD
Validation Server is created.
This personal certificate must be signed with a certification authority (CA) certificate or a
self-signed certificate. Save a copy of this CA certificate or self-signed certificate on the
mainframe.
Ensure that the certificate file is downloaded from IBM AD
Validation Server in the correct format. The example in the
configuration instructions for IBM AD Validation Server creates a DER encoded X.509 certificate that is in
the Base64 format, so download this certificate in the ASCII mode if using
FTP. An alternative to FTP is to copy and paste the
certificate contents. The mainframe data set that contains the certificate must be VB with a LRECL
of at least 256 bytes.
Important: The personal certificate that is presented to IBM AD Connect for
Mainframe on behalf of the IBM AD
Validation Server must have the Common Name field equal to the
numeric IP address of the Windows machine where the
IBM AD
Validation Server is running. Do not use the host
name. Confirm this with the person who performs TLS
configurations in IBM AD
Validation Server.
Import the personal certificated that is saved in the preceding step to
the RACF database as TRUSTED. Create
an RACF key ring in the RACF database for the user ID that the
skeleton in ChangeMan will run with. Connect the imported personal
certificate to the key ring.
The following example shows how to import a CA certificate
to the RACF database, create a key
ring, and connect a user ID to the key ring. The user ID needs the read access to
IRR.DIGTCERT.LISTRING in the FACILTY class. You can also find this sample file in
IAYV510.SIAYSAMP(VCERTJCL) or IAYV510.SAMPLIB(VCERTJCL).Figure 10. Example:
Sample JCL to import a CA certificate to the RACF database, create a key ring, and
connect a user ID to the key
ring
//jobname JOB ’SAMPLE JCL’, MSGLEVEL=1,MSGCLASS=H,CLASS=A,REGION=0M
//****************************************************************************************************
//* JOB INSTRUCTIONS: *
//* ENTER VALID JOBCARD ABOVE. *
//*1. CHANGE ++CERTIFICATE-DATASET++ TO THE SEQUENTIAL FILE CONTAINING
//* CA CERT OR SELF SIGNED CERTIFICATE.
//* 2. CHANGE ++LABEL ++ TO APPROPRIATE LABEL NAME .
//* 3. CHANGE ++RINGNAME++ TO YOUR KEY RING NAME. EX: VALRING *
//* 4. CHANGE ++USERID++ TO THE USERID SUBMITTING THE
//* COMPILE SKELETON(S) IN CHANGEMAN
//****************************************************************************************************
//* AT THE END OF THIS JOB YOU SHOULD HAVE THE FOLLOWING: *
//* KEYRING : ++RINGNAME++ *
//* CA CERT/SELF SIGNED CERT CONNECTED TO THE RING OWND BY USERID
//****************************************************************************************************
//* * ADD CA CERT/SELF-SIGNED CERTIFICATE TO THE RACF DATABASE
//* * CERTAUTH - CERTIFICATE AUTHORITY TYPE.
//****************************************************************************************************
//****************************************************************************************************
//STEP1 EXEC PGM=IKJEFT01,REGION=512K
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT CERTAUTH ADD('++CERTIFICATE DATASET++') +
WITHLABEL('++LABEL++’) TRUST
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//*********************************************************************************************
//*Create RING and Connect CA cert to it.***********************************************
//*RING to be owned by USERID submitting Changeman skeleton Job.**************
//*********************************************************************************************
//STEP2 EXEC PGM=IKJEFT01,REGION=512K
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RACDCERT ID(++USERID++) ADDRING(++RINGNAME++)
RACDCERT ID(++USERID++) CONNECT(CERTAUTH LABEL('++LABEL++') +
RING(++RINGNAME++) +
default
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
SETROPTS RACLIST(FACILITY) REFRESH
/*
//**************************************************************************************************
//*PERMIT USERID to access the RING
//*REFRESH CLASSES.
//**************************************************************************************************
//PERMIT EXEC PGM=IKJEFT01,REGION=512K
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(++USERID++) ACCESS(READ)
SETR RACLIST (FACILITY) REFRESH
/*
Set up the PAGENT policy for the port that is
used by IBM AD
Validation Server.
Because IBM AD
Validation Server runs on the Windows machine, and the batch job runs on the mainframe as
the client, the PAGENT policy for the secured port needs to be configured
for the outbound direction. The following example shows how to set up the PAGENT policy. You can also find this sample file in IAYV510.SIAYSAMP(VALTTLS).Figure 11. Example: PAGENT policy
setup
TTLSRule VAL_SERVER
{
RemotePortRange ++port-number++
Direction Outbound
TTLSGroupActionRef grp_Enabled
TTLSEnvironmentActionRef AD_VALIDATE
}
##
}
##
TTLSGroupAction grp_Enabled
{
TTLSEnabled On
Trace 255 # Errors to syslogd & IP joblog
#Trace 254 # Everything to syslogd
}
##----------------------------
TTLSEnvironmentAction AD_VALIDATE
{
HandshakeRole Client
TTLSKeyRingParms
{
Keyring ++RING-NAME++ # Keyring must be owned by the userid with which Changeman skeleton
Job will run
}
TTLSCipherParmsRef TLS_12 # Ciphers modern acceptable
##
TTLSEnvironmentAdvancedParms
{
ApplicationControlled Off
## TSLV1.2 only on z/OS 2.1
TLSV1.2 On # latest TLS only
TLSV1.1 Off # TLSv1 & TLSv1.1 are on by default
TLSV1 Off # TLSv1 & TLSv1.1 are on by default
SSLV3 Off #
SSLV2 Off #
}
}
##
#
TTLSCipherParms TLS_12
{
# RSA, DSS auth with AES and SHA-2
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA256
# RSA, DSS auth with AES and SHA-1
V3CipherSuites TLS_DHE_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
# RSA, DSS auth with 3DES and SHA-1
V3CipherSuites TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
}
After you define the AT-TLS rules, refresh or
update the policy agent for the AT-TLS rules to take effect.
If PAGENT is started before you define the AT-TLS
rules, you must refresh or update PAGENT by using the MVS MODIFY command:
F PAGENT,REFRESH
The REFRESH command triggers PAGENT to reread and
process the policy files. If the FLUSH parameter is specified on the TcpImage
or discipline configuration statement, the REFRESH command triggers the FLUSH
processing.
Because the FLUSH processing deletes and re-installs all policies, you must use this command
only if you suspect that policies have become out of sync between the TCP/IP
stack and PAGENT. Note that one consequence of triggering the FLUSH
processing is that policy statistics that are being collected in the TCP/IP
stack are reset.
F PAGENT,UPDATE
The UPDATE command triggers PAGENT to reread and
process the policy files. This command differs slightly from the REFRESH command.
By using the UPDATE command, PAGENT installs and removes
only the new, changed, or deleted policies from the stack. Unchanged policies are unaffected.
Therefore, it is suggested to use the UPDATE command in most cases.