_ _ _ __ ___ ___ __| | ___ ___| | | '_ ` _ \ / _ \ / _` | / __/ __| | | | | | | | (_) | (_| | \__ \__ \ | ``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: Makefile.libdir ......... dummy for Apache config mechanism Makefile.tmpl ........... Makefile template for Unix platform Makefile.win32 .......... Makefile template for Win32 platform libssl.module ........... stub called from the Apache config mechanism libssl.version .......... file containing the mod_ssl version information mod_ssl.c ............... main source file containing API structures mod_ssl.h ............... common header file of mod_ssl ssl_engine_compat.c ..... backward compatibility support ssl_engine_config.c ..... module configuration handling ssl_engine_dh.c ......... DSA/DH support ssl_engine_ds.c ......... data structures ssl_engine_ext.c ........ Extensions to other Apache parts 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_sdbm.c ......... the SDBM library source ssl_util_sdbm.h ......... the SDBM library header ssl_util_table.c ........ the hash table library source ssl_util_table.h ........ the hash table library header 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: ap_ctx .................. Apache EAPI Context server_rec .............. Apache (Virtual) Server conn_rec ................ Apache Connection BUFF .................... Apache Connection Buffer request_rec ............. Apache Request SSLModConfig ............ mod_ssl (Global) Module Configuration SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration SSLDirConfig ............ mod_ssl Directory Configuration 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_PERDIRCA The ability to use SSLCACertificateFile and SSLCACertificatePath in a per-directory context (.htaccess). This is provided by some nasty reconfiguration hacks until OpenSSL has better support for this. It should work on non-multithreaded platforms (all but Win32). o SSL_EXPERIMENTAL_PROXY The ability to use various additional SSLProxyXXX directives in oder to control extended client functionality in the HTTPS proxy code. 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. VENDOR EXTENSIONS Inside the mod_ssl sources you can enable various EAPI vendor hooks (`ap::mod_ssl::vendor::xxxx') by using the APACI --enable-rule=SSL_VENDOR option. These hooks can be used to change or extend mod_ssl by a vendor without patching the source code. Grep for `ap::mod_ssl::vendor::'. Additionally vendors can add their own source code to files named ssl_vendor.c, ssl_vendor_XXX.c, etc. The libssl.module script automatically picks these up under configuration time and mod_ssl under run-time calls the functions `void ssl_vendor_register(void)' and `void ssl_vendor_unregister(void)' inside these objects to bootstrap them. An ssl_vendor.c should at least contain the following contents: | #include "mod_ssl.h" | void ssl_vendor_register(void) { return; } | void ssl_vendor_unregister(void) { return; }