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