Adding support for  the Secure Socket Layer (SSL) to a web server is a complex
process.  For the OSU server, SSL is added as a filter between the tserver_tcp
network I/O module and main server code.

Files in the tserver_ssl_v2.zip distribution:
    tserver_ssl.c	Software shim that intercepts the TCP I/O and
			directs it through an SSL interpreter though
			ssl_server interface calls.

    ssl_server.h	Protoypes for ssl_server_interface:
			    tssl_initialize(error());
			    tssl_init_server_context ( 	*ctx, 
				get(),put(),err(), arg, max_io );
			    tssl_put_app_data ( ctx, data, length );
			    tssl_get_app_data ( ctx, *length, **data );
			    tssl_rundown_context ( ctx, flags );

    ssl_server_null.c	Null implementation of ssl_server, data is passed
			through transparently.  Useful for testing shareable
			image mechanisms.

    ssl_server_dnet.c	Implementation of ssl_server interface that uses
    ssl_server_dnet.opt a DECnet object to perform the SSL encryption.

    ssl_server_mst.c  	Implementation of ssl_server that creates an internal
    ssl_server_mst.opt  MST (service thread) to handle the SSL operations for
			each connection.

    /ssl.../bss_mst.c	BIO interface file for 

    /ssl.../ssl_threaded.c  Interfaces SSL library to ssl_server_mst module.

    link_tcpshare.com	Updated procedure to assist in linking tserver_tcpshr
			shareable images.

    wwwssl.com		DECnet task file, place this file in sys$login, it
			run ssl_task.exe.

Installation:
   The list below is a framework for setting up the SSL support provided
   by these files - mistakes and ommisions are likely.

   1. Convert http_server.exe to use the shareable image TCP/IP interface.
      There is no .COM for doing this, you must use (or emulate)
      MMS/MACRO=(SHARE_TCP=xxxx).

   2. Compile tserver_ssl.c, ssl_server_null.c, and ssl_server_dnet.c (you
      also need to be sure the existing decnet_access.c is compiled).
      These files should be placed in the [.base_code] sub-directory.

   3. To link null interface version use command:
	   @link_tcpshare ssl "" ssl_server_null.obj
      for dnet version:
	   @link_tcpshare ssl "" ssl_server_dnet/option
      for MST version:
	   @link_tcpshare ssl "" ssl_server_mst/option
	   
      In all cases, a file tserver_ssl.exe will be produced in your
      [.system] sub-directory.

   4. Define tserver_tcpshr as www_system:tserver_ssl.exe and
      tserver_ssl_transport as www_system:tserver_tcpshr.exe.  See
      ssl_setup.com for an example of the required logicals.

   5. When installed, odd-numbered listen ports (e.g. 443) activate the
      SSL filter and and event numbered ports are passed through.

   6. To build www_task.c you need a VMS distribution of SSLEAY 0.6.4, which 
      you must build on your own.  Read the code (actually the comments).


The original implementation of SLL for the web server looked like this:

    +-------------+     +-------------+
    | WWW client  |==1==| Tserver_TCP |
    +-------------+     +- - -(2)- - -+     +-------------+
                        | SSL shim    |==3==| SSL engine  |
                        +- - - - - - -+     +-------------+
                             : 2 :
                        +- - - - - - -+
                        | HTTP server |
                        +-------------+

Commuication paths:

    1. TCP/IP connection between WWW client and SSL shim.  Shim checks port
       number of connection (e.g. 80 or 443) and either relays data
       transparently to path 2 (HTTP server) or creates an SSL session
       over path 3.  For the SSL session path 1 binds to the 'R' channel
       and path 2 binds to the 'A' (application) channel.

    2. Multi-threaded TCP API defined by tserver_tcp.h.  Each new connection 
       creates a client thread to handle the HTTP request.

    3. Message-oriented network connection (DECnet) between shim and SSL object.
       This path uses a special protocol that multiplexes the SSL and 
       application data streams over the single network connection, 
       implemented as BIO class defined in BSS_RTCP.C.  On the shim side the 
       code is in SSL_SERVER_DNET.C.

To make the multithreaded version of the SSL engine, all I did was convert
path 3 to use a mechanism I created called an MST (message-based service 
thread).  An MST follows the same semantics as a DECnet logical link (designed
so specifically to facilitate conversion of DECnet objects to MSTs).  When a
thread writes to the MST link, the contents of it's data buffer is copied 
to the data buffer of corresponding read operation by the partner thread..

It's an interesting question whether to keep the architecture as it is or have
the shim bind the client and server paths directly to the SSL context.  An
MST imposes extra overhead (thread creation + data copying), but on the
other hand allows for parallel processing of the HTTP request with the
SSL encryption since there are 2 threads involved.  I was also concerned about
not knowing the stack consumption for the SSL library, an MST keeps that
issue independant of the HTTP client thread.

---------------------------------------------------------------------------
David L. Jones               |      Phone:    (614) 292-6929
Ohio State Unviversity       |      Internet:
2070 Neil Ave. Rm. 122       |               jonesd@kcgl1.eng.ohio-state.edu
Columbus, OH 43210           |               vman+@osu.edu