granicus.if.org Git - apache/blob - modules/ssl/README

   1                       _             _
   2   _ __ ___   ___   __| |    ___ ___| |
   3  | '_ ` _ \ / _ \ / _` |   / __/ __| |
   4  | | | | | | (_) | (_| |   \__ \__ \ | ``mod_ssl combines the flexibility of
   5  |_| |_| |_|\___/ \__,_|___|___/___/_|   Apache with the security of OpenSSL.''
   6                       |_____|
   7  mod_ssl                               ``Ralf Engelschall has released an
   8  Apache Interface to OpenSSL             excellent module that integrates
   9  http://www.modssl.org/                  Apache and SSLeay.''
  10  Version 2.8                                               -- Tim J. Hudson
  11
  12  SYNOPSIS
  13
  14  This Apache module provides strong cryptography for the Apache 1.3 webserver
  15  via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
  16  v1) protocols by the help of the SSL/TLS implementation library OpenSSL which
  17  is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package
  18  was created in April 1998 by Ralf S. Engelschall and was originally derived
  19  from software developed by Ben Laurie for use in the Apache-SSL HTTP server
  20  project.
  21
  22  SOURCES
  23
  24  Here is a short overview of the source files:
  25
  26    Makefile.in ............. Makefile template for Unix platform
  27    config.m4 ............... Autoconf stub for the Apache config mechanism
  28    mod_ssl.c ............... main source file containing API structures
  29    mod_ssl.h ............... common header file of mod_ssl
  30    ssl_engine_compat.c ..... backward compatibility support
  31    ssl_engine_config.c ..... module configuration handling
  32    ssl_engine_dh.c ......... DSA/DH support
  33    ssl_engine_ds.c ......... data structures
  34    ssl_engine_ext.c ........ Extensions to other Apache parts
  35    ssl_engine_init.c ....... module initialization
  36    ssl_engine_io.c ......... I/O support
  37    ssl_engine_kernel.c ..... SSL engine kernel
  38    ssl_engine_log.c ........ logfile support
  39    ssl_engine_mutex.c ...... mutual exclusion support
  40    ssl_engine_pphrase.c .... pass-phrase handling
  41    ssl_engine_rand.c ....... PRNG support
  42    ssl_engine_vars.c ....... Variable Expansion support
  43    ssl_expr.c .............. expression handling main source
  44    ssl_expr.h .............. expression handling common header
  45    ssl_expr_scan.c ......... expression scanner automaton (pre-generated)
  46    ssl_expr_scan.l ......... expression scanner source
  47    ssl_expr_parse.c ........ expression parser automaton  (pre-generated)
  48    ssl_expr_parse.h ........ expression parser header     (pre-generated)
  49    ssl_expr_parse.y ........ expression parser source
  50    ssl_expr_eval.c ......... expression machine evaluation
  51    ssl_scache.c ............ session cache abstraction layer
  52    ssl_scache_dbm.c ........ session cache via DBM file
  53    ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer
  54    ssl_scache_shmht.c ...... session cache via shared memory hash table
  55    ssl_util.c .............. utility functions
  56    ssl_util_ssl.c .......... the OpenSSL companion source
  57    ssl_util_ssl.h .......... the OpenSSL companion header
  58    ssl_util_sdbm.c ......... the SDBM library source
  59    ssl_util_sdbm.h ......... the SDBM library header
  60    ssl_util_table.c ........ the hash table library source
  61    ssl_util_table.h ........ the hash table library header
  62
  63  The source files are written in clean ANSI C and pass the ``gcc -O -g
  64  -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes
  65  -Wmissing-declarations -Wnested-externs -Winline'' compiler test
  66  (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When
  67  you make changes or additions make sure the source still passes this
  68  compiler test.
  69
  70  FUNCTIONS
  71
  72  Inside the source code you will be confronted with the following types of
  73  functions which can be identified by their prefixes:
  74
  75    ap_xxxx() ............... Apache API function
  76    ssl_xxxx() .............. mod_ssl function
  77    SSL_xxxx() .............. OpenSSL function (SSL library)
  78    OpenSSL_xxxx() .......... OpenSSL function (SSL library)
  79    X509_xxxx() ............. OpenSSL function (Crypto library)
  80    PEM_xxxx() .............. OpenSSL function (Crypto library)
  81    EVP_xxxx() .............. OpenSSL function (Crypto library)
  82    RSA_xxxx() .............. OpenSSL function (Crypto library)
  83
  84  DATA STRUCTURES
  85
  86  Inside the source code you will be confronted with the following
  87  data structures:
  88
  89    ap_ctx .................. Apache EAPI Context
  90    server_rec .............. Apache (Virtual) Server
  91    conn_rec ................ Apache Connection
  92    BUFF .................... Apache Connection Buffer
  93    request_rec ............. Apache Request
  94    SSLModConfig ............ mod_ssl (Global)  Module Configuration
  95    SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration
  96    SSLDirConfig ............ mod_ssl Directory Configuration
  97    SSL_CTX ................. OpenSSL Context
  98    SSL_METHOD .............. OpenSSL Protocol Method
  99    SSL_CIPHER .............. OpenSSL Cipher
 100    SSL_SESSION ............. OpenSSL Session
 101    SSL ..................... OpenSSL Connection
 102    BIO ..................... OpenSSL Connection Buffer
 103
 104  For an overview how these are related and chained together have a look at the
 105  page in README.dsov.{fig,ps}. It contains overview diagrams for those data
 106  structures. It's designed for DIN A4 paper size, but you can easily generate
 107  a smaller version inside XFig by specifing a magnification on the Export
 108  panel.
 109
 110  EXPERIMENTAL CODE
 111
 112  Experimental code is always encapsulated as following:
 113
 114    | #ifdef SSL_EXPERIMENTAL_xxxx
 115    | ...
 116    | #endif
 117
 118  This way it is only compiled in when this define is enabled with
 119  the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the
 120  C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_
 121  defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all
 122  SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE
 123  is already defined. Currently the following features are experimental:
 124
 125    o SSL_EXPERIMENTAL_PERDIRCA
 126      The ability to use SSLCACertificateFile and SSLCACertificatePath
 127      in a per-directory context (.htaccess). This is provided by some nasty
 128      reconfiguration hacks until OpenSSL has better support for this. It
 129      should work on non-multithreaded platforms (all but Win32).
 130
 131    o SSL_EXPERIMENTAL_PROXY
 132      The ability to use various additional SSLProxyXXX directives in
 133      oder to control extended client functionality in the HTTPS proxy
 134      code.
 135
 136    o SSL_EXPERIMENTAL_ENGINE
 137      The ability to support the new forthcoming OpenSSL ENGINE stuff.
 138      Until this development branch of OpenSSL is merged into the main
 139      stream, you have to use openssl-engine-0.9.x.tar.gz for this.
 140      mod_ssl automatically recognizes this OpenSSL variant and then can
 141      activate external crypto devices through SSLCryptoDevice directive.
 142
 143  INCOMPATIBILITIES
 144
 145  The following intentional incompatibilities exist between mod_ssl 2.x
 146  from Apache 1.3 and this mod_ssl version for Apache 2.0:
 147
 148  o The complete EAPI-based SSL_VENDOR stuff was removed.
 149  o The complete EAPI-based SSL_COMPAT stuff was removed.
 150
 151  MAJOR CHANGES
 152
 153  The following major changes were made between mod_ssl 2.x
 154  from Apache 1.3 and this mod_ssl version for Apache 2.0:
 155
 156  o The DBM based session cache is now based on APR's DBM API only.
 157