README revision a1450136064a23e3a8a16a4f6c1fc3f55b4cbd55
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff _ __ ___ ___ __| | ___ ___| |
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff | '_ ` _ \ / _ \ / _` | / __/ __| |
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff | | | | | | (_) | (_| | \__ \__ \ | ``mod_ssl combines the flexibility of
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff |_| |_| |_|\___/ \__,_|___|___/___/_| Apache with the security of OpenSSL.''
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff mod_ssl ``Ralf Engelschall has released an
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Apache Interface to OpenSSL excellent module that integrates
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac http://www.modssl.org/ Apache and SSLeay.''
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac Version 2.8 -- Tim J. Hudson
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff This Apache module provides strong cryptography for the Apache 1.3 webserver
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac v1) protocols by the help of the SSL/TLS implementation library OpenSSL which
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package
8cf870d281dc8c242f083d14dfef05f24aa5fceeJnRouvignac was created in April 1998 by Ralf S. Engelschall and was originally derived
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff from software developed by Ben Laurie for use in the Apache-SSL HTTP server
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Here is a short overview of the source files:
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # Makefile.in ............. Makefile template for Unix platform
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # config.m4 ............... Autoconf stub for the Apache config mechanism
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # mod_ssl.c ............... main source file containing API structures
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - mod_ssl.h ............... common header file of mod_ssl
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_config.c ..... module configuration handling
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_engine_ds.c ......... data structures
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_ext.c ........ Extensions to other Apache parts
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_init.c ....... module initialization
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_io.c ......... I/O support
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_kernel.c ..... SSL engine kernel
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_log.c ........ logfile support
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_engine_mutex.c ...... mutual exclusion support
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_pphrase.c .... pass-phrase handling
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_rand.c ....... PRNG support
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_engine_vars.c ....... Variable Expansion support
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_expr.c .............. expression handling main source
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_expr.h .............. expression handling common header
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_expr_scan.c ......... expression scanner automaton (pre-generated)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_expr_scan.l ......... expression scanner source
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_expr_parse.c ........ expression parser automaton (pre-generated)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_expr_parse.h ........ expression parser header (pre-generated)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_expr_parse.y ........ expression parser source
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_expr_eval.c ......... expression machine evaluation
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_scache.c ............ session cache abstraction layer
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_scache_dbm.c ........ session cache via DBM file
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - ssl_scache_shmht.c ...... session cache via shared memory hash table
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_util.c .............. utility functions
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_util_ssl.c .......... the OpenSSL companion source
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_util_ssl.h .......... the OpenSSL companion header
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_util_table.c ........ the hash table library source
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff # ssl_util_table.h ........ the hash table library header
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Legend: # = already ported to Apache 2.0
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff - = port still not finished
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff The source files are written in clean ANSI C and pass the ``gcc -O -g
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff -Wmissing-declarations -Wnested-externs -Winline'' compiler test
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff you make changes or additions make sure the source still passes this
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff compiler test.
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Inside the source code you will be confronted with the following types of
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff functions which can be identified by their prefixes:
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff ap_xxxx() ............... Apache API function
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff ssl_xxxx() .............. mod_ssl function
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_xxxx() .............. OpenSSL function (SSL library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff OpenSSL_xxxx() .......... OpenSSL function (SSL library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff X509_xxxx() ............. OpenSSL function (Crypto library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff PEM_xxxx() .............. OpenSSL function (Crypto library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff EVP_xxxx() .............. OpenSSL function (Crypto library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff RSA_xxxx() .............. OpenSSL function (Crypto library)
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff DATA STRUCTURES
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Inside the source code you will be confronted with the following
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff data structures:
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff ap_ctx .................. Apache EAPI Context
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff server_rec .............. Apache (Virtual) Server
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff conn_rec ................ Apache Connection
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff BUFF .................... Apache Connection Buffer
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff request_rec ............. Apache Request
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSLModConfig ............ mod_ssl (Global) Module Configuration
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSLDirConfig ............ mod_ssl Directory Configuration
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_CTX ................. OpenSSL Context
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_METHOD .............. OpenSSL Protocol Method
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_CIPHER .............. OpenSSL Cipher
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_SESSION ............. OpenSSL Session
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL ..................... OpenSSL Connection
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff BIO ..................... OpenSSL Connection Buffer
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff For an overview how these are related and chained together have a look at the
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff page in README.dsov.{fig,ps}. It contains overview diagrams for those data
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff structures. It's designed for DIN A4 paper size, but you can easily generate
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff a smaller version inside XFig by specifing a magnification on the Export
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff EXPERIMENTAL CODE
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff Experimental code is always encapsulated as following:
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff | #ifdef SSL_EXPERIMENTAL_xxxx
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff This way it is only compiled in when this define is enabled with
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff is already defined. Currently the following features are experimental:
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff o SSL_EXPERIMENTAL_PERDIRCA
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff The ability to use SSLCACertificateFile and SSLCACertificatePath
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff in a per-directory context (.htaccess). This is provided by some nasty
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff reconfiguration hacks until OpenSSL has better support for this. It
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff should work on non-multithreaded platforms (all but Win32).
d25372dc8e65a9ed019a88fdf659ca61313f1b31jcduff o SSL_EXPERIMENTAL_PROXY
stream, you have to use openssl-engine-0.9.x.tar.gz for this.
The following intentional incompatibilities exist between mod_ssl 2.x
o The complete SSL_CONSERVATIVE stuff was removed, i.e.,
The following major changes were made between mod_ssl 2.x