gtpm2m34Migration Guide: Program Update Tapes

Shared SSL Session Support (APAR PJ28118)

The following section discusses the migration considerations for shared SSL session support.

Prerequisite APARs

See the APEDIT for APAR PJ28118 for information about prerequisite APARs.

Functional Overview

Secure Sockets Layer (SSL) support (APAR PJ27863) on the TPF 4.1 system, which is based on the OpenSSL version 0.9.6 open source package, supported the following:

See Secure Sockets Layer (SSL) Support (APAR PJ27863) for more information about SSL support.

Shared SSL session support provides the following enhancements to SSL support:

In addition, APAR PJ28021 adds support for the Berkeley Software Distribution (BSD) format of the select function through the tpf_select_bsd function. These functions are now supported:

Note:
BSD select (APAR PJ28021) is only required for Secure Web Server support. BSD select is not needed for shared SSL session support.

See TPF C/C++ Language Support User's Guide for more information about these functions.

Activate on Receipt (AOR) Capability for SSL

The SSL_aor function is new to the TPF 4.1 system. This function allows you to have thousands of shared SSL sessions without having thousands of active entry control blocks (ECBs). The SSL_aor function is modeled after the sockets activate_on_receipt function. Go to SSL for the TPF 4.1 System: An Online User's Guide for more information about these functions.

Secure Web Server Support

Support has been added for the mod_ssl module in Apache.

Shared SSL Sessions

Shared SSL sessions increase the scalability and usability of the code by allowing SSL sessions to be shared by ECBs in the TPF 4.1 system. For example, ECB 1 can read an input message on a shared SSL session and ECB 2 can send the output message across that same SSL session.

SSL Diagnostic Tools

SSL diagnostic tools provide statistical information about SSL sessions. You can display this statistical information by using the ZSSLD command. Go to SSL for the TPF 4.1 System: An Online User's Guide for more information about this command.

The following statistical information is maintained:

Architecture

SSL support (APAR PJ27863) enabled TPF applications to use SSL. The OpenSSL version 0.9.6 open source package that was ported ties an SSL session to a specific process. For the TPF 4.1 system, this means a given SSL session is owned by a specific ECB and all information about that SSL session resides in heap storage associated with that ECB. This ECB is the only one that can issue any SSL APIs for that SSL session. If the ECB exits for any reason, the SSL session is ended.

In a distributed application environment that includes the TPF 4.1 system, multiple ECBs have the ability to share a TCP/IP socket. Shared SSL session support extends this capability to allow multiple ECBs to share an SSL session, or to have the ability to pass an SSL session from one ECB to another ECB. When the application creates an SSL session, the session can be defined as shared or not shared. For SSL sessions defined as not shared, there are no changes and the session is still tied to a single ECB. SSL daemon processes manage SSL sessions that are created as shared. Any application (ECB) can issue an SSL API for a shared SSL session. Shared SSL sessions are not tied to an application ECB, meaning that the SSL session can remain active even if there are no active application ECBs.

TCP/IP support created a unique socket API called activate_on_receipt (AOR) that allows the calling ECB to exit, a new ECB to be created, and the specified application to be activated when data arrives on the socket. No ECBs are tied up while waiting for data to arrive. Shared SSL session support provides a similar ability for SSL sessions. A new TPF-unique SSL API called SSL_aor is created that provides the same functions to SSL sessions that activate_on_receipt provides for sockets.

Operating Environment Requirements and Planning Information

There are no changes.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

Table 1113 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 1113. Changes to Build Scripts for Shared SSL Session Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CTALBS LLM Changed Updated for shared SSL session support.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 1123 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 1114. Changes to General Use C/C++ Language Header Files for Shared SSL Session Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments? Segments to Recompile
c$ck2sn.h Changed No Not Applicable
c$eb0eb.h Changed No Not Applicable
ssl.h Changed No Not Appilcable
sysapi.h Changed Yes Any application that uses shared SSL session support.
sysgtime.h Changed No Updated for APAR PJ28021 to add support for the BSD format of the select function through the tpf_select_bsd function.
time.h Changed No Updated for APAR PJ28021 to add support for the BSD format of the select function through the tpf_select_bsd function.

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

Table 1115 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 1115. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for Shared SSL Session Support

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments? Segments to Recompile
i$issl.h New No Not Applicable

Library Interface Scripts

Table 1116 summarizes changes to the library interface scripts used by the library interface tool and the build tool. This information is presented in alphabetic order by the name of the library interface script.

Table 1116. Changes to Library Interface Scripts for Shared SSL Session Support

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CTALXV Changed Updated for shared SSL session support.
C551 New Updated for shared SSL session support.

Link-Edited Modules

