2ronwalf _ _

2ronwalf _ __ ___ ___ __| | ___ ___| |

2ronwalf | '_ ` _ \ / _ \ / _` | / __/ __| |

2ronwalf | | | | | | (_) | (_| | \__ \__ \ | ``mod_ssl combines the flexibility of

2ronwalf |_| |_| |_|\___/ \__,_|___|___/___/_| Apache with the security of OpenSSL.''

2ronwalf |_____|

2ronwalf mod_ssl ``Ralf Engelschall has released an

2ronwalf Apache Interface to OpenSSL excellent module that integrates

2ronwalf http://www.modssl.org/ Apache and SSLeay.''

2ronwalf Version 2.8 -- Tim J. Hudson

2ronwalf

2ronwalf SYNOPSIS

2ronwalf

2ronwalf This Apache module provides strong cryptography for the Apache 1.3 webserver

2ronwalf via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS

2ronwalf v1) protocols by the help of the SSL/TLS implementation library OpenSSL which

2ronwalf is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package

2ronwalf was created in April 1998 by Ralf S. Engelschall and was originally derived

2ronwalf from software developed by Ben Laurie for use in the Apache-SSL HTTP server

2ronwalf project.

2ronwalf

2ronwalf SOURCES

2ronwalf

2ronwalf Here is a short overview of the source files:

2ronwalf

2ronwalf * README .................. This file ;)

2ronwalf # Makefile.in ............. Makefile template for Unix platform

2ronwalf # config.m4 ............... Autoconf stub for the Apache config mechanism

38daenzerorama # mod_ssl.c ............... main source file containing API structures

2ronwalf # mod_ssl.h ............... common header file of mod_ssl

2ronwalf # ssl_engine_config.c ..... module configuration handling

2ronwalf # ssl_engine_dh.c ......... DSA/DH support

2ronwalf # ssl_engine_init.c ....... module initialization

2ronwalf # ssl_engine_io.c ......... I/O support

38daenzerorama # ssl_engine_kernel.c ..... SSL engine kernel

38daenzerorama # ssl_engine_log.c ........ logfile support

38daenzerorama # ssl_engine_mutex.c ...... mutual exclusion support

38daenzerorama # ssl_engine_pphrase.c .... pass-phrase handling

38daenzerorama # ssl_engine_rand.c ....... PRNG support

38daenzerorama # ssl_engine_vars.c ....... Variable Expansion support

2ronwalf # ssl_expr.c .............. expression handling main source

38daenzerorama # ssl_expr.h .............. expression handling common header

38daenzerorama # ssl_expr_scan.c ......... expression scanner automaton (pre-generated)

38daenzerorama # ssl_expr_scan.l ......... expression scanner source

38daenzerorama # ssl_expr_parse.c ........ expression parser automaton (pre-generated)

38daenzerorama # ssl_expr_parse.h ........ expression parser header (pre-generated)

2ronwalf # ssl_expr_parse.y ........ expression parser source

2ronwalf # ssl_expr_eval.c ......... expression machine evaluation

38daenzerorama # ssl_scache.c ............ session cache abstraction layer

38daenzerorama # ssl_scache_dbm.c ........ session cache via DBM file

38daenzerorama ~ ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer

38daenzerorama ~ ssl_scache_shmht.c ...... session cache via shared memory hash table

38daenzerorama # ssl_util.c .............. utility functions

2ronwalf # ssl_util_ssl.c .......... the OpenSSL companion source

38daenzerorama # ssl_util_ssl.h .......... the OpenSSL companion header

38daenzerorama # ssl_util_table.c ........ the hash table library source

38daenzerorama # ssl_util_table.h ........ the hash table library header

38daenzerorama

38daenzerorama Legend: # = already ported to Apache 2.0 and is cleaned up

38daenzerorama * = ported to Apache 2.0 but still needs cleaning up

2ronwalf ~ = ported to Apache 2.0 but still needs work

2ronwalf - = port still not finished

38daenzerorama

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

38daenzerorama -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes

38daenzerorama -Wmissing-declarations -Wnested-externs -Winline'' compiler test

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

2ronwalf you make changes or additions make sure the source still passes this

38daenzerorama compiler test.

38daenzerorama

38daenzerorama FUNCTIONS

38daenzerorama

38daenzerorama Inside the source code you will be confronted with the following types of

38daenzerorama functions which can be identified by their prefixes:

38daenzerorama

2ronwalf ap_xxxx() ............... Apache API function

38daenzerorama ssl_xxxx() .............. mod_ssl function

38daenzerorama SSL_xxxx() .............. OpenSSL function (SSL library)

38daenzerorama OpenSSL_xxxx() .......... OpenSSL function (SSL library)

38daenzerorama X509_xxxx() ............. OpenSSL function (Crypto library)

38daenzerorama PEM_xxxx() .............. OpenSSL function (Crypto library)

38daenzerorama EVP_xxxx() .............. OpenSSL function (Crypto library)

38daenzerorama RSA_xxxx() .............. OpenSSL function (Crypto library)

38daenzerorama

2ronwalf DATA STRUCTURES

Inside the source code you will be confronted with the following

data structures:

server_rec .............. Apache (Virtual) Server

conn_rec ................ Apache Connection

request_rec ............. Apache Request

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

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.

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_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

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 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

o SSL renegotiations in combination with POST request

o Port all remaining code (code inside #if 0...#endif blocks)

o Do we need SSL_set_read_ahead()?

o the ssl_expr api is NOT THREAD SAFE. race conditions exist:

-in ssl_expr_comp() if SSLRequire is used in .htaccess

(ssl_expr_info is global)

-is ssl_expr_eval() if there is an error

(ssl_expr_error is global)

o SSLRequire directive (parsing of) leaks memory

o Diffie-Hellman-Parameters for temporary keys are hardcoded in

ssl_engine_dh.c, while the comment in ssl_engine_kernel.c says:

"it is suggested that keys be changed daily or every 500

transactions, and more often if possible."

o ssl_var_lookup could be rewritten to be MUCH faster

o CRL callback should be pluggable

o session cache store should be pluggable

o init functions should return status code rather than ssl_die()

o ssl_engine_pphrase.c needs to be reworked so it is generic enough

to also decrypt proxy keys

o the shmcb code should just align its memory segment rather than

jumping through all the "safe" memcpy and memset hoops