_ _ | |
_ __ ___ ___ __| | ___ ___| | | |
| '_ ` _ \ / _ \ / _` | / __/ __| | | |
| | | | | | (_) | (_| | \__ \__ \ | ``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: | |
* README .................. This file ;) | |
# Makefile.in ............. Makefile template for Unix platform | |
# config.m4 ............... Autoconf stub for the Apache config mechanism | |
# mod_ssl.c ............... main source file containing API structures | |
# mod_ssl.h ............... common header file of mod_ssl | |
# 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_table.c ........ the hash table library source | |
# ssl_util_table.h ........ the hash table library header | |
Legend: # = already ported to Apache 2.0 and is cleaned up | |
* = ported to Apache 2.0 but still needs cleaning up | |
- = port still not finished | |
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: | |
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 | |
SSLFilterRec ............ mod_ssl Filter Context | |
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. | |
INCOMPATIBILITIES | |
The following intentional incompatibilities exist between mod_ssl 2.x | |
from Apache 1.3 and this mod_ssl version for Apache 2.0: | |
o The complete EAPI-based SSL_VENDOR stuff was removed. | |
o The complete EAPI-based SSL_COMPAT stuff was removed. | |
o The <IfDefine> variable MOD_SSL is no longer provided automatically | |
o The complete SSL_CONSERVATIVE stuff was removed, i.e., | |
SSL renegotiations in combination with POST request are not supported | |
unless the problem is solved again, but this time through layered I/O. | |
MAJOR CHANGES | |
The following major changes were made between mod_ssl 2.x | |
from Apache 1.3 and this mod_ssl version for Apache 2.0: | |
o The DBM based session cache is now based on APR's DBM API only. | |
o Introduced Filter logic (similar to mod_tls) | |
o Eliminated ap_global_ctx. Storing Persistant information in | |
process_rec->pool->user_data. The ssl_pphrase_Handle_CB() and | |
ssl_config_global_* () functions have an extra parameter now - | |
"server_rec *" - which is used to retrieve the SSLModConfigRec. | |
TODO | |
o Cleanup ssl_engine_io.c !! | |
o Port all remaining code (code inside #if 0...#endif blocks) | |
o Do we need SSL_set_read_ahead()? | |
o Enable use of MM, SHMCB and SHMHT. | |
o Enable SSL extensions (ssl_engine_ext.c) | |