README revision 6bd5608385f2307a9ded240a87e9da495988d9fb
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg _ __ ___ ___ __| | ___ ___| |
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg | '_ ` _ \ / _ \ / _` | / __/ __| |
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg | | | | | | (_) | (_| | \__ \__ \ | ``mod_ssl combines the flexibility of
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg |_| |_| |_|\___/ \__,_|___|___/___/_| Apache with the security of OpenSSL.''
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg mod_ssl ``Ralf Engelschall has released an
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Apache Interface to OpenSSL excellent module that integrates
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg http://www.modssl.org/ Apache and SSLeay.''
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Version 2.8 -- Tim J. Hudson
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg This Apache module provides strong cryptography for the Apache 1.3 webserver
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg v1) protocols by the help of the SSL/TLS implementation library OpenSSL which
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg was created in April 1998 by Ralf S. Engelschall and was originally derived
16b55a35cff91315d261d1baa776138af465c4e4fuankg from software developed by Ben Laurie for use in the Apache-SSL HTTP server
16b55a35cff91315d261d1baa776138af465c4e4fuankg Here is a short overview of the source files:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg # Makefile.in ............. Makefile template for Unix platform
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg # config.m4 ............... Autoconf stub for the Apache config mechanism
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg # mod_ssl.c ............... main source file containing API structures
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - mod_ssl.h ............... common header file of mod_ssl
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_config.c ..... module configuration handling
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_ds.c ......... data structures
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_ext.c ........ Extensions to other Apache parts
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_init.c ....... module initialization
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_io.c ......... I/O support
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_kernel.c ..... SSL engine kernel
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_log.c ........ logfile support
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg # ssl_engine_mutex.c ...... mutual exclusion support
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_pphrase.c .... pass-phrase handling
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_rand.c ....... PRNG support
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_engine_vars.c ....... Variable Expansion support
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr.c .............. expression handling main source
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr.h .............. expression handling common header
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_scan.c ......... expression scanner automaton (pre-generated)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_scan.l ......... expression scanner source
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_parse.c ........ expression parser automaton (pre-generated)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_parse.h ........ expression parser header (pre-generated)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_parse.y ........ expression parser source
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_expr_eval.c ......... expression machine evaluation
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_scache.c ............ session cache abstraction layer
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg # ssl_scache_dbm.c ........ session cache via DBM file
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_scache_shmht.c ...... session cache via shared memory hash table
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_util.c .............. utility functions
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_util_ssl.c .......... the OpenSSL companion source
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_util_ssl.h .......... the OpenSSL companion header
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_util_table.c ........ the hash table library source
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - ssl_util_table.h ........ the hash table library header
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Legend: # = already ported to Apache 2.0
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg - = port still not finished
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg The source files are written in clean ANSI C and pass the ``gcc -O -g
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg -Wmissing-declarations -Wnested-externs -Winline'' compiler test
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg you make changes or additions make sure the source still passes this
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg compiler test.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Inside the source code you will be confronted with the following types of
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg functions which can be identified by their prefixes:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ap_xxxx() ............... Apache API function
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ssl_xxxx() .............. mod_ssl function
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_xxxx() .............. OpenSSL function (SSL library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg OpenSSL_xxxx() .......... OpenSSL function (SSL library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg X509_xxxx() ............. OpenSSL function (Crypto library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg PEM_xxxx() .............. OpenSSL function (Crypto library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg EVP_xxxx() .............. OpenSSL function (Crypto library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg RSA_xxxx() .............. OpenSSL function (Crypto library)
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg DATA STRUCTURES
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Inside the source code you will be confronted with the following
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg data structures:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ap_ctx .................. Apache EAPI Context
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg server_rec .............. Apache (Virtual) Server
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg conn_rec ................ Apache Connection
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg BUFF .................... Apache Connection Buffer
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg request_rec ............. Apache Request
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSLModConfig ............ mod_ssl (Global) Module Configuration
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSLDirConfig ............ mod_ssl Directory Configuration
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_CTX ................. OpenSSL Context
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_METHOD .............. OpenSSL Protocol Method
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_CIPHER .............. OpenSSL Cipher
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_SESSION ............. OpenSSL Session
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL ..................... OpenSSL Connection
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg BIO ..................... OpenSSL Connection Buffer
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg For an overview how these are related and chained together have a look at the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg page in README.dsov.{fig,ps}. It contains overview diagrams for those data
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg structures. It's designed for DIN A4 paper size, but you can easily generate
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg a smaller version inside XFig by specifing a magnification on the Export
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg EXPERIMENTAL CODE
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Experimental code is always encapsulated as following:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg | #ifdef SSL_EXPERIMENTAL_xxxx
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg This way it is only compiled in when this define is enabled with
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg is already defined. Currently the following features are experimental:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o SSL_EXPERIMENTAL_PERDIRCA
0662ed52e814f8f08ef0e09956413a792584eddffuankg The ability to use SSLCACertificateFile and SSLCACertificatePath
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg in a per-directory context (.htaccess). This is provided by some nasty
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg reconfiguration hacks until OpenSSL has better support for this. It
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg should work on non-multithreaded platforms (all but Win32).
0662ed52e814f8f08ef0e09956413a792584eddffuankg o SSL_EXPERIMENTAL_PROXY
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg The ability to use various additional SSLProxyXXX directives in
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg oder to control extended client functionality in the HTTPS proxy
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o SSL_EXPERIMENTAL_ENGINE
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg The ability to support the new forthcoming OpenSSL ENGINE stuff.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg Until this development branch of OpenSSL is merged into the main
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg stream, you have to use openssl-engine-0.9.x.tar.gz for this.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg mod_ssl automatically recognizes this OpenSSL variant and then can
0662ed52e814f8f08ef0e09956413a792584eddffuankg activate external crypto devices through SSLCryptoDevice directive.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg INCOMPATIBILITIES
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg The following intentional incompatibilities exist between mod_ssl 2.x
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg from Apache 1.3 and this mod_ssl version for Apache 2.0:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o The complete EAPI-based SSL_VENDOR stuff was removed.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o The complete EAPI-based SSL_COMPAT stuff was removed.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o The <IfDefine> variable MOD_SSL is no longer provided automatically
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o The complete SSL_CONSERVATIVE stuff was removed, i.e.,
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg SSL renegotiations in combination with POST request are not supported
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg unless the problem is solved again, but this time through layered I/O.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg MAJOR CHANGES
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg The following major changes were made between mod_ssl 2.x
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg from Apache 1.3 and this mod_ssl version for Apache 2.0:
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o The DBM based session cache is now based on APR's DBM API only.
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg o Whether to unregister and how to unregister?
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ssl_var_unregister();
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ssl_ext_unregister();
13b501825bce68e7e49b4bc775da93e38d9bd9f3fuankg ssl_io_unregister();