Table 1117 summarizes changes to the link-edited modules shipped by IBM, which should go into a data set with attributes DCB=(RECFM=U,LRECL=80,BLKSIZE=1200). This information is presented in alphabetic order by the name of the link-edited module.

Table 1117. Changes to Link-Edited Modules for Shared SSL Session Support

Link-Edited Module New, Changed, or No Longer Supported? Description of Change
CSSL Changed Updated for shared SSL session support.
CSL0 New Created for shared SSL session support.
CSL1 New Created for shared SSL session support.
CSL2 New Created for shared SSL session support.
CSL3 New Created for shared SSL session support.
CSL4 New Created for shared SSL session support.
CSL5 New Created for shared SSL session support.
CSL6 New Created for shared SSL session support.
CSL7 New Created for shared SSL session support.
CSL8 New Created for shared SSL session support.
CSL9 New Created for shared SSL session support.
CSLA New Created for shared SSL session support.

Members

Table 1118 summarizes changes to members. This information is presented in alphabetic order by the name of the member.

Notes:

  1. You must recompile or reassemble a member if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 1118. Changes to Members for Shared SSL Session Support

Member DLM/DLL/LLM Name Type New, Changed, or No Longer Supported? Member Type Description of Change
CMOVE2 CTAL LLM New Real-Time Assembler Created for shared SSL session support.
COFLOK CISO LLM Changed Object Code Only Updated to add shared SSL session support.
C551 COMX LLM New C++ Language Created for shared SSL session support.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

There are no changes. Table 1119 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 1119. Changes to Copy Members for Shared SSL Session Support

Copy Member Type New, Changed, or No Longer Supported? Segment Where Copy Member is Included Name of Link-Edited Module DLM, DLL, LLM, or Control Program Description of Change
CCEB Control Program Changed CCENBK CPS0 Control Program Updated to add shared SSL session support.
CICS Control Program Changed CCNUCL CPS0 Control Program Updated to add shared SSL session support.
CISO Control Program Changed CCISOC CPS0 Control Program Updated to add shared SSL session support.
CLHV Control Program Changed CCSTOR CPS0 Control Program Updated to add shared SSL session support.
CTH0 Control Program Changed CCTHDS CPS0 Control Program Updated to add shared SSL session support.
CTH2 Control Program Changed CCTHDS CPS0 Control Program Updated to add shared SSL session support.
CTI2 Control Program Changed CCTCP2 CPS0 Control Program Updated to add shared SSL session support.
CTSM Control Program Changed CCTCP3 CPS0 Control Program Updated to add shared SSL session support.
CTT6 Control Program Changed CCTCP1 CPS0 Control Program Updated to add shared SSL session support.
CT40 Control Program Changed CCCTIN CPS0 Control Program Updated to add shared SSL session support.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

Table 1120 summarizes changes to the communication macros and statements. This information is presented in alphabetic order by the name of the SNA communication macro or statement.

Table 1120. Changes to Communication Macros and Statements for Shared SSL Session Support

Communication Macro or Statement New, Changed, or No Longer Supported? Do You Need to Reassemble Programs? Programs to Reassemble
SNAKEY Changed Yes CTK2

Data Macros

Table 1121 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 1121. Changes to Data Macros for Shared SSL Session Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro? Programs to Reassemble
CK2SN Changed No Not Applicable
IEQCE2 Changed No Not Applicable
ISOCK Changed No Not Applicable

General Macros

There are no changes.

Selected Equate Macros

Table 1122 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 1122. Changes to Selected Equate Macros for Shared SSL Session Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs? Programs to Reassemble
CZ1SE Changed No Not Applicable

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 1123 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 1123. Changes to SIP Skeleton and Internal Macros for Shared SSL Session Support

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 1124 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 1124. Changes to SIP Stage II Macros for Shared SSL Session Support

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

Table 1125 summarizes system macro changes. This information is presented in alphabetic order by the name of the system macro. See TPF System Macros for a complete description of all system macros.

Table 1125. Changes to System Macros for Shared SSL Session Support

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs? Programs to Reassemble
$MOVEC Changed No Not Applicable

System Macros (IBM Use Only)

Table 1126 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 1126. Changes to System Macros (IBM Use Only) for Shared SSL Session Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs? Programs to Reassemble
DLTEC Changed Yes All segments that reference DLTEC.

Segments

Table 1127 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 1127. Changes to Segments for Shared SSL Session Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CCCTIN CSECT Not Applicable No Changes - Must reassemble though because copy members in CCCTIN were updated. Updated to add shared SSL session support.
CCENBK CSECT Not Applicable Changed Updated to add shared SSL session support.
CCNUCL CSECT Not Applicable No Changes - Must reassemble though because copy members in CCNUCL were updated. Updated to add shared SSL session support.
CCTCP1 CSECT Not Applicable No Changes - Must ressemble though because copy members in CCTCP1 were updated. Updated to add shared SSL session support.
CCTCP2 CSECT Not Applicable No Changes - Must reassemble though because copy members in CCTCP2 were updated. Updated to add shared SSL session support.
CCTCP3 CSECT Not Applicable No Changes - Must reassemble though because copy members in CCTCP3 were updated. Updated to add shared SSL session support.
CCTHDS CSECT Not Applicable No Changes - Must reassemble though because copy members in CCTHDS were updated. Updated to add shared SSL session support.
CSK0 Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
csslac C Language Not Applicable New Created for shared SSL session support.
cssalo C Language Not Applicable New Created for shared SSL session support.
csslar C Language Not Applicable New Created for shared SSL session support.
csslcf C Language Not Applicable New Created for shared SSL session support.
csslch C Language Not Applicable New Created for shared SSL session support.
csslcs C Language Not Applicable New Created for shared SSL session support.
csslcy C Language Not Applicable New Created for shared SSL session support.
csslgc C Language Not Applicable New Created for shared SSL session support.
csslls C Language Not Applicable New Created for shared SSL session support.
csslmg C Language Not Applicable New Created for shared SSL session support.
csslmt C Language Not Applicable New Created for shared SSL session support.
csslns C Language Not Applicable New Created for shared SSL session support.
csslnw C Language Not Applicable New Created for shared SSL session support.
csslqo C Language Not Applicable New Created for shared SSL session support.
csslqt C Language Not Applicable New Created for shared SSL session support.
csslrc C Language Not Applicable New Created for shared SSL session support.
csslrd C Language Not Applicable New Created for shared SSL session support.
csslrs C Language Not Applicable New Created for shared SSL session support.
csslrt C Language Not Applicable New Created for shared SSL session support.
csslr2 C Language Not Applicable New Created for shared SSL session support.
csslsf C Language Not Applicable New Created for shared SSL session support.
csslsn C Language Not Applicable New Created for shared SSL session support.
csslus C Language Not Applicable New Created for shared SSL session support.
csslwb C Language Not Applicable New Created for shared SSL session support.
csslwr C Language Not Applicable New Created for shared SSL session support.
csslwt C Language Not Applicable New Created for shared SSL session support.
csslzd C Language Not Applicable New Created for shared SSL session support.
csslzs C Language Not Applicable New Created for shared SSL session support.
CTKO Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTKR Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTKT Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTSA Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTSC Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTSQ Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTS5 Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTS6 Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CTS8 Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
CVAB Real-Time Assembler Not Applicable Changed Updated to add shared SSL session support.
ssl_lib C++ Language Not Applicable Changed Updated to add shared SSL session support.
ssl_rsa C++ Language Not Applicable Changed Updated to add shared SSL session support.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

Table 1128 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for more information about the ZNKEY command. Go to http://www.ibm.com/tpf/pubs/tpfpubs.htm and click SSL for the TPF 4.1 System: An Online User's Guide for more information about the ZSSLD command.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 1128. Changes to Commands for Shared SSL Session Support

Command New, Changed, or No Longer Supported? Description of Change
ZNKEY Changed Added the SSLPROC and SSLTHRD parameters. Updated the SOCKSWP parameter for the SSL socket sweeper.
ZSSLD New Created to manage SSL daemon processes.

Messages and System Errors

Table 1129 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. Go to SSL for the TPF 4.1 System: An Online User's Guide for more information about these messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 1129. Changes to Messages and System Errors for Shared SSL Session Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
007820 System Error New
SSLD0001I Online New
SSLD0002I Online New
SSLD0003I Online New
SSLD0004I Online New
SSLD0005I Online New
SSLD0007I Online New
SSLD0008I Online New
SSLD0010I Online New
SSLD0011I Online New
SSLD0020E Online New
SSLD0021E Online New
SSLD0022E Online New
SSLD0023E Online New
SSLD0024E Online New
SSLD0025E Online New
SSLD0026E Online New
SSLD0030E Online New
SSLD0032E Online New
SSLD0040E Online New
SSLD0041E Online New
SSLD0050E Online New
SSLD0051E Online New
SSLD0052E Online New
SSLD0053E Online New
SSLD0054I Online New

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

The following updates may be needed:

See TPF Operations for more information about the ZCTKA ALTER command.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 1130 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 1130. Changes to TPF Publications for Shared SSL Session Support

Publication Title Softcopy File Name Description of Change
TPF ACF/SNA Network Generation GTPACF0E Updated the existing SNAKEY macro to include the new SSLPROC and SSLTHRD parameters. The existing SOCKSWP parameter was also updated.
TPF C/C++ Language Support User's Guide GTPCLU0F Added the new tpf_movec_EVM function and updated the existing tpf_movec function for shared SSL session support.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for shared SSL session support.
TPF Migration Guide: Program Update Tapes GTPMG205 Updated with migration considerations for shared SSL session support.
TPF Operations GTPOPR0F Updated with information about the commands that were added and changed for shared SSL session support.
TPF Program Development Support Reference GTPPDR0F Added the new SSL dump label for shared SSL session support.
TPF System Macros GTPSYS0F Updated the existing $MOVEC macro for shared SSL session support.
TPF Transmission Control Protocol/Internet Protocol GTPCLW0B Added the APIs for shared SSL session support and updated SSL support APIs that were modified by shared SSL session support.
SSL for the TPF 4.1 System: An Online User's Guide Not Applicable Updated with information for shared SSL session support.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

Shared SSL session support provides the following new APIs:

  • SSL_aor
  • SSL_CTX_load_and_set_client_CA_list
  • SSL_CTX_new_shared
  • SSL_get_session
  • SSL_load_and_set_client_CA_list
  • SSL_renegotiate
  • SSL_set_session
  • tpf_movec_EVM.

Shared SSL session support updated the following APIs:

  • SSL_CTX_check_private_key
  • SSL_CTX_free
  • SSL_CTX_load_verify_locations
  • SSL_CTX_new
  • SSL_CTX_set_cipher_list
  • SSL_CTX_set_client_CA_list
  • SSL_CTX_set_default_passwd_cb_userdata
  • SSL_CTX_set_verify
  • SSL_CTX_use_certificate_chain_file
  • SSL_CTX_use_certificate_file
  • SSL_CTX_use_PrivateKey_file
  • SSL_CTX_use_RSAPrivateKey_file
  • SSL_get_peer_certificate
  • SSL_load_client_CA_file
  • SSL_new
  • SSL_read
  • SSL_set_cipher_list
  • SSL_set_client_CA_list
  • SSL_use_certificate_file
  • SSL_use_PrivateKey_file
  • SSL_use_RSAPrivateKey_file
  • SSL_write
  • SSLv2_client_method
  • SSLv2_server_method
  • SSLv23_client_method
  • SSLv23_server_method
  • SSLv3_client_method
  • SSLv3_server_method
  • tpf_movec
  • TLSv1_client_method
  • TLSv1_server_method.

To view information about these APIs, go to SSL for the TPF 4.1 System: An Online User's Guide

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Use the following procedure to install APAR PJ28118, which contains shared SSL session support, on your TPF 4.1 system.

  1. Ensure TCP/IP native stack support (APAR PJ26683) is installed on your TPF 4.1 system. See Chapter 13 in TPF Migration Guide: Program Update Tapes for more information.
  2. Ensure SSL support (APAR PJ27863) is installed on your TPF 4.1 system. See Chapter 17 in TPF Migration Guide: Program Update Tapes for more information.
  3. Put the C/C++ language header files listed in Table 1123 in the \openssl\include subdirectory of your library system. You will need to use these header files to compile applications that use the SSL APIs.
  4. Run the system allocator (SALO) using IBMPAL and SPPGML additions for newly created segments to create an updated program allocation table (PAT) and system allocator (SAL) table.
  5. Assemble the SIP Stage I deck to create a SIP Stage II deck.
  6. Run SIP Stage II.
  7. Load the link-edited modules listed in Table 1117.
  8. IPL your TPF 4.1 system.
  9. Define the SSL daemon processes by coding the SSLPROC and SSLTHRD parameters on the SNAKEY macro in CTK2. See TPF ACF/SNA Network Generation for more information about these new parameters and the SNAKEY macro.
  10. Enable threads on your TPF 4.1 system by doing the following:
    • Enter the ZCTKA ALTER command with the MTHD parameter specified to change the maximum number of threads allowed for a process. The value specified must be the value of the SSLTHRD parameter plus 1 or higher.
    • Enter the ZCTKA ALTER command with the TSTK parameter specified to change the number of 4-KB ISO-C stack frames for a thread.

    See TPF Operations for more information about the ZCTKA ALTER command.

  11. Load the updated CTK2 to your TPF 4.1 system.
  12. Create the shared SSL configuration file, /etc/sslshared.txt, if you want to assign specific applications to one or more specific SSL daemon processes.
  13. Modify any existing applications or code new applications to create shared SSL sessions using the SSL_CTX_new_shared function. You can optionally use the SSL_aor function. Go to SSL for the TPF 4.1 System: An Online User's Guide for more information about these new APIs.
  14. Recompile any applications that were written using SSL support that issue the SSL_get_cipher function if, and only if, you want that application to use shared SSL sessions.