README revision fa563b81d94fc4811ca73df2889f22ec522fc95e
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte This Apache module provides strong cryptography for the Apache 2.0 webserver
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte v1) protocols by the help of the SSL/TLS implementation library OpenSSL which
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte is based on SSLeay from Eric A. Young and Tim J. Hudson.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte The mod_ssl package was created in April 1998 by Ralf S. Engelschall
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte and was originally derived from software developed by Ben Laurie for
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte use in the Apache-SSL HTTP server project. The mod_ssl implementation
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte for Apache 1.3 continues to be supported by the modssl project
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte See the top-level LAYOUT file in httpd-2.0 for file descriptions.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte The source files are written in clean ANSI C and pass the ``gcc -O -g
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte -Wmissing-declarations -Wnested-externs -Winline'' compiler test
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte you make changes or additions make sure the source still passes this
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte compiler test.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Inside the source code you will be confronted with the following types of
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte functions which can be identified by their prefixes:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte ap_xxxx() ............... Apache API function
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte ssl_xxxx() .............. mod_ssl function
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_xxxx() .............. OpenSSL function (SSL library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte OpenSSL_xxxx() .......... OpenSSL function (SSL library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte X509_xxxx() ............. OpenSSL function (Crypto library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte PEM_xxxx() .............. OpenSSL function (Crypto library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte EVP_xxxx() .............. OpenSSL function (Crypto library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte RSA_xxxx() .............. OpenSSL function (Crypto library)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteDATA STRUCTURES
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Inside the source code you will be confronted with the following
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte data structures:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte server_rec .............. Apache (Virtual) Server
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte conn_rec ................ Apache Connection
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte request_rec ............. Apache Request
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSLModConfig ............ mod_ssl (Global) Module Configuration
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSLDirConfig ............ mod_ssl Directory Configuration
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSLConnConfig ........... mod_ssl Connection Configuration
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSLFilterRec ............ mod_ssl Filter Context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_CTX ................. OpenSSL Context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_METHOD .............. OpenSSL Protocol Method
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_CIPHER .............. OpenSSL Cipher
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_SESSION ............. OpenSSL Session
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL ..................... OpenSSL Connection
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte BIO ..................... OpenSSL Connection Buffer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte For an overview how these are related and chained together have a look at the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte page in README.dsov.{fig,ps}. It contains overview diagrams for those data
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte structures. It's designed for DIN A4 paper size, but you can easily generate
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte a smaller version inside XFig by specifing a magnification on the Export
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteEXPERIMENTAL CODE
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Experimental code is always encapsulated as following:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte | #ifdef SSL_EXPERIMENTAL_xxxx
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte This way it is only compiled in when this define is enabled with
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte is already defined. Currently the following features are experimental:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o SSL_EXPERIMENTAL_ENGINE
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte The ability to support the new forthcoming OpenSSL ENGINE stuff.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte Until this development branch of OpenSSL is merged into the main
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte stream, you have to use openssl-engine-0.9.x.tar.gz for this.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte mod_ssl automatically recognizes this OpenSSL variant and then can
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte activate external crypto devices through SSLCryptoDevice directive.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteINCOMPATIBILITIES
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte The following intentional incompatibilities exist between mod_ssl 2.x
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte from Apache 1.3 and this mod_ssl version for Apache 2.0:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o The complete EAPI-based SSL_VENDOR stuff was removed.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o The complete EAPI-based SSL_COMPAT stuff was removed.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o The <IfDefine> variable MOD_SSL is no longer provided automatically
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteMAJOR CHANGES
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte For a complete history of changes for Apache 2.0 mod_ssl, see the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte CHANGES file in the top-level httpd-2.0 directory. The following
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte is a condensed summary of the major changes were made between
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte mod_ssl 2.x from Apache 1.3 and this mod_ssl version for Apache 2.0:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o The DBM based session cache is now based on APR's DBM API only.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o The shared memory based session cache is now based on APR's APIs.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o SSL I/O is now implemented in terms of filters rather than BUFF
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o Eliminated ap_global_ctx. Storing Persistant information in
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte process_rec->pool->user_data. The ssl_pphrase_Handle_CB() and
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte ssl_config_global_* () functions have an extra parameter now -
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte "server_rec *" - which is used to retrieve the SSLModConfigRec.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o Properly support restarts, allowing mod_ssl to be added to a server
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte that is already running and to change server certs/keys on restart
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o Various performance enhancements
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o proxy support is no longer an "extension", much of the mod_ssl core
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte was re-written (ssl_engine_{init,kernel,config}.c) to be generic so
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte it could be re-used in proxy mode.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - the optional function ssl_proxy_enable is provide for mod_proxy
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte to enable proxy support
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - proxy support now requires 'SSLProxyEngine on' to be configured
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte - proxy now supports SSLProxyCARevocation{Path,File} in addition to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte the original SSLProxy* directives
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o per-directory SSLCACertificate{File,Path} is now thread-safe but
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte requires SSL_set_cert_store patch to OpenSSL
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o RSA sslc is supported via ssl_toolkit_compat.h
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte o the ssl_engine_{ds,ext}.c source files are obsolete and no longer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte See the top-level STATUS file in httpd-2.0 for current efforts and goals.