APAR status
Closed as new function.
Error description
NEW FUNCTION - Add System SSL support for x25519/x448 and limiting key exchange elliptic curves for TLSV1.2 and earlier.
Local fix
Problem summary
**************************************************************** * USERS AFFECTED: System SSL applications performing TLS * * V1.0, TLS V1.1, and/or TLS V1.2 handshakes. * **************************************************************** * PROBLEM DESCRIPTION: System SSL has been enhanced to allow * * the x25519 and x448 elliptic curves to * * be used for TLS V1.0, TLS V1.1, and * * TLS V1.2 negotiated connections. * * * * System SSL has been enhanced to give * * server applications the ability to * * limit the elliptic curves chosen for * * TLS V1.0, TLS V1.1, and TLS V1.2 key * * exchanges. * **************************************************************** * RECOMMENDATION: APPLY PTF * **************************************************************** System SSL has been enhanced to allow the x25519 and x448 elliptic curves to be used for TLS V1.0, TLS V1.1, and TLS V1.2 negotiated connections. System SSL has been enhanced to give server applications the ability to limit the elliptic curves chosen for TLS V1.0, TLS V1.1, and TLS V1.2 key exchanges. KEYWORDS: ZOS0301C/K
Problem conclusion
Temporary fix
Comments
System SSL has been enhanced to allow the x25519 and x448 elliptic curves to be used for TLS V1.0, TLS V1.1, and TLS V1.2 negotiated connections. System SSL has been enhanced to give server applications the ability to limit the elliptic curves chosen for TLS V1.0, TLS V1.1, and TLS V1.2 key exchanges. System SSL server applications now use a list of elliptic curves allowed by the server when selecting the key exchange elliptic curve for TLS V1.0, TLS V1.1, and TLS V1.2 handshakes. When selecting the key exchange elliptic curve, the server's list is used with the client's supported elliptic curve list to find and select the first elliptic curve in common between both lists. System SSL client applications specify their elliptic curves list using the GSK_CLIENT_ECURVE_LIST attribute. By default, the x25519 and x448 elliptic curves are not specified. When TLS V1.3 is enabled, x25519 is added to the end of the default list. System SSL server applications specify their elliptic curves list using the new GSK_SERVER_ALLOWED_KEX_ECURVES attribute. By default, x25519 and x448 elliptic curves are not specified. When processing the cipher list, System SSL server applications will look for the common elliptic curve when an ECDHE cipher is specified. If no such common elliptic curve is found, the ECDHE ciphers are disabled. Documentation updates to the z/OS Cryptographic Services System Secure Sockets Layer Programming publication (SC14-7495) Chapter: System SSL application programming considerations - Add the following to the end of the list "When designing a System SSL SSL/TLS application, there are several key functional capabilities to consider:" Will the application need to limit the elliptic curve utilized during the handshake key exchange process? System SSL provides the capability for a client or server to limit the key exchange elliptic curves. See "Limiting Key Exchange Elliptic Curves" for additional information. - Add the following new section Limiting Key Exchange Elliptic Curves When utilizing an Ephemeral Elliptic Curve Diffie Hellman cipher (TLS_ECDHE_xxx), each side of the connection being negotiated generates an elliptic curve key pair and exchanges the public key as part of the TLS V1.0, TLS V1.1 or TLS V1.2 handshake process. The elliptic curve is selected by the server using a list of supported elliptic curves provided by the client. System SSL provides the capability to define the list of supported elliptic curves through either an environment variable or through an invocation to the gsk_attribute_set_buffer() routine. When a client, the list of supported elliptic curves is defined using GSK_CLIENT_ECURVE_LIST. This list represents the elliptic curves supported by the client for the key exchange in the client's preferred order. This list also represents certificate elliptic curves supported when a server is using an elliptic curve public key certificate. When a server, the list of allowed elliptic curves is defined using GSK_SERVER_ALLOWED_KEX_ECURVES. This list represents the allowed key exchange elliptic curves with no defined order. When enabled for FIPS mode, elliptic curves x25519 and x448 are not supported and if specified, will be ignored. The specified list may also be tailored to meet the requirements of the FIPS level being utilized. For information about FIPS mode level support, see Chapter: "System SSL and FIPS 140-2". For example: If the client supports secp256r1 (0023) and secp384r1 (0024) and prefers secp256r1 to be utilized, GSK_CLIENT_ECURVE_LIST=00230024. If the server supports secp384r1 (0024), x25519 (0029) and secp256r1 (0023), GSK_SERVER_ALLOWED_KEX_ECURVES=002400290023. The key exchange process for the above connection would use secp256r1 (0023). The elliptic curve selection involves the server looking through the client's provided list for a match in the server's list. The first matching elliptic curve is used. Chapter: API Reference gsk_attribute_get_buffer() - Add the following under Usage: GSK_SERVER_ALLOWED_KEX_ECURVES Returns the list of elliptic curve specifications that are allowed by the server for the TLS V1.0, TLS V1.1 and TLS V1.2 server key exchange as a string consisting of 4-character decimal values. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for a list of valid 4-character elliptic curve or group specifications. GSK_SERVER_ALLOWED_KEX_ECURVES may be specified for an SSL environment or an SSL connection. gsk_attribute_set_buffer() - Add the following to the end of the "For TLS V1.0, ..." paragraph under the GSK_CLIENT_ECURVE_LIST entry of the Usage section: This attribute is ignored when Suite B has been enabled for the client. The supported elliptic curve values are defined by the Suite B profile being used. - Modify the following paragraph under the GSK_CLIENT_ECURVE_LIST entry of the Usage section: Only NIST recommended curves along with x25519 (0029) and x448 (0030) are able to be specified for this attribute. If x25519 or x448 is specified along with TLS V1.0, TLS V1.1 or TLS V1.2 and the partner server is using an ECDSA certificate, at least one other curve must be specified to match the elliptic curve in the partner's certificate. System SSL does not support x25519 or x448 certificates. If the application is only enabled for TLS V1.3, the secp192r1 (0019) and secp224r1 (0021) elliptic curves or supported groups are ignored. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for a list of valid 4-character elliptic curve or group specifications. - Add the following to the end under the GSK_CLIENT_ECURVE_LIST entry of the Usage section: To use Brainpool standard curve certificates for an SSL/TLS connection, the buffer must be reinitialized to NULL (empty) using either gsk_attribute_set_buffer() or the GSK_CLIENT_ECURVE_LIST environment variable. Brainpool certificates cannot be used in FIPS mode or if the selected protocol is TLS V1.3. When TLS V1.3 is enabled, a NULL (empty) list is not allowed. When executing in FIPS mode, a NULL (empty) list should not be utilized. A NULL (empty) list may result in an elliptic curve being selected or utilized by the partner that is not supported in FIPS mode. When executing in FIPS mode, non-FIPS elliptic curves will be removed to meet the requirements of the FIPS level being utilized. For information about FIPS mode level support, see Chapter: "System SSL and FIPS 140-2". - Add new entry to the Usage section: GSK_SERVER_ALLOWED_KEX_ECURVES Specifies the list of elliptic curve specifications that are allowed by the server for the TLS V1.0, TLS V1.1 and TLS V1.2 server key exchange when using ECDHE-based cipher suites as a string consisting of 1 or more 4-character decimal values. This list is used by the server to limit which elliptic curves can be used for the handshake key exchange when an ephemeral Elliptic Curve Diffie-Hellman (ECDHE) cipher is utilized. This attribute is ignored when Suite B has been enabled for the server. The allowed elliptic curve values are defined by the Suite B profile being used. If the server is enabled for sysplex session ID caching (GSK_SYSPLEX_SIDCACHE is set to ON), like servers in the sysplex must all be configured the same when running on V2R4 or later with the PTFs for OA61783 applied and active to minimize full handshakes. See Table: "Supported elliptic curve(group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for a list of valid 4-character supported elliptic curve and group specifications. The specified list will be tailored to meet the requirements of the FIPS level being utilized. For information about FIPS mode level support, see Chapter: "System SSL and FIPS140-2". GSK_SERVER_ALLOWED_KEX_ECURVES may be specified for an SSL environment or an SSL connection. gsk_environment_open() - Modify the following bullet under "When not executing in FIPS mode, the following default values are set:" in the Usage section: The supported elliptic curve list is set to "00210023002400250019" should be updated to: The supported client elliptic curve list is set to "00210023002400250019" - Add the following bullet under "When not executing in FIPS mode, the following default values are set:" in the Usage section: The allowed server elliptic curve list is set to "00230024002500210019". - Modify the following bullet under "When executing in FIPS mode, the following default values are set:" in the Usage section: The supported elliptic curve list is set to "00210023002400250019" should be updated to: The supported client elliptic curve list is set to "00210023002400250019" - Add the following bullet under "When executing in FIPS mode, the following default values are set:" in the Usage section: The allowed server elliptic curve list is set to "00230024002500210019". - Add environment variable under "These environment variables are processed list:" GSK_SERVER_ALLOWED_KEX_ECURVES Specifies the list of elliptic curves that are allowed by the server for the TLS V1.0, TLS V1.1 and TLS V1.2 server key exchange. gsk_secure_socket_init() - Add the following before the bullet "When using protocol TLS V1.1 and higher, any cipher suites that specify 40-bit export encryption." under the cipher selection section: When using protocol TLS V1.0, TLS V1.1 or TLS V1.2, any ephemeral elliptic curve (ECDHE) cipher suite is ignored if the client and server do not have a supported elliptic curve in common. The client provides its list of supported elliptic curves as part of the TLS handshake. If the server's certificate is ECDSA and does not match one of the client's elliptic curves or the server does not support at least one of the curves supported by the client, ECDHE cipher suites cannot be used. A z/OS System SSL client specifies the list of supported elliptic curves through the GSK_CLIENT_ECURVE_LIST setting. An empty list means all elliptic curves supported can be used. The FIPS setting may further restrict what curves can be used. A z/OS System SSL server specifies the list of supported elliptic curves through the GSK_SERVER_ALLOWED_KEX_ECURVES setting. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for the supported elliptic curve (group) definitions. Chapter: Messages and codes 9: Cryptographic processing error. - Update the Explanation section: Explanation: An error is detected by a cryptographic function. This error might also occur while running in FIPS mode when negotiating a secure connection in the following cases: - Using a non-FIPS key size - Using a non-FIPS elliptic curve - Using a triple DES cipher and the negotiated triple DES session key does not have three unique key parts - Modify the following paragraph under User response User response: If the error occurred while executing in FIPS mode, check that only FIPS key sizes and elliptic curves are used. If the error occurred during the establishment of a secure connection in FIPS mode using a triple DES cipher, retry the connection. If the problem persists, collect a System SSL trace containing the error and then contact your service representative. 402: No SSL cipher specifications. - Add the following bullet to the Explanation section after "Using Suite B mode and no required Suite B ciphers were specified.": Using protocol TLS V1.0, TLS V1.1 or TLS V1.2, any specified ephemeral elliptic curve (ECDHE) cipher suites are ignored if the client and server do not have a supported elliptic curve in common. - Add the following paragraph at the end of the User response section: If an ephemeral elliptic curve (ECDHE) cipher is expected to be used, ensure the client and server have a supported elliptic curve or group specification in common. The client provides its list of supported elliptic curves as part of the TLS handshake. If the server does not support at least one elliptic curve supported by the client, TLS_ECDHE cipher suites cannot be used. TLS_ECDHE_ECDSA cipher suites cannot be used if the server's certificate does not match one of the client's supported elliptic curves. A z/OS System SSL client specifies the list of supported elliptic curves through the GSK_CLIENT_ECURVE_LIST setting. An empty client list means all elliptic curves supported can be used. The FIPS setting may further restrict what elliptic curves can be used. A z/OS System SSL server specifies the list of supported elliptic curves through the GSK_SERVER_ALLOWED_KEX_ECURVES setting. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for supported curves or groups. 405: Certificate format is not supported. - Modify the first two paragraphs under User response: If an ECC certificate is received from the communication partner during a TLS V1.0, TLS V1.1, or TLS V1.2 handshake, the certificate's elliptic curve must be specified in the GSK_CLIENT_ECURVE_LIST environment variable or attribute type. System SSL does not support x25519 and x448 certificates. If the communication partner's certificate is either x25519 or x448, a different certificate must be provided. If a TLS V1.3 handshake is attempted, DSA, Diffie-Hellman and Elliptic Curve x25519 or x448 certificates are not allowed to be received from the communication partner. There are limitations on the key type and sizes that are allowed for TLS V1.3. See "gsk_secure_socket_init()" usage section for more information. The communication partner will need to provide a different certificate. 464: Elliptic curve list is not valid. - Update the Explanation section: The supported elliptic curve list is not formatted correctly or when running in FIPS mode, the removal of unsupported elliptic curves resulted in an empty list. -Update the User response section to the two listed paragraphs: Ensure the value that is supplied for GSK_CLIENT_ECURVE_LIST or GSK_SERVER_ALLOWED_KEX_ECURVES contains only entries for elliptic curves that are supported by System SSL. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for a list of supported elliptic curve definitions. Ensure that each entry uses 4 decimal digits. If enabled for FIPS mode, elliptic curves x25519 and x448 are not supported. The specified list may also be tailored to meet the requirements of the FIPS level being utilized. For information about FIPS mode level support, see Chapter: "System SSL and FIPS 140-2". Appendix: Environment variables GSK_CLIENT_ECURVE_LIST - Update the second paragraph of the Usage to the following: Only NIST recommended curves along with x25519 and x448 can be specified. If x25519 or x448 is specified along with TLS V1.0, TLS V1.1 or TLS V1.2 and the partner server is using an ECDSA certificate, the elliptic curve used in the server's certificate must appear in the list. This is due to z/OS System SSL not supporting x25519 or x448 certificates. - Add new environment variable entry: GSK_SERVER_ALLOWED_KEX_ECURVES Usage: Specifies the list of elliptic curve specifications that are allowed by the server for the TLS V1.0, TLS V1.1, and TLS V1.2 server key exchange when using TLS_ECDHE cipher suites as a string consisting of 1 or more 4-character values. See Table: "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" for a list of valid 4-character elliptic curve and group specifications. For the TLS V1.3 protocol, this setting is ignored and the server allowed elliptic curve specifications and groups are defined by the GSK_SERVER_TLS_KEY_SHARES setting. When a Suite B profile is defined, this setting is ignored. The server allowed elliptic curves are defined by the Suite B profile setting. For more information see "Suite B cryptography support". Valid values: The default specification is 00230024002500210019. Appendix : "Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3" - Add X's to the TLS V1.0, TLS V1.1, and TLS V1.2 columns for x25519 and x448. - Add the following entry to the Note: section TLS V1.0, TLS V1.1 and TLS V1.2 elliptic curves x25519 and x448 are only used for the key exchange portion of the handshake processing and not for certificates.
APAR Information
APAR number
OA61783
Reported component name
SYSTEM SSL
Reported component ID
565506805
Reported release
440
Status
CLOSED UR1
PE
NoPE
HIPER
NoHIPER
Special Attention
YesSpecatt / New Function / Xsystem
Submitted date
2021-07-19
Closed date
2023-04-12
Last modified date
2023-04-12
APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:
UJ08500 UJ08503 UJ08518 UJ08519
Modules/Macros
GSKAH010 GSKAH021 GSKC31 GSKC31F GSKC64 GSKC64F GSKCMS31 GSKCMS64 GSKHP002 GSKS31 GSKS31F GSKS64 GSKS64F GSKSSL GSKSSL64
| SC147495XX |
Fix information
Fixed component name
SYSTEM SSL
Fixed component ID
565506805
Applicable component levels
[{"Business Unit":{"code":"BU011","label":"Systems - zSystems software"},"Product":{"code":"SG19M"},"Platform":[{"code":"PF054","label":"z Systems"}],"Version":"440"}]
Document Information
Modified date:
13 April 2023