PH29466: DOC APAR - CSQX620E FUNCTION 'GSK_SECURE_SOCKET_INIT' RC=456

APAR status

• Closed as documentation error.

Error description

• Setting Environment Variables for SSL tasks needs explanation
  within the Knowledge Center
  
  When using MQ with an elliptic curve key exchange cipher, the
  GSK_CLIENT_ECURVE_LIST value determines which elliptic curve is
  used for the key exchange. This ENVAR could not be modified
  using the standard means (CEEOPTS DD statement).
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of IBM MQ for z/OS Version 9       *
  *                 Release 1 Modification 0 and Release 2       *
  *                 Modification 0.                              *
  ****************************************************************
  * PROBLEM DESCRIPTION: When using MQ with an elliptic curve    *
  *                      key exchange cipher, and a system       *
  *                      restriction on the key size used, a     *
  *                      CSQX620E error message can occur        *
  *                      during handshaking if the key size      *
  *                      selected from GSK_CLIENT_ECURVE_LIST    *
  *                      is too small.                           *
  ****************************************************************
  There exists no documentation providing instructions to
  modify GSK_CLIENT_ECURVE_LIST to apply to all
  SSLTASKS defined for a QMGR.
  
  If using the CEEOPTS DD statement with in-stream data,
  it was found that the new value for environment variables
  was not propagated across all SSL tasks.
  

Problem conclusion

• A new page has been added to the Knowledge Center
  to provide instructions for modifying GSK_CLIENT_ECURVE_LIST,
  and ensuring it is set for all SSL tasks.
  
  ========== DOC Change for V910 Knowledge Center ===============
  
  The page "Modifying Elliptic Curve Key Length on z/OS" for
  v9.1.0 will be added to the Knowledge Center:
  
  Home
  > IBM MQ 9.1.x
    > IBM MQ
      > Securing
        > Setting up security
          > Working with SSL/TLS
            > Working with SSL/TLS on z/OS
              > Modifying Elliptic Curve Key Length on z/OS:
  
  (with the following content):
  
  Modify the GSK_CLIENT_ECURVE_LIST environment variable to set
  the list of elliptic curves or supported groups that are
  specified by the client as a string consisting of 1 or more
  4-character values in order of preference for use.
  
  This SSL environment variable can be set in the CHINIT startup
  JCL via the CEEOPTS DD statement:
  {{{
  CEEOPTS DD DSN=<dataset-name>,DISP=SHR
  }}}
  In the dataset referenced above, specify the list that you wish
  to use, for example:
  {{{
  ENVAR('GSK_CLIENT_ECURVE_LIST=002300240025')
  }}}
  
  NOTE: Do not use this CEEOPTS statement with in-stream data, as
  this will prevent the environment variable from being set for
  all SSL tasks using it. Make sure to reference a sequential
  dataset, or partitioned dataset member to allow this to work
  when using an SSLTASKS value greater than 1.
  See Table 5 (link: https://www.ibm.com/support/knowledgecenter/
  SSLTBW_2.4.0/com.ibm.zos.v2r4.gska100/csdcwh.htm#csdcwh__tttcsd)
  for a list of valid 4-character elliptic curve and supported
  groups specifications.
  
  The default specification is 00210023002400250019. If TLS V1.3
  is enabled, 0029 (x25519) is appended to the end of the default
  list.
  
  ========== DOC Change for V920 Knowledge Center ===============
  
  The page "Modifying Elliptic Curve Key Length on z/OS" for
  v9.2.0 will be added to the Knowledge Center:
  
  Home
  > IBM MQ 9.2.x
    > IBM MQ
      > Securing
        > Setting up security
          > Working with SSL/TLS
            > Working with SSL/TLS on z/OS
              > Modifying Elliptic Curve Key Length on z/OS:
  
  (with the following content):
  
  Modify the GSK_CLIENT_ECURVE_LIST environment variable to set
  the list of elliptic curves or supported groups that are
  specified by the client as a string consisting of 1 or more
  4-character values in order of preference for use.
  
  This SSL environment variable can be set in the CHINIT startup
  JCL via the CEEOPTS DD statement:
  {{{
  CEEOPTS DD DSN=<dataset-name>,DISP=SHR
  }}}
  In the dataset referenced above, specify the list that you wish
  to use, for example:
  {{{
  ENVAR('GSK_CLIENT_ECURVE_LIST=002300240025')
  }}}
  
  NOTE: Do not use this CEEOPTS statement with in-stream data, as
  this will prevent the environment variable from being set for
  all SSL tasks using it. Make sure to reference a sequential
  dataset, or partitioned dataset member to allow this to work
  when using an SSLTASKS value greater than 1.
  See Table 5 (link: https://www.ibm.com/support/knowledgecenter/
  SSLTBW_2.4.0/com.ibm.zos.v2r4.gska100/csdcwh.htm#csdcwh__tttcsd)
  for a list of valid 4-character elliptic curve and supported
  groups specifications.
  
  The default specification is 00210023002400250019. If TLS V1.3
  is enabled, 0029 (x25519) is appended to the end of the default
  list.
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

Applicable component levels