Figure 1 describes the basic structure of the elements that are needed in your System SSL source program.

Whether writing a server or client applications, the initial steps are the same. First, an SSL environment must be established with these function calls:

gsk_environment_open()

This is the first function call. It returns an environment handle that is used in all subsequent function calls. It also obtains storage and sets default values for all internal variables and picks up the values that are specified in system environment variables that override the built-in defaults.

gsk_attribute_set...()

One or more of these function calls are issued to set attribute values for the environment.

gsk_environment_init()

After you set all variables, issue this function call to complete the initialization of the SSL environment. When complete, you can open and close SSL connections.

Now, the client and server sides diverge. The server side sets up a listen environment. The listen environment is established by obtaining a socket descriptor through the socket() call and the activation of a connection through the bind(), listen() and accept() socket calls.When the listen environment is established, the server waits for notification that a secure socket connection is requested and issues these System SSL API function calls:

gsk_secure_socket_open()

This function call reserves a handle in which to store information for initializing each secure socket. Default values for each SSL connection are set from the environment.

gsk_attribute_set...()

This function call sets attribute values for this particular SSL connection. These values could include the socket file descriptor, ciphers, protocol, and application-supplied callback routines.

gsk_secure_socket_init()

For each connection to be started, the application must issue this function call to complete the initialization of the SSL connection and to run the SSL handshake protocol. The SSL handshake is a function of the System SSL support.

gsk_secure_socket_read()

One or more read function calls is issued until the inbound data flow is complete. The number of calls is purely application-dependent.

gsk_secure_socket_write()

One or more write function calls is issued until all appropriate data is sent to the partner. Reads and writes may be alternated as defined by the application protocol until the data flow is complete.

gsk_secure_socket_close()

This function call frees all the resources that are used for the SSL connection.

All of the SSL API function calls are thread-safe. This is useful on the server side, since each connection can be run on its own thread, simplifying application design. See the sample client/server program that is shipped with z/OS® System SSL, for an illustration of a multi-threaded application.

The client application then opens a connection to the server through the socket() and connect() calls and issues these System SSL API function calls:

gsk_secure_socket_open()

This function call reserves a handle in which to store information for initializing each secure socket.

gsk_attribute_set...()

This function call sets values for this particular SSL connection. These values could include the socket file descriptor, ciphers, protocol, and application-supplied callback routines.

gsk_secure_socket_init()

For each connection to be started, the application must issue this function call to complete the initialization of the SSL connection and to run the SSL handshake protocol. The SSL handshake is a function of the System SSL support.

gsk_secure_socket_write()

One or more write function calls are issued until the outbound data flow is complete. The number of calls is purely application-dependent.

gsk_secure_socket_read()

One or more read function calls are issued until all appropriate data is received from the partner. Writes and reads may be alternated as defined by the application protocol until the data flow is complete.

gsk_secure_socket_close()

This function call frees all the resources that are used for the SSL connection.

For both client and server applications, when the application is ready to end and all gsk_secure_socket_close() functions complete, destroy the sockets through the close() call and issue the gsk_environment_close() function call to close the SSL environment and return resources to the operating system.

In addition to using the previous SSL programming interfaces in an application, an application is not complete until a key database is available for use by the SSL application. The key database contains certificate information and is a z/OS UNIX System Services file that is built and managed using the gskkyman utility, a SAF key ring or a z/OS PKCS #11 token. For more information about key databases, see Certificate/Key management.

Figure 1. Sockets Programming Model Using System SSL