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