gtpm2m33Migration Guide: Program Update Tapes

Secure Sockets Layer (SSL) Support (APAR PJ27863)

The following section discusses the migration considerations for SSL support.

Prerequisite APARs

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

Functional Overview

The SSL protocol, which was originally developed for Web browsers, is a set of rules governing authenticated and encrypted communication between Transmission Control Protocol/Internet Protocol (TCP/IP) clients and servers. SSL is widely used on the Internet by an increasing number of varied applications, especially for interactions that involve exchanging confidential information such as credit card numbers. SSL evolved into the Transport Layer Security (TLS) version 1standard.

SSL is positioned as a protocol layer between the TCP layer and the application to form a secure connection between clients and servers so that they can communicate in a secure manner over a Transmission Control Protocol/Internet Protocol (TCP/IP) network by providing:

Figure 11 shows an example of a TCP/IP network using SSL.

Figure 11. TCP/IP Network Using SSL


This type of secure connection ensures that all data exchanged between clients and servers is encrypted, and is therefore not readable by a third party on the Internet. SSL has gained popularity in the Internet industry primarily because of its use of public-key certificates as a means of authenticating principals. The public-key certificates are a type of security exchange to secure the TCP connection between clients and servers. The exchange occurs after the TCP connection is established and an SSL session is started.

To establish the connection, SSL requires a server certificate, at a minimum. As part of the initial SSL handshake process, the server presents its certificate to the client to authenticate the server's identity. The authentication process uses public-key encryption and digital signatures to confirm that the server is, in fact, who the server claims to be (that is, that the server's certificate is valid). Once the server has been authenticated (that is, the client determines that the server's certificate is valid), the client and server use techniques of symmetric-key encryption to encrypt all the information they exchange for the remainder of the SSL session and message digests to detect any tampering that may have occurred. A different key is created for each client and server connection. As a result, even if unauthorized users intercept and decrypt a session key (which is unlikely), they cannot use it to monitor later SSL sessions.

SSL support on the TPF 4.1 system, which is based on the OpenSSL version 0.9.6 open source package, supports the following:

The OpenSSL open source package is available at http://www.openssl.org. This code was modified to work with the TPF 4.1 system. Therefore, it is important that you use the code modified and shipped by IBM.

Architecture

There are no changes.

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

There are no changes.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 1107 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 1107. Changes to General Use C/C++ Language Header Files for SSL Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments? Segments to Recompile
asn1.h New No Not Applicable
bio.h New No Not Applicable
blowfish.h New No Not Applicable
bn.h New No Not Applicable
buffer.h New No Not Applicable
cast.h New No Not Applicable
comp.h New No Not Applicable
crypto.h New No Not Applicable
des.h New No Not Applicable
dh.h New No Not Applicable
dsa.h New No Not Applicable
e_os2.h New No Not Applicable
evp.h New No Not Applicable
lhash.h New No Not Applicable
md2.h New No Not Applicable
md4.h New No Not Applicable
md5.h New No Not Applicable
mdc2.h New No Not Applicable
obj_mac.h New No Not Applicable
objects.h New No Not Applicable
opensslconf.h New No Not Applicable
opensslv.h New No Not Applicable
pem.h New No Not Applicable
pem2.h New No Not Applicable
pkcs7.h New No Not Applicable
rc2.h New No Not Applicable
rc4.h New No Not Applicable
ripemd.h New No Not Applicable
rsa.h New No Not Applicable
safestack.h New No Not Applicable
sha.h New No Not Applicable
ssl.h New No Not Applicable
ssl2.h New No Not Applicable
ssl23.h New No Not Applicable
ssl3.h New No Not Applicable
stack.h New No Not Applicable
synhacks.h New No Not Applicable
tls1.h New No Not Applicable
x509.h New No Not Applicable
x509_vfy.h New No Not Applicable

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

There are no changes.

Library Interface Scripts

There are no changes.

Link-Edited Modules

Table 1108 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 1108. Changes to Link-Edited Modules for SSL Support

Link-Edited Module New, Changed, or No Longer Supported? Description of Change
CRYP New Created for SSL support.
CRY1 New Created for SSL support.
CRY2 New Created for SSL support.
CSSL New Created for SSL support.

Members

There are no changes.

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.

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

There are no changes.

Data Macros

There are no changes.

General Macros

There are no changes.

Selected Equate Macros

There are no changes.

Structured Programming Macros (SPMs)

There are no changes.

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

Table 1109 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 1109. Changes to SIP Skeleton and Internal Macros for SSL 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 1110 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 1110. Changes to SIP Stage II Macros for SSL 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

There are no changes.

System Macros (IBM Use Only)

There are no changes.

Segments

There are no changes.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

There are no changes.

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

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 1111 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 1111. Changes to TPF Publications for SSL Support

Publication Title Softcopy File Name Description of Change
TPF Migration Guide: Program Update Tapes GTPMG205 Updated with migration considerations for SSL support.
TPF Transmission Control Protocol/Internet Protocol GTPCLW0B Added the APIs for SSL support.
SSL for the TPF 4.1 System: An Online User's Guide Not Applicable Created for the delivery of information for SSL support on the TPF 4.1 system.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

SSL support provides several new APIs. Table 1112 lists these APIs in alphanumeric order.

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

Table 1112. APIs for SSL Support

SSL_accept SSL_free SSL_set_verify
SSL_check_private_key SSL_get_cipher SSL_shutdown
SSL_connect SSL_get_error SSL_use_certificate_file
SSL_CTX_check_private_key SSL_get_peer_certificate SSL_use_PrivateKey_file
SSL_CTX_free SSL_get_verify_result SSL_use_RSAPrivateKey_file
SSL_CTX_load_verify_locations SSL_get_version SSL_write
SSL_CTX_new SSL_library_init SSLv2_client_method
SSL_CTX_set_cipher_list SSL_load_client_CA_file SSLv2_server_method
SSL_CTX_set_client_CA_list SSL_new SSLv23_client_method
SSL_CTX_set_default_passwd_cb_userdata SSL_pending SSLv23_server_method
SSL_CTX_set_verify SSL_read SSLv3_client_method
SSL_CTX_use_certificate_chain_file SSL_set_cipher_list SSLv3_server_method
SSL_CTX_use_certificate_file SSL_set_client_CA_list TLSv1_client_method
SSL_CTX_use_PrivateKey_file SSL_set_fd TLSv1_server_method
SSL_CTX_use_RSAPrivateKey_file    

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 PJ27863, which contains SSL support, on your TPF 4.1 system.

  1. Be sure 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. Put the C/C++ language header files listed in Table 1107 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.
  3. 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.
  4. Assemble the SIP Stage I deck to create a SIP Stage II deck.
  5. Run SIP Stage II.
  6. Load the link-edited modules listed in Table 1108.
  7. IPL your TPF 4.1 system.
  8. Enter ZTMSL ADD IBMSSLPR MAXECB-9999 MAXTIME-0 MINSUSP-0 RUNTIME-100 to define the time-slice name used by SSL support.
  9. If your TPF 4.1 system needs to send certificates to the remote application, do the following; otherwise, go to step 10.
    1. Create the files that contain certain public key and private key pairs for your TPF 4.1 system from a remote platform. These files are known as key files.
    2. Create the files that contain the certificates for your TPF 4.1 system from a remote platform. These files are known as certificate files.
    3. Load the files created in steps 9a and 9b to your TPF 4.1 system. You can use File Transfer Protocol (FTP) to load this information to your TPF 4.1 system.
    4. Define the file system permission bits for the key and certificate files so that the SSL applications can read these files. There are different ways to set the permission bits. For example, you can set permission bits so that all users can read the files, or define the files with specific user and group permissions and have the SSL applications define that user or group before issuing SSL API functions that read those files. Go to SSL for the TPF 4.1 System: An Online User's Guide for more information.
  10. If you want your TPF 4.1 system to verify the identity of remote nodes when SSL connections are started, do one of the following. Otherwise, go to step 11.
  11. Code your new applications to use the SSL APIs and convert existing TCP applications to use the SSL APIs, as appropriate.