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