System SSL: Modify code or System SSL application configurations to enable null encryption, RSA-Export, or RC4 ciphers

Description

Starting in z/OS V2R2, z/OS System SSL has changed its default SSL and TLS cipher support. The cipher defines the authentication, encryption, message authentication code (MAC), and key exchange algorithm used when negotiating a secure connection using SSL or TLS. When a System SSL application calls the gsk_environment_open() routine to establish a secure environment or the deprecated SSL or TLS gsk_secure_soc_init() routine specifying cipher_specs or v3cipher_spec set as NULL, the default enabled ciphers no longer includes the NULL encryption, RSA-EXPORT, or RC4 ciphers.

Table 1. SSL V3 and TLS ciphers
2 character cipher number	4 character cipher number	Short name	Description
00	0000	TLS_NULL_WITH_NULL_NULL	No encryption or message authentication and RSA key exchange.
01	0001	TLS_RSA_WITH_NULL_MD5	No encryption with MD5 message authentication and RSA key exchange.
02	0002	TLS_RSA_WITH_NULL_SHA	No encryption with SHA-1 message authentication and RSA key exchange.
03	0003	TLS_RSA_EXPORT_WITH_RC4_40_MD5¹	40-bit RC4 encryption with MD5 message authentication and RSA (export) key exchange.
04	0004	TLS_RSA_WITH_RC4_128_MD5	128-bit RC4 encryption with MD5 message authentication and RSA key exchange.
05	0005	TLS_RSA_WITH_RC4_128_SHA	128-bit RC4 encryption with SHA-1 message authentication and RSA key exchange.
06	0006	TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5¹	40-bit RC2 encryption with MD5 message authentication and RSA (export) key exchange.

¹ Ciphers are not supported for TLS V1.1 and TLS V1.2.

Table 2. SSL V2 ciphers
Cipher number	Description
1	128-bit RC4 encryption with MD5 message authentication.
2	128-bit RC4 export encryption with MD5 message authentication.

Notes:

The null encryption, RSA-EXPORT, and RC4 based ciphers are not supported when running in FIPS mode.
The SSL V2 and SSL V3 protocols are no longer being enabled by default. Therefore, the ciphers for those protocols do not have any meaning unless the protocol is explicitly enabled. See System SSL: Modify code or System SSL application configurations to enable SSLV2 or SSLV3 for more information about protocol defaults and enabling the protocols.

For the cipher values that are in the default cipher specification list along with their order, see the description of the gsk_environment_open() routine in z/OS Cryptographic Services System SSL Programming.

For applications that must continue to use these ciphers, the ciphers must be explicitly enabled.

If the ciphers in Table 1 and Table 2 are the only ciphers in common between the two secure connection endpoints, the following are example SSL errors that may occur when the ciphers are not explicitly enabled:

Return code 402: No SSL cipher specifications.
Return code -1: No SSL cipher specifications.

The full list of supported ciphers is available in z/OS Cryptographic Services System SSL Programming.

Table 3 provides more details about this migration action. Use this information to plan your changes to the system.

Table 3. Information about this migration action
Element or feature:	Cryptographic Services
When change was introduced:	z/OS V2R2. z/OS V2R1 and z/OS V1R13, both with APAR OA47405.
Applies to migration from:	z/OS V2R1 and z/OS V1R13, both without APAR OA47405.
Timing:	Before the first IPL of z/OS V2R2.
Is the migration action required?	Yes, if System SSL applications for secure SSL/TLS connections are used.
Target system hardware requirements:	None.
Target system software requirements:	None.
Other system (coexistence or fallback) requirements:	None.
Restrictions:	None.
System impacts:	SSL and TLS secure connections may fail if a System SSL application is relying on one of the System SSL defined default ciphers and it is no longer enabled.
Related IBM Health Checker for z/OS check:	None.

Steps to take

If your installation utilizes System SSL applications for secure SSL/TLS connections, examine those applications to determine if they require the usage of null encryption, RSA-EXPORT, or RC4 based ciphers.

If the System SSL application runs in FIPS mode, these ciphers are not supported and no migration action is needed.

For each System SSL application that requires the usage of one or more of these ciphers, consult each application's configuration documentation to determine the appropriate enablement capability. If the application supports the use of environment variables, see Method 2 in this section for environment variable information.

If your System SSL written application needs to support one or more of the removed ciphers, z/OS System SSL provides two methods to override the default SSL/TLS ciphers enabled when negotiating a secure connection using the SSL/TLS routines. Your application will need to utilize one of the following methods:

Method 1

Use the gsk_attribute_set_buffer() or gsk_secure_soc_init() routine:

gsk_attribute_set_buffer()

The gsk_attribute_set_buffer() routine supports the specification of SSL V2 and SSL V3/TLS ciphers in preference order through the GSK_V2_CIPHER_SPECS, GSK_V3_CIPHER_SPECS, and GSK_V3_CIPHER_SPECS_EXPANDED attributes. Each attribute buffer consists of a single character string consisting of the cipher values enabled to be used for the secure connection.

To re-enable one or more of the SSL V2 ciphers, specify the GSK_V2_CIPHER_SPECS attribute along with the complete list of ciphers to be available during the negotiation of the secure connection. For example, if you want to restore the V2 default cipher list, you need to set the buffer value to "713642" when the System SSL Security Level 3 FMID (JCPT421) is installed. Otherwise, set the buffer to "642". Setting the value to "713642" when the System SSL Security Level 3 FMID (JCPT421) is not installed results in ciphers "713" being ignored.

To re-enable one or more of the SSL V3 ciphers, specify GSK_V3_CIPHER_SPECS if 2-character cipher specifications is enabled (this is the default), or GSK_V3_CIPHER_SPECS_EXPANDED if 4-character cipher specifications is enabled along with the complete list of ciphers to be available during the negotiation of the secure connection. For example, if you want to restore the SSL V3 2-character default cipher list, set the buffer value to "050435363738392F303132330A1613100D0915120F0C0306020100" when the System SSL Security Level 3 FMID (JCPT421) is installed. Otherwise, set the buffer to "0915120F0C0306020100". Setting the value to "050435363738392F303132330A1613100D0915120F0C0306020100" when the System SSL Security Level 3 FMID (JCPT421) is not installed results in ciphers "050435363738392F303132330A1613100D" being ignored. When using the 4-character cipher values, the buffer value is "0005000400350036003700380039002F0030003100320033000A0016001 30010000D000900150012000F000C00030006000200010000" when the System SSL Security Level 3 FMID (JCPT421) is installed. Otherwise, set the buffer to "000900150012000F000C00030006000200010000". Setting the value to "0005000400350036003700380039002F0030003100320033000A0016001 30010000D000900150012000F000C00030006000200010000" when the System SSL Security Level 3 FMID (JCPT421) is not installed results in ciphers "0005000400350036003700380039002F0030003100320033000A0016001 30010000D" being ignored.

gsk_secure_soc_init()

The gsk_secure_soc_init() routine (deprecated API) supports the specification of SSL V2 and SSL V3/TLS ciphers through the cipher_specs and v3cipher_specs fields in the gsk_soc_init_data structure.

To re-enable one or more of the SSL V2 ciphers, specify the complete list of ciphers to be available during the negotiation of the secure connection in the cipher_specs field. For example, if you want to restore the SSL V2 default cipher list, set the buffer value to "713642" when the System SSL Security Level 3 FMID (JCPT421) is installed. Otherwise, set the buffer to "642". Setting the value to "713642" when the System SSL Security Level 3 FMID (JCPT421) is not installed results in ciphers "713" being ignored.

To re-enable one or more of the SSL V3/TLS ciphers, specify the complete list of ciphers to be available during the negotiation of the secure connection in the v3cipher_specs field. For example, if you want to restore the SSL V3 2-character default cipher list, set the buffer value to "050435363738392F303132330A1613100D0915120F0C0306020100" when the System SSL Security Level 3 FMID (JCPT421) is installed. Otherwise, set the buffer to "0915120F0C0306020100". Setting the value to "050435363738392F303132330A1613100D0915120F0C0306020100" when the System SSL Security Level 3 FMID (JCPT421) is not installed results in ciphers "050435363738392F303132330A1613100D" being ignored.

Method 2

Use the environment variables GSK_V2_CIPHER_SPECS, GSK_V3_CIPHER_SPECS, and GSK_V3_CIPHER_SPECS_EXPANDED:

GSK_V2_CIPHER_SPECS: To re-enable one or more of the SSL V2 ciphers, specify the GSK_V2_CIPHER_SPECS attribute along with the complete list of ciphers to be available during the negotiation of the secure connection. See Method 1 in this section for cipher specification list examples.
GSK_V3_CIPHER_SPECS: To re-enable one or more of the SSL V3 ciphers, specify GSK_V3_CIPHER_SPECS if 2-character cipher specifications is enabled (this is the default) along with the complete list of ciphers to be available during the negotiation of the secure connection. See Method 1 in this section for cipher specification list examples.
GSK_V3_CIPHER_SPECS_EXPANDED: To re-enable one or more of the SSL V3 ciphers, specify GSK_V3_CIPHER_SPECS_EXPANDED if 4-character cipher specifications is enabled along with the complete list of ciphers to be available during the negotiation of the secure connection. See Method 1 in this section for cipher specification list examples.

Note: Applications that have specified the SSL V3 cipher specifications using the gsk_attribute_set_buffer() or gsk_secure_soc_init() routine override the respective environment variable settings.

Reference information

For more information about System SSL, see z/OS Cryptographic Services System SSL Programming.