System SSL: Modify code or System SSL application configurations to enable SSLV2 or SSLV3
Description
Starting in z/OS V2R2, z/OS System SSL has changed its default protocol support. When a System SSL application calls the gsk_environment_open() routine to establish a secure environment, SSL V2 and SSL V3 will now be disabled by default. TLS V1.0 will continue to be enabled by default. For applications that must continue to use these protocols, the protocol must be explicitly enabled.
- Return code 402: No SSL cipher specifications.
- Return code 412: SSL protocol or certificate type is not supported.
- Return code 429: SSL V2 header is not valid.
For applications that use the SSL V2 or SSL V3 protocol, evaluate the application's usage and change the application to use the TLS protocols if possible. TLS has addressed many security deficiencies in the prior SSL V2 and SSL V3 protocols.
Table 1 provides more details about this migration action. Use this information to plan your changes to the system.
| Element or feature: | Cryptographic Services |
|---|---|
| When change was introduced: | z/OS V2R2. z/OS V2R1 and z/OS V1R13, both with APAR OA46489. |
| Applies to migration from: | z/OS V2R1 and z/OS V1R13, both without APAR OA46489. |
| 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: | None. |
| 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 either the SSL V2 or SSL V3 protocols to be enabled.
- The first method is the Application Programming Interface (API) gsk_attribute_set_enum() routine. This routine allows the enablement of the SSL/TLS protocols at either the SSL/TLS environment or connection level. To enable the usage of SSL V2, enumeration parameter GSK_PROTOCOL_SSLV2 must be set to GSK_PROTOCOL_SSLV2_ON. To enable the usage of SSL V3, enumeration parameter GSK_PROTOCOL_SSLV3 must be set to GSK_PROTOCOL_SSLV3_ON.
- The second method uses environment variables GSK_PROTOCOL_SSLV3 and GSK_PROTOCOL_SSLV2. To enable the usage of SSL V2, environment variable GSK_PROTOCOL_SSLV2 must be set to ON, 1, or ENABLED. To enable the usage of SSL V3, environment variable GSK_PROTOCOL_SSLV3 must be set to ON, 1, or ENABLED. Note that an environment variable setting is overridden if the application calls the gsk_attribute_set_enum() routine to set the GSK_PROTOCOL_SSLV2 and GSK_PROTOCOL_SSLV3 values.
If the protocols are required, consult each application configuration documentation to determine the appropriate enablement capability.
Reference information
For more information about System SSL, see z/OS Cryptographic Services System SSL Programming.