Figure 1 shows the flow for one of
the most common SSL API calls when used in a shared SSL session environment:
an application reading data on a shared SSL session using the SSL_aor function. Figure 1. Read data using the SSL_aor function
Application program X issues SSL_aor to create a new entry control
block (ECB) when there is data available to read on the SSL session.
The SSL value (ssl_token1 in the figure), a pointer to 8 bytes of
data to pass to the new ECB (userd1 in the figure), and the name of
the application program to activate when there is no data to read
(prog Y in the figure) are passed to this function.
The SSL code issues the GSYSC macro to obtain a 4-KB block of
system heap. This block will be used to pass parameters from the
original application ECB to the SSL thread ECB, and then to the new
application ECB. The following information is set up in the block:
The API call to process, which is SSL_aor
The SSL value (ssl_token1 in the figure)
The 8-bytes of data to pass to the new ECB (userd1 in the figure)
The name of the application prorgram to activate in the new ECB
(prog Y in the figure)
The system virtual address (SVA) of this ECB
The database ID (DBI in the figure) of this ECB
The SSU and PBI of this ECB. This is needed to set up the new
application ECB.
The system heap block is added to the queue of tasks for shared
SSL sessions.
One of the SSL threads obtains control and pulls the first item
from the queue (the system heap block). This item indicates that the SSL_aor function
must be issued. The z/TPF system determines
that the SSL value (ssl_token1 in the figure) displayed in the SSL
session table (SSST) was passed and finds its entry to obtain the
real SSL value (ssl1 in the figure). The z/TPF system obtains the
file descriptor for the socket from the SSL structure for this SSL
session (fd1 in the figure).
The z/TPF system issues
the SSL_pending function to determine whether any data has been read
from the socket and not yet passed to the application. In this example,
the SSL_pending function returns 0, which indicates that
there is no data in the read buffer of this SSL session. If the return
code is greater than 0, step 6 is omitted, the new ECB is created,
and the process continues with step 7.
The SSL thread ECB issues the activiate_on_receipt_with_length function
on the socket. The following information is provided as input to
this API:
The file descriptor of the socket (fd1 in the figure)
The maximum length of data to receive
The name of the program to activate when the new ECB is created
(prog Z in the figure)
A pointer to 8 bytes of data to pass to the new ECB.
The z/TPF system posts
the application ECB, which returns to the application with a return
code of 1 to indicate that SSL_aor was accepted. Application
program X can now exit.
When there is data available to read on the SSL session, a new
ECB is created and program Z obtains control. The following information
is provided as input to the ECB:
File descriptor of the socket (fd1 in the figure).
Pointer to the system heap frame.
Program Z uses the information in the system heap block to
set up the DBI, SSU, and PBI of this ECB to match that of the original
application ECB. The SSL value (ssl_token1 in the figure) is then
copied from the system heap block to the EBW work area to pass to
the new application program. The name of the program to activate
(prog Y in the figure) is copied from the system heap block to a local
variable. The RSYSC macro is issued to return the system heap block
because it is no longer needed. Program Z now activates the application
program (prog Y in the figure).
The application program in the new ECB issues SSL_read to read
the data.
