APACHE 2.0 STATUS:                                              -*-text-*-

Last modified at [$Date: 2002/05/30 05:54:43 $]

Last modified at [$Date: 2002/05/30 06:02:15 $]

Release:

        registered apr_atexit() fn's that have the return code as an

        argument to the registered fn.

    * Port of mod_ssl to Apache 2.0:

      The current porting state is summarized in modules/ssl/README. The

      remaining work includes:

      (1) stablizing/optimizing the SSL filter logic

      (2) Enabling SSL extentions

      (3) Trying to seperate the https filter logic from mod_ssl -

          This is to facilitate other modules that wish to use the https

          filter or the mod_ssl logic or both as required.

    * Eliminate unnecessary creation of pipes in mod_cgid

    * Combine log_child and piped_log_spawn. Clean up http_log.c.

                      _             _ 

  _ __ ___   ___   __| |    ___ ___| |

 | '_ ` _ \ / _ \ / _` |   / __/ __| | 

 | | | | | | (_) | (_| |   \__ \__ \ | ``mod_ssl combines the flexibility of

 |_| |_| |_|\___/ \__,_|___|___/___/_|   Apache with the security of OpenSSL.''

                      |_____|                                           

 mod_ssl                               ``Ralf Engelschall has released an

 Apache Interface to OpenSSL             excellent module that integrates

 http://www.modssl.org/                  Apache and SSLeay.''                 

 Version 2.8                                               -- Tim J. Hudson

 SYNOPSIS

 This Apache module provides strong cryptography for the Apache 1.3 webserver

 via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS

 v1) protocols by the help of the SSL/TLS implementation library OpenSSL which

 is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package

 was created in April 1998 by Ralf S. Engelschall and was originally derived

 from software developed by Ben Laurie for use in the Apache-SSL HTTP server

 project. 

 SOURCES

 Here is a short overview of the source files:

 * README .................. This file ;)

 # Makefile.in ............. Makefile template for Unix platform

 # config.m4 ............... Autoconf stub for the Apache config mechanism

 # mod_ssl.c ............... main source file containing API structures

 # mod_ssl.h ............... common header file of mod_ssl

 # ssl_engine_config.c ..... module configuration handling

 # ssl_engine_dh.c ......... DSA/DH support

 # ssl_engine_init.c ....... module initialization

 # ssl_engine_io.c ......... I/O support

 # ssl_engine_kernel.c ..... SSL engine kernel

 # ssl_engine_log.c ........ logfile support

 # ssl_engine_mutex.c ...... mutual exclusion support

 # ssl_engine_pphrase.c .... pass-phrase handling

 # ssl_engine_rand.c ....... PRNG support

 # ssl_engine_vars.c ....... Variable Expansion support

 # ssl_expr.c .............. expression handling main source

 # ssl_expr.h .............. expression handling common header

 # ssl_expr_scan.c ......... expression scanner automaton (pre-generated)

 # ssl_expr_scan.l ......... expression scanner source

 # ssl_expr_parse.c ........ expression parser automaton  (pre-generated)

 # ssl_expr_parse.h ........ expression parser header     (pre-generated)

 # ssl_expr_parse.y ........ expression parser source

 # ssl_expr_eval.c ......... expression machine evaluation

 # ssl_scache.c ............ session cache abstraction layer

 # ssl_scache_dbm.c ........ session cache via DBM file

 ~ ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer

 ~ ssl_scache_shmht.c ...... session cache via shared memory hash table

 # ssl_util.c .............. utility functions

 # ssl_util_ssl.c .......... the OpenSSL companion source

 # ssl_util_ssl.h .......... the OpenSSL companion header

 # ssl_util_table.c ........ the hash table library source

 # ssl_util_table.h ........ the hash table library header

 Legend: # = already ported to Apache 2.0 and is cleaned up

         * = ported to Apache 2.0 but still needs cleaning up

         ~ = ported to Apache 2.0 but still needs work

         - = port still not finished

 The source files are written in clean ANSI C and pass the ``gcc -O -g

 -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes

 -Wmissing-declarations -Wnested-externs -Winline'' compiler test

 (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When

 you make changes or additions make sure the source still passes this

 compiler test.

 FUNCTIONS

 Inside the source code you will be confronted with the following types of

 functions which can be identified by their prefixes:

   ap_xxxx() ............... Apache API function

   ssl_xxxx() .............. mod_ssl function

   SSL_xxxx() .............. OpenSSL function (SSL library)

   OpenSSL_xxxx() .......... OpenSSL function (SSL library)

   X509_xxxx() ............. OpenSSL function (Crypto library)

   PEM_xxxx() .............. OpenSSL function (Crypto library)

   EVP_xxxx() .............. OpenSSL function (Crypto library)

   RSA_xxxx() .............. OpenSSL function (Crypto library)

 DATA STRUCTURES

 Inside the source code you will be confronted with the following

 data structures:

   server_rec .............. Apache (Virtual) Server

   conn_rec ................ Apache Connection

   request_rec ............. Apache Request

   SSLModConfig ............ mod_ssl (Global)  Module Configuration

   SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration

   SSLDirConfig ............ mod_ssl Directory Configuration

   SSLConnConfig ........... mod_ssl Connection Configuration

   SSLFilterRec ............ mod_ssl Filter Context

   SSL_CTX ................. OpenSSL Context

   SSL_METHOD .............. OpenSSL Protocol Method

   SSL_CIPHER .............. OpenSSL Cipher

   SSL_SESSION ............. OpenSSL Session

   SSL ..................... OpenSSL Connection

   BIO ..................... OpenSSL Connection Buffer

 For an overview how these are related and chained together have a look at the

 page in README.dsov.{fig,ps}. It contains overview diagrams for those data

 structures. It's designed for DIN A4 paper size, but you can easily generate

 a smaller version inside XFig by specifing a magnification on the Export

 panel.

 EXPERIMENTAL CODE

 Experimental code is always encapsulated as following:

   | #ifdef SSL_EXPERIMENTAL_xxxx

   | ...

   | #endif

 This way it is only compiled in when this define is enabled with

 the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the

 C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_

 defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all

 SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE

 is already defined. Currently the following features are experimental:

   o SSL_EXPERIMENTAL_ENGINE

     The ability to support the new forthcoming OpenSSL ENGINE stuff.

     Until this development branch of OpenSSL is merged into the main

     stream, you have to use openssl-engine-0.9.x.tar.gz for this.

     mod_ssl automatically recognizes this OpenSSL variant and then can

     activate external crypto devices through SSLCryptoDevice directive.

 INCOMPATIBILITIES

 The following intentional incompatibilities exist between mod_ssl 2.x

 from Apache 1.3 and this mod_ssl version for Apache 2.0:

 o The complete EAPI-based SSL_VENDOR stuff was removed.

 o The complete EAPI-based SSL_COMPAT stuff was removed.

 o The <IfDefine> variable MOD_SSL is no longer provided automatically 

 MAJOR CHANGES 

 The following major changes were made between mod_ssl 2.x

 from Apache 1.3 and this mod_ssl version for Apache 2.0:

 o The DBM based session cache is now based on APR's DBM API only.

 o The shared memory based session cache is now based on APR's APIs.

 o SSL I/O is now implemented in terms of filters rather than BUFF

 o Eliminated ap_global_ctx. Storing Persistant information in 

   process_rec->pool->user_data. The ssl_pphrase_Handle_CB() and 

   ssl_config_global_* () functions have an extra parameter now - 

   "server_rec *" -  which is used to retrieve the SSLModConfigRec.

 o Properly support restarts, allowing mod_ssl to be added to a server

   that is already running and to change server certs/keys on restart

 o Various performance enhancements

 o proxy support is no longer an "extension", much of the mod_ssl core

   was re-written (ssl_engine_{init,kernel,config}.c) to be generic so

   it could be re-used in proxy mode.

   - the optional function ssl_proxy_enable is provide for mod_proxy

     to enable proxy support

   - proxy support now requires 'SSLProxyEngine on' to be configured

   - proxy now supports SSLProxyCARevocation{Path,File} in addition to

     the original SSLProxy* directives

 o per-directory SSLCACertificate{File,Path} is now thread-safe but

   requires SSL_set_cert_store patch to OpenSSL

 o RSA sslc is supported via ssl_toolkit_compat.h

 o the ssl_engine_{ds,ext}.c source files are obsolete and no longer

   exist

 TODO

 o SSL renegotiations in combination with POST request

 o Port all remaining code (code inside #if 0...#endif blocks)

 o Do we need SSL_set_read_ahead()?

 o the ssl_expr api is NOT THREAD SAFE.  race conditions exist:

   -in ssl_expr_comp() if SSLRequire is used in .htaccess

    (ssl_expr_info is global)

   -is ssl_expr_eval() if there is an error

    (ssl_expr_error is global)

 o SSLRequire directive (parsing of) leaks memory

 o Diffie-Hellman-Parameters for temporary keys are hardcoded in

   ssl_engine_dh.c, while the comment in ssl_engine_kernel.c says:

   "it is suggested that keys be changed daily or every 500

    transactions, and more often if possible."

 o ssl_var_lookup could be rewritten to be MUCH faster

 o CRL callback should be pluggable

 o session cache store should be pluggable

 o init functions should return status code rather than ssl_die()

 o ssl_engine_pphrase.c needs to be reworked so it is generic enough

   to also decrypt proxy keys

 o the shmcb code should just align its memory segment rather than

   jumping through all the "safe" memcpy and memset hoops