| _ _ | |
| _ __ ___ ___ __| | ___ ___| | | |
| | '_ ` _ \ / _ \ / _` | / __/ __| | | |
| | | | | | | (_) | (_| | \__ \__ \ | ``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; } | |