PJ46661: Server name indication (SNI) and TLS cipher preference changes for Transport Layer Security.

APAR status

• Closed as new function.

Error description

• See Problem Summary.
  

Local fix

• NA
  

Problem summary

• APAR NUMBER:  PJ46661
  PRODUCT:  z/TPF
  FUNCTIONAL AREA:  SECURE SOCKETS LAYER
  SHIPPED IN YEAR:  2022
  
  ABSTRACT:
  Server name indication (SNI) and TLS cipher preference changes
  for Transport Layer Security.
  
  PACKAGE CONTENTS:
  Source Segments:
  (C) base/include/tpf/c_ck2sn.h
  (C) base/macro/ck2sn.mac
  (C) base/macro/snakey.mac
  (C) base/openssl/ssl/ssl_lib.c
  (C) base/openssl/tpfssl/csslwb.c
  (C) base/openssl/tpfssl/headers/tpf/i_issl.h
  (C) base/openssl/tpfssl/headers/tpf/tpf_ssl_lib.h
  (C) base/openssl/tpfssl/tpf_ssl_cssl.c
  (C) base/rt/csk0.asm
  (C) base/rt/ept_connect.cpp
  (C) base/rt/httpSendUtils.c
  
  Object Only Binaries:
  None.
  
  BINARIES TO BUILD: YES
  Configuration Independent Binaries:
  (C) base/lib/libCHTE.so
  (C) base/load/CDMF.so
  (C) base/load/CHTE.so
  (C) base/load/CSK0.so
  (C) base/obj/csk0.o
  (C) base/obj/ept_connect.o
  (C) base/obj/httpSendUtils.o
  (C) base/openssl/lib/libCSSL.so
  (C) base/openssl/load/CSL2.so
  (C) base/openssl/load/CSSL.so
  (C) base/openssl/obj/csslwb.o
  (C) base/openssl/obj/ssl_lib.o
  (C) base/openssl/obj/tpf_ssl_cssl.o
  
  Configuration Dependent Binaries:
  None.
  
  
  COMMENTS:
  The server name indication (SNI) is a TLS extension that might
  be required for z/TPF clients when communicating with remote
  servers. This extension, when specified by the TLS client
  before the TLS handshake takes place, indicates the hostname of
  the server it connected to. If the SNI extension is required by
  a server the handshake cannot succesfully complete when it is
  not specified. The SSL_set_tlsext_host_name() and
  SSL_get_servername() APIs that are used to set and get the
  server name indicator are currently not supported for z/TPF
  shared SSL sessions and subsequently any middleware packages
  that use shared SSL.
  
  In addition, OpenSSL uses the client's preference when
  negotiating ciphers and establishing a TLS connection. The
  server's cipher preference can be used by issuing either the
  SSL_set_options or SSL_CTX_set_options APIs in the server
  application, however these APIs are not supported for shared
  SSL.
  

Problem conclusion

• SOLUTION:
  The SSL_set_tlsext_host_name() and SSL_get_servername() APIs
  are added and supported in shared SSL. In addition, the
  following middleware packages automatically set the hostname by
  issuing the SSL_set_tlsext_host_name() API when a hostname is
  provided:
  -High-Speed connector
  -Enhanced HTTP Client using HSC (persistent sessions)
  -Enhanced HTTP Client using non-persistent sessions
  
  A global option has been added to keypoint 2 (ctk2.asm) that
  allows TLS sessions established to a z/TPF server to either
  negotiate using the client's cipher preference (default) or the
  z/TPF server's cipher preference. This option is modified by
  updating ctk2.asm and reloading the keypoint or by issuing the
  ZNKEY command to modify the value. The z/TPF global option was
  provided so client application code and middleware do not need
  to be updated to set the session to use the server's cipher
  preference. Modification of the server's cipher preference
  takes place immediately and will be honored for all subsequent
  TLS server sessions established.
  
  COREQS: NO
  None.
  
  MIGRATION CONSIDERATIONS: YES
  Functional, automation, and operation changes:
  The following command was changed: ZNKEY
  
  Application programming interface (API) changes:
  Two new Shared SSL APIs were added: SSL_set_tlsext_host_name
  and SSL_get_servername
  
  Hardware, software, and configuration changes:
  If this APAR is installed using the z/TPF e-type loader, the
  z/TPF shared SSL daemons must be stopped and restarted (ZSSLD
  STOP/ZSSLD START) or recycled (ZSSLD RECYCLE) after installing
  the APAR.
  
  Communications changes:
  You can issue the ZNKEY SSLSERVP command to change the cipher
  list preference from using the client's cipher list to the
  server's cipher list. By default, TPF SSL servers will
  prioritize the client's cipher list preference.  Keypoint 2 is
  processor unique, so modifying the value using ZNKEY would need
  to be done for each processor in a loosely-coupled complex.
  
  If you were to change the default value for SSLSERVP with the
  ZNKEY SSLSERVP command, you must change the SSLSERVP value for
  the customer version of ctk2.asm to ensure that subsequent
  loads of keypoint 2 set the desired value for SSLSERVP instead
  of the default value.
  
  
  
  BUILD COMMANDS AND INSTRUCTIONS: YES
  #maketpf commands for linux
  maketpf -f CSK0 csk0.o
  maketpf -f CSSL ssl_lib.o tpf_ssl_cssl.o
  maketpf -f CSL2 csslwb.o
  maketpf -f CDMF ept_connect.o
  maketpf -f CHTE httpSendUtils.o
  maketpf CSK0 link
  maketpf CSSL link
  maketpf CSL2 link
  maketpf CDMF link TPF_VERIFY_LINK_REFS=NO
  maketpf CHTE link
  maketpf CDMF link
  
  UPDATED INFORMATION UNITS: YES
  z/TPF and z/TPFDF Migration Guide: PUT 2 and Later
  z/TPF ACF/SNA Network Generation
  z/TPF C/C++ Language Support User's Guide
  z/TPF Deployment Descriptors
  z/TPF Operations
  z/TPF Security
  
  See your IBM representative if you need additional information.
  
  DOWNLOAD INSTRUCTIONS:
  https://www.ibm.com/support/docview.wss?uid=swg27049604
  
  APAR URL:
  https://transfer.boulder.ibm.com/2022/PJ46661.tar.gz
  

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

• Fixed component name

  Z/TPF

• Fixed component ID

  5748T1501

Applicable component levels