This article is the sixth in a series that describe the different z/OS TLS providers, how those providers expose their settings, which providers are used by some common IBM z/OS-based products, and some examples of changing very specific TLS settings for each provider and product.
For a complete listing of all the articles, please refer to the anchor article entitled z/OS TLS/SSL Configuration One-stop information hub
If you have a comment or question about this article or any in the series, please post it to the z/OS Communications Server discussion group on the IBM Z and Linux ONE Community. For the quickest response, please prefix your discussion subject line with “TLS Settings:”
For details on setting TLS parameters for ISV products, please consult the appropriate vendor documentation.
Approaches to configuring AT-TLS settings
z/OS Communications Server’s Application Transparent TLS (AT-TLS) feature provides TLS protection to z/OS TCP/IP applications through policy rules instead of application source code changes. AT-TLS invokes z/OS® System SSL in the TCP layer of the stack, transparently from the perspective of the z/OS application. The z/OS policy agent (pagent) reads the rules and installs them into each TCP/IP stack for enforcement. When a new TCP connection matches an AT-TLS rule, AT-TLS calls System SSL using the protection attributes specified on that rule.
There are two primary approaches to build and maintain your AT-TLS policy rules:
- Using the IBM Configuration Assistant for z/OS Communications Server task in z/OS Management Facility (z/OSMF)
- Hand-coding your AT-TLS policy rules
Figure 1 illustrates the two approaches and the general relationship between NCA, Policy Agent, and the TCP/IP stack in relation to AT-TLS.
Regardless of the approach taken, many IBM z/OS users manage their AT-TLS policy updates within their local shop’s change management system. They apply the same type of reviews and scrutiny to those policy updates as they would configuration or service level changes for their important z/OS workloads.
Figure 1 Two approaches to managing AT-TLS policy
Using IBM Network Configuration Assistant for z/OS Communications Server
The preferred and recommended approach to building and maintaining your AT-TLS policy rules is using the z/OSMF plugin called the IBM Network Configuration Assistant (NCA) for z/OS Communications server.
Under direction of an authorized user, the NCA creates, manages, and deploys AT-TLS policy files (as well as policy for other z/OS Communications Server technologies) to one or more z/OS systems and even across sysplexes. Through its panels, wizards, and pre-configured objects like traffic descriptors and security levels, NCA guides the user through a wide variety of common AT-TLS policy management tasks, relieving that user from the need to know any of the low-level syntax or structure of the AT-TLS policy rules. NCA also provides an excellent structure for maintaining a history of policy updates and the ability to revert to earlier versions of policy.
For more information on using the Network Configuration Assistant, including tutorials, see the z/OSMF Network Configuration Assistant Task Summary.
Hand coding AT-TLS policy rules
It is also possible to manually create the AT-TLS policy rules by hand coding all the required statements in a z/OS UNIX file or MVS data set. While hand coding is not the preferred approach, many users have used it effectively. For more information, see the following references:
How AT-TLS sets the TLS settings used by System SSL
AT-TLS invokes System SSL on behalf of the z/OS LE sockets application. As such, AT-TLS is ultimately just a System SSL application. However, because of the way it creates and manages the LE environments under which System SSL executes, there are a few important considerations to keep in mind:
Background on AT-TLS LE environment
- AT-TLS almost always overrides any System SSL defaults and environment variables
- AT-TLS accommodations for between-release System SSL enhancements prior to V2R5
Background on AT-TLS LE environments
As described in an earlier article, System SSL executes under the Language Environment (LE) environment of the invoking application. This means AT-TLS must provide suitable LE environments for System SSL to use. A set of LE environments, along with a dedicated instance of the System SSL load library, are created during AT-TLS initialization for each TTLSGroup object in the AT-TLS policy file. Once created, the System SSL library instance for the TTLSGroup executes within that group’s LE environments.
Since environment variables are established for an LE environment, any manipulation of System SSL environment variables for AT-TLS must be done at the TTLSGroup level. However, as described under the next topic below, specification of System SSL environment variables illustrated in the article Updating System SSL settings (outside of AT-TLS) does not work for most settings under AT-TLS.
AT-TLS almost always overrides any System SSL defaults and environment variables
When Policy Agent installs AT-TLS rules into the TCP/IP stack, it specifies values for the vast majority of System SSL settings – even when those values are not explicitly specified in the AT-TLS policy statements. In other words, Policy Agent usually supplies its own default value when a value is not specified on a given AT-TLS policy statement.
Of course, the way Policy Agent specifies its values to System SSL is by passing them as parameters on the System SSL API calls it invokes. Since a parameter specified on an API call always overrides a System SSL environment variable or default, the Policy Agent values, whether specified by the policy statement or set as a Policy Agent default, always takes precedence over any System SSL environment variable.
Similarly, NCA always specifies values in the generated AT-TLS policy unless explicitly directed not to by the NCA user.
Because of this, the methods for specifying System SSL environment variables in Updating System SSL settings (outside of AT-TLS) does not work for most settings under AT-TLS.
AT-TLS accommodations for between-release System SSL enhancements prior to V2R5
For many years, it was rare for System SSL to introduce a new environment variable between z/OS releases through a new function APAR. In these rare instances, the associated new AT-TLS parameter could not be added until the subsequent z/OS release, leaving a temporary configuration gap in AT-TLS for the releases on which the System SSL new function APAR was delivered. However, with the advent of Continuous Delivery and quarterly enhancements to modern z/OS releases, it is more common for System SSL to add new parameters between releases. Because of this, AT-TLS was updated in V2R5 so that new AT-TLS parameters can be easily introduced between releases, which means that for z/OS V2R5 and later, when a new System SSL parameter is added between releases, the corresponding AT-TLS parameters can also be added at the same time.
If you are running on z/OS V2R4 or earlier, and a new System SSL environment variable is introduced on that release as a new function APAR, there are two ways to specify the new environment variable for use under AT-TLS:
- You can code the System SSL environment variable in your LE CEEPRMxx parmlib member. This works because AT-TLS is not aware of that parameter/value and does not override the system level setting.
- You can use an AT-TLS environment file that specifies System SSL environment variables that were introduced between releases. To specify such a file:
- Create a file that contains the new System SSL environment variable with the desired settings. This file needs to be accessible to the TCP/IP stack.
- If you use the IBM Network Configuration Assistant (NCA) for z/OS Communications Server in z/OSMF to maintain your AT-TLS policy, log into the z/OSMF Network Configuration Assistant's AT-TLS perspective. The LE Environment Variable file can be configured at the z/OS Image level or at the Connectivity Rule level.
- In most cases, using an image-level environment file is the best approach as the settings in that image-level file apply to all connectivity rules for all TCP/IP stacks for the z/OS system. To configure an environment file at the z/OS Image level, navigate to the NCA->AT-TLS->z/OS System Image dialog under the “Advanced” tab. Specifically, the “Language environment ENV file” portion of that tab controls the location of the environment file for the z/OS Image.
- If you do need to configure a different environment file for a specific Connectivity Rule, navigate to the NCA->AT-TLS->TCP/IP Stack->Connectivity Rule->Advanced dialog for the relevant Connectivity Rule. On that dialog, click the “Advanced” button and then click on the “Environment” tab under the resulting dialog. Specifically, the “Language environment ENV file” portion of that tab controls the location of the environment file for the rule.
- If you hand code your AT-TLS policy, add an Envfile parameter that specifies the name of your new file to the TTLSGroupAdvancedParms statement associated with the relevant AT-TLS rules. In this case, any environment variables set in the specified file are used when AT-TLS creates a TTLS group instance from the TTLSGroupAction that references the TTLSGroupAdvancedParms statement. Using this approach, you can override the system-level settings in the CEEPRMxx parmlib member for the TTLS group.
The first is preferred in most cases (rely on the system-level setting). Only use the second approach when absolutely necessary i.e., if you need to override the system-level setting for one or more applications. The AT-TLS rules for those applications would reference the TTLSGroupActionGroupAdvancedParms with the new Envfile parameter.
Note: In many cases, when AT-TLS support is added for a new System SSL parameter in the subsequent release, the values specified through a System SSL environment variable is ignored by the newer release because AT-TLS overrides it. This can sometimes result in what looks like a regression of function. Therefore, you must pay close attention to any release-to-release upgrade actions that involve the addition of new AT-TLS parameters. The upgrade actions guide you to avoid any potential functional regression.
An example: Controlling ephemeral Diffie Hellman (DHE) key exchange key length in AT-TLS
As an example, let’s see how to configure the minimum DHE key size using AT-TLS policy parameters, via two different options, by using the IBM Configuration Assistant (NCA) for z/OS Communications Server and by hand-coding the policy updates.
- Using the IBM Configuration Assistant (NCA) for z/OS Communications Server
- Log into the z/OSMF Network Configuration Assistant's AT-TLS perspective. The minimum Diffie-Hellman KEX key lengths are configured on the Security Level objects under the NCA->AT-TLS->Security Level->Advanced dialog under the “Other” tab.
- Unclick the “Use System SSL Defaults” checkbox.
- Select the “Diffie-Hellman group size of 2048” under both the “Specify the minimum Diffie-Hellman group size to be used by the server for an ephemeral Diffie-Hellman key exchange message when AT-TLS is the TLS client” and the “Specify the minimum Diffie-Hellman group size to be used by the server for an ephemeral Diffie-Hellman key exchange message when AT-TLS is the TLS server” dropdowns.
Here is an example of the “Other” tab of the Advanced AT-TLS Settings dialog:
Note: the exact dialog and navigation path through the NCA for any given parameter depends on which parameter you want to set. Many of the TLS settings related to specific algorithms and key lengths are found in the Security Level dialogs.
- Hand-coding AT-TLS policy rules
Code ClientEDHGroupSize 2048 and ServerEDHGroupSize 2048 on the TTLSEnvironmentAdvancedParms statement referenced by your AT-TLS rule. These parameters/values tell AT-TLS to set the System SSL GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE and GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE parameters to a value of 2048 when it calls System SSL. For example:
# Client rule
TTLSRule Client_Rule
{
. . .
TTLSEnvironmentAction
{
. . .
HandshakeRole Client
TTLSEnvironmentAdvancedParmsRef Standard_EnvAdvParms
}
}
# Server rule
TTLSRule Server_Rule
{
. . .
TTLSEnvironmentAction
{
. . .
HandshakeRole Server
TTLSEnvironmentAdvancedParmsRef Standard_EnvAdvParms
}
}
. . .
# Environment advanced parms for both client and server rules
TTLSEnvironmentAdvancedParms Standard_EnvAdvParms
{
. . .
ClientEDHGroupSize 2048
ServerEDHGroupSize 2048
}
. . .
Navigation
Next article: Updating Java TLS settings
Previous article: Updating System SSL settings (outside of AT-TLS)