This article is part of a series that describe the different z/OS TLS providers, how those providers expose their settings, which workloads use which providers, and some examples of changing very specific TLS settings for each provider and workload.
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.
Introduction
There is a current movement in IT to eliminate the use of weaker elliptic curves for key exchange (KEX) with Transport Layer Security (TLS) TLSv1.2 handshakes. Similarly, there is growing interest in enforcing Diffie-Hellman key sizes to a minimum of 2048 bits when using ephemeral Diffie-Hellman (DHE) KEX.
This article builds upon the techniques presented in the other articles within this series to explain how to customize the set of TLSv1.2 KEX curves and to enforce 2048-bit or greater DHE key lengths.
Controlling TLSv1.2 KEX curves and DHE KEX key length in the TLS providers
System SSL
To configure the TLSv1.2 supported KEX curves, there are two relevant System SSL settings:
- The GSK_CLIENT_ECURVE_LIST setting controls the list of elliptic curves or supported groups that the TLS client is willing to use. These are specified in order of preference.
- With System SSL APAR V2R4 and V2R5 OA61783, System SSL introduced the GSK_SERVER_ALLOWED_KEX_ECURVES setting. This setting specifies the list of elliptic curves that are allowed by the server for the TLS V1.2 server key exchange when using ECDHE-based cipher suites.
To configure the minimum DHE key size, System SSL provides the GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE and GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE settings that specify the minimum Diffie-Hellman key size for ephemeral Diffie-Hellman KEX when using DHE-based cipher suites. Specifying a value of 2048 on these environment variables enforces the use of keys that are at least 2048 bits long.
Example:
Updating the LE CEEPRMxx parmlib member as described in Updating System SSL settings (outside of AT-TLS), the following statements would set system-level System SSL defaults for:
- TLSv1.2 KEX curves to secp256r1, secp384r1, secp521r1, x25519 and x448 for both TLS client and TLS server roles and
- Ephemeral Diffie-Hellman (DHE) KEX key size to a minimum of 2048 bits for both TLS client and TLS server roles
CEEDOPT(... ,
ENVAR(
( GSK_CLIENT_ECURVE_LIST=00230024002500290030
, GSK_SERVER_ALLOWED_KEX_ECURVES=00230024002500290030
, GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE=2048
, GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE=2048
),
OVR
)
)
CELQDOPT (... ,
ENVAR(
( GSK_CLIENT_ECURVE_LIST=00230024002500290030
, GSK_SERVER_ALLOWED_KEX_ECURVES=00230024002500290030
, GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE=2048
, GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE=2048
),
OVR
)
)
AT-TLS
To configure the TLS client-side list of supported curves, code the ClientECurves parameter of the TTLSSignatureParms statement referenced by your AT-TLS rule. This parameter determines how AT-TLS sets the GSK_CLIENT_ECURVE_LIST parameter when it calls System SSL.
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 client KEX curves are configured on the Security Level objects under the NCA->AT-TLS->Security Level->Advanced dialog under the “Signature and Key Share” tab. Specifically, the “Named groups supported by the client” portion of that tab controls the GSK_CLIENT_ECURVE_LIST setting.
To configure the set of curves a TLS server allows, the approach varies between V2R4 and V2R5.
- z/OS V2R4
Since the System SSL GSK_SERVER_ALLOWED_KEX_ECURVES environment variable was added to V2R4 with System SSL APAR OA61783, there is no explicit AT-TLS support support on V2R4. To specify a server allowed key exchange curve list on V2R4, you must use one of the two approaches (LE CEEPRMxx parmlib or AT-TLS environment file) described under the heading “AT-TLS accommodations for between-release System SSL enhancements prior to V2R5” in Updating AT-TLS settings.
Note: If you perform these actions at V2R4, when you upgrade V2R4 systems to V2R5, you need to take an upgrade action as described under the next bullet.
System SSL added a new GSK_SERVER_ALLOWED_KEX_ECURVES environment variable to V2R5 with System SSL APAR OA61783. At the same time, z/OS V2R5 Communications Server APAR PH45902 added the corresponding new ServerKexECurves parameter to the TTLSSignatureParms statement to configure the System SSL server allowed key exchange curve list. In addition, IBM Network Configuration Assistant for z/OS V2R5 Communications Server APAR PH47400 adds support to configure the server allowed key exchange curves through the NCA’s AT-TLS perspective.
With z/OS 3.1 and later, the above changes are built into the release.
Note: when upgrading from V2R4, if you initially configured the GSK_SERVER_ALLOWED_KEX_ECURVES environment variable on a V2R4 system for use with AT-TLS as described in the preceding bullet, there is a required upgrade action when upgrading to later versions.
Since AT-TLS in V2R5 (with the above APARs applied) and later is aware of the new System SSL setting, AT-TLS may override any specification of the GSK_SERVER_ALLOWED_KEX_ECURVES variable at the system level via the CEEPRMxx parmlib member or in the AT-TLS environment file. The exact behavior depends on whether you have also applied IP APAR PH56638 the z/OS V2R5 or 3.1 system
-
- If IP APAR PH56638 is applied to the V2R5 or 3.1 system, the value configured with the System SSL GSK_SERVER_ALLOWED_KEX_ECURVES variable remains in effect but is not be visible from the z/OS UNIX pasearch command or the netstat TTLS/-x report.
- If IP APAR PH56638 is not applied to the V2R5 or 3.1 system, the server allowed KEX curves specified in the AT-TLS environment files are ignored and an AT-TLS default is used. This may result in an undesired key exchange value being accepted by the server.
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 KEX curves are configured on the Security Level objects under the NCA->AT-TLS->Security Level->Advanced dialog under the “Signature and Key Share” tab. Specifically, the “Named groups for TLS Server Key Exchange” portion of that tab controls the GSK_SERVER_ALLOWED_KEX_ECURVES setting.
To configure the minimum DHE key size, 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 GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE and GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE parameters to a value of 2048 when it calls System SSL.
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 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. Specifically, unclick the “Use System SSL Defaults” checkbox and then 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.
Java Secure Sockets Extension (JSSE)
Java provides a complete TLS implementation via the Java Secure Sockets Extension (JSSE), which is a set of classes that any Java program can use to achieve TLS protection of their TCP sockets. JSSE in turn relies on underlying Java Cryptographic Extension (JCE) providers for its cryptographic operations.
Configuring supported TLS ECDHE KEX curves
Unfortunately, the x25519 and x448 curves are not supported by JSSE in Java 8. However, the latest java.security file does disable the 192- and 224-bit curves. Per this reference, these curves were disabled in Java 8 Service Release 4, FixPack 5.
- Java 11Java 11 supports the x25519 and x448 curves and enables them both by default in non-FIPS-1440 mode. Further, the 192- and 224-bit curves are disabled by the java.security file, just as they are under Java 8.
To configure the minimum DHE key size
On the relevant jdk.tls.disabledAlgorithms property specify DH keySize < 2048. This property is typically specified in the JVM’s java.security file. If you do not find such a file for your JVM, consult the documentation for your program or product to find the location of this property specification.
Note: Specifying a DH keysize of 2048 can cause higher CPU consumption than 1024.
For more information, check the related information: How to disable SSL/TLS Diffie-Hellman keys less than 2048 bits
Note: The JVM’s java.security file should be checked and updated each time you put on new maintenance as the JVM might introduce a new algorithm to jdk.tls.disabledAlgorithms that may need to copied to other java.security files on your system.
Controlling TLSv1.2 KEX curves and DHE KEX key length for specific z/OS products that call System SSL directly (not using AT-TLS)
For any applications or middleware that use AT-TLS for their TLS protection, follow the instructions under the “AT-TLS” section above.
IBM HTTP Server (IHS)
With APAR PH51678, IHS provides a new SSLSupportedCurves configuration parameter that allows you to specify exactly which TLSv1.2 or TLSv1.3 KEX curves you want your IHS instance to allow. This APAR also removes the secp224r1 and secp192r1 curves from the default list of curves.
For more information, see the IBM Support page on APAR PH51678.
Note: IHS does not support any DHE cipher suites, so the DHE KEX key size not a factor for this product.
IHS also provides a variety of other TLS-related settings. For more information, refer to the Apache HTTP Server documentation on module mod_ibm_ssl.
IBM Tivoli Directory Server for z/OS (z/OS LDAP server)
The z/OS LDAP server does not provide any configuration parameters related to TLS KEX settings. As such, you must rely on System SSL environment variables to control these settings. Two approaches are available to you for setting System SSL environment variables for this server.
- Use system-wide settings as described above under the System SSL topic on page 4.
Specify the variables in the LDAP server’s environment file. For more information, see the z/OS IBM Tivoli Directory Server Administration and Use for z/OS book’s topic entitled “Environment variables used by the LDAP server”.
IBM Sterling Connect:Direct for z/OS
Like the z/OS LDAP server, Connect:Direct SecurePlus does not provide any explicit configuration parameters for TLS KEX settings. As such, you must rely on System SSL environment variables to control these settings. Two approaches are available to you for setting System SSL environment variables for this server.
Some users use AT-TLS to protect their Connect:Direct traffic. In these cases, Connect:Direct is configured to run without any TLS support from SecurePlus, essentially as if it were communicating over the network in cleartext. The underlying AT-TLS protection is completely transparent to Connect:Direct on z/OS. If your shop uses this approach, then follow the guidance under the AT-TLS heading on page 6 for your Connect:Direct traffic.
CICS
CICS Transaction Server (CICS TS), when operating as a server, can be configured to either call System SSL directly or to use AT-TLS for its TLS protection – the CICS TS TCPIPSERVICE configuration determines which approach is used. For more information on TCPIPSERVICE configuration, see the CICS Transaction Server for z/OS Securing CICS topic “Introduction to Application Transparent Transport Layer Security (AT-TLS).”
When AT-TLS is used, the guidance under the AT-TLS heading on page 2 applies to CICS TS server-side function.
When CICS TS is acting as a client or when CICS TS is configured to use its own SSL support as a server, then the following guidance applies.
With CICS Transaction Server (CICS TS) for z/OS APAR PH50175, CICS TS has been updated with a new feature toggle that controls, among other things, the strength of the ECDHE curves and the DHE groups. The relevant PTFs are:
- UI90656 for CICS TS 5.6
- UI90657 for CICS TS 5.5
- UI90658 & UI90659 for CICS TS 5.4
This support is also available on CICS TS 6.1 with APAR PH51719 (PTF UI90660).
For details on the new com.ibm.cics.tls.minimumkeystrength toggle, see the CICS Transaction Server for z/OS Reference topic on Feature toggles.
MQ
When IBM MQ for z/OS is configured to call System SSL directly, IBM MQ for z/OS does not provide an explicit configuration control for ECDHE KEX curves or for the minimum DHE key length. Rather, MQ relies on the setting of System SSL environment variables for this. If you specify the settings in the CEEPRMxx parmlib member as described under the System SSL heading, those settings should protect your MQ jobs. You can set the variables for the MQ jobs themselves as described in the Modifying elliptic curve key length on z/OS topic in the IBM MQ information center.
IBM Content Manager On Demand
Like the z/OS LDAP server, CMOD does not provide any explicit configuration parameters for TLS KEX settings. As such, you must rely on System SSL environment variables to control these settings. Two approaches are available to you for setting System SSL environment variables for this server.
- Use system-wide settings as described above under the System SSL topic.
- Specify the variables in the CMOD JCL using a CEEOPTS DD that specifies an environment file (ENVAR='_CEE_ENVFILE=DD:ENVIRON').
Controlling TLSv1.2 KEX curves and DHE KEX key length for specific z/OS Java products
WebSphere Application Server
WebSphere Traditional as well as WebSphere Liberty are written in Java and therefore rely on the JSSE TLS provider to protect their connections.
Configuring supported TLS ECDHE KEX curves
Since Java 8 JSSE does not support the x25519 or x448 curves (as described above), WAS Traditional and WAS Liberty do not support them either. However, the latest java.security file does disable the 192- and 224-bit curves via the jdk.tls.disabledAlgorithms parameter – this should apply to both WAS Traditional and WAS Liberty.
To configure the minimum DHE key size:
- Replace the java.security files at:
WAS_HOME/DeploymentManager/properties/java.security
WAS_HOME/AppServer/properties/java.security
from symbolic links to a real files that can be edited.
- Copy the value of jdk.tls.disabledAlgorithms from the JVM's
WAS_HOME/AppServer/java/8.0/lib/security/java.security
to
WAS_HOME/DeploymentManager/properties/java.security and
WAS_HOME/AppServer/properties/java.security
- Change the DH keySize for jdk.tls.disabledAlgorithms from:
DH keySize < 1024
to
DH keySize < 2048
Note: Using DH keysize 2048 can be more CPU intensive than 1024.
For more information, check the related Infocenter topic: How to disable SSL/TLS Diffie-Hellman keys less that 2048 bits
Note: The java.security file should be checked and updated each time you put on new maintenance as the JVM might introduce a new algorithm to jdk.tls.disabledAlgorithms, which needs to be copied to your java.security file in WebSphere.
z/OS Management Facility (z/OSMF)
z/OSMF depends on WAS Liberty.
Since WAS Liberty does not support the x25519 or x448 curves, these curves cannot be used with z/OSMF. However, the latest WAS Liberty java.security file disables the 192- and 224-bit curves via the jdk.tls.disabledAlgorithms parameter, so z/OSMF should not be exposed to those curves.
See the “WebSphere Application Server” section above for instructions on setting the DHE key length.
Navigation
Previous article: Updating TLS settings for various IBM z/OS-based products