c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweSYNOPSIS

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This Apache module provides strong cryptography for the Apache 2 webserver

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe v1) protocols by the help of the SSL/TLS implementation library OpenSSL which

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is based on SSLeay from Eric A. Young and Tim J. Hudson.

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The mod_ssl package was created in April 1998 by Ralf S. Engelschall

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and was originally derived from software developed by Ben Laurie for

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe use in the Apache-SSL HTTP server project. The mod_ssl implementation

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe for Apache 1.3 continues to be supported by the modssl project

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov <http://www.modssl.org/>.

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri PankovSOURCES

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe See the top-level LAYOUT file for file descriptions.

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The source files are written in clean ANSI C and pass the ``gcc -O -g

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe -Wmissing-declarations -Wnested-externs -Winline'' compiler test

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe you make changes or additions make sure the source still passes this

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe compiler test.

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweFUNCTIONS

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Inside the source code you will be confronted with the following types of

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe functions which can be identified by their prefixes:

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe ap_xxxx() ............... Apache API function

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe ssl_xxxx() .............. mod_ssl function

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe SSL_xxxx() .............. OpenSSL function (SSL library)

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe OpenSSL_xxxx() .......... OpenSSL function (SSL library)

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe X509_xxxx() ............. OpenSSL function (Crypto library)

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe PEM_xxxx() .............. OpenSSL function (Crypto library)

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe EVP_xxxx() .............. OpenSSL function (Crypto library)

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov RSA_xxxx() .............. OpenSSL function (Crypto library)

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard LoweDATA STRUCTURES

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Inside the source code you will be confronted with the following

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov data structures:

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe server_rec .............. Apache (Virtual) Server

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe conn_rec ................ Apache Connection

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov request_rec ............. Apache Request

c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe SSLModConfig ............ mod_ssl (Global) Module Configuration

a9478106a12424322498e53cf7cd75bd8a4d6004Yuri Pankov SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration

SSLDirConfig ............ mod_ssl Directory Configuration

SSLConnConfig ........... mod_ssl Connection Configuration

SSLFilterRec ............ mod_ssl Filter Context

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.

INCOMPATIBILITIES

The following intentional incompatibilities exist between mod_ssl 2.x

from Apache 1.3 and this mod_ssl version for Apache 2:

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

MAJOR CHANGES

For a complete history of changes for Apache 2 mod_ssl, see the

CHANGES file in the top-level directory. The following

is a condensed summary of the major changes were made between

mod_ssl 2.x from Apache 1.3 and this mod_ssl version for Apache 2:

o The DBM based session cache is now based on APR's DBM API only.

o The shared memory based session cache is now based on APR's APIs.

o SSL I/O is now implemented in terms of filters rather than BUFF

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.

o Properly support restarts, allowing mod_ssl to be added to a server

that is already running and to change server certs/keys on restart

o Various performance enhancements

o proxy support is no longer an "extension", much of the mod_ssl core

was re-written (ssl_engine_{init,kernel,config}.c) to be generic so

it could be re-used in proxy mode.

- the optional function ssl_proxy_enable is provide for mod_proxy

to enable proxy support

- proxy support now requires 'SSLProxyEngine on' to be configured

- proxy now supports SSLProxyCARevocation{Path,File} in addition to

the original SSLProxy* directives

o per-directory SSLCACertificate{File,Path} is now thread-safe but

requires SSL_set_cert_store patch to OpenSSL

o RSA sslc is supported via ssl_toolkit_compat.h

o the ssl_engine_{ds,ext}.c source files are obsolete and no longer

exist

TODO

See the top-level STATUS file for current efforts and goals.