Enabling TLS Connection to IBM AD Validation Server
Before you begin
Before the Application Transparent Transport Layer Security (AT-TLS) setup in IBM® AD Connect for Mainframe, make sure to complete the enablement of Transport Layer Security (TLS) connection in IBM AD Validation Server. For instructions, see Enabling TLS Connection between IBM AD Validation Server and IBM AD Connect for Mainframe.
About this task
For IBM AD V126.96.36.199 and earlier versions, the communication between IBM AD Validation Server and IBM AD Connect for Mainframe is unencrypted socket session. Beginning with version 188.8.131.52, the optional secure communication, which uses the TLS protocol, is supported by using the AT-TLS feature of IBM 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/OS C 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/OS Communication 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.
- Configure PAGENT as a started task on z/OS.
- Define the security authorization for PAGENT.
- Define PAGENT configuration files.
- Configure AT-TLS.
- Store the personal certificate that represent IBM AD Validation Server.
- Import the personal certificate to the RACF® database.
- Set up the PAGENT policy for the port that is used by IBM AD Validation Server.
- Refresh the PAGENT policy.
Configure PAGENT as a started task on z/OS. 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).To run with the required configuration, you can use environment variables that are configured either in an IBM Multiple Virtual Storage (IBM MVS™) data set, or in a z/OS UNIX 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).
- 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).
- 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.
- 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).
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/OS UNIX superuser authority, which means the z/OS UNIX 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).
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('/')).
If you are using z/OS V1R13 or later, you can choose to use a non-superuser UID. For more information about using such a UID, see z/OS Communications Server V2R3: IP Configuration Guide, SC27-3650-30.
- Associate the PAGENT user ID with the PAGENT started task.Use the RACF RALTER 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).
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).
- Restrict access to the pasearch
The pasearch UNIX 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:
The following example shows the RACF commands that are used to restrict access to the pasearch UNIX 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).
- The z/OS system name.
- The procedure name of the TCP/IP stack that policy information is to be restricted to.
- The policy type that is being requested. The following types are possible:
- Policy Quality of Service
- Policy Intrusion Detection System
- Policy Internet Protocol Security
- Policy AT-TLS
- Define the PAGENT started task to RACF.
Define PAGENT configuration files.
PAGENT is responsible for reading policies from configuration members in MVS data sets or in z/OS UNIX 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
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 TTLS2. 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 NOTTLS2. 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:
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:
- Add the TTLS parameter to the TCPCONFIG section.
- Add the PAGENT parameter to the AUTOLOG section.
- The system name that is assigned to the z/OS LPAR.
- The procedure name of the TCP/IP stack to which access is to be controlled.
- 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).
- 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).
- 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:
- 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.
- 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.