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