rubbos/app/httpd-2.0.64/modules/ssl/README

   1 SYNOPSIS
   2
   3  This Apache module provides strong cryptography for the Apache 2.0 webserver
   4  via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
   5  v1) protocols by the help of the SSL/TLS implementation library OpenSSL which
   6  is based on SSLeay from Eric A. Young and Tim J. Hudson.
   7
   8  The mod_ssl package was created in April 1998 by Ralf S. Engelschall
   9  and was originally derived from software developed by Ben Laurie for
  10  use in the Apache-SSL HTTP server project.  The mod_ssl implementation
  11  for Apache 1.3 continues to be supported by the modssl project
  12  <http://www.modssl.org/>.
  13
  14 SOURCES
  15
  16  See the top-level LAYOUT file in httpd-2.0 for file descriptions.
  17
  18  The source files are written in clean ANSI C and pass the ``gcc -O -g
  19  -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes
  20  -Wmissing-declarations -Wnested-externs -Winline'' compiler test
  21  (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When
  22  you make changes or additions make sure the source still passes this
  23  compiler test.
  24
  25 FUNCTIONS
  26
  27  Inside the source code you will be confronted with the following types of
  28  functions which can be identified by their prefixes:
  29
  30    ap_xxxx() ............... Apache API function
  31    ssl_xxxx() .............. mod_ssl function
  32    SSL_xxxx() .............. OpenSSL function (SSL library)
  33    OpenSSL_xxxx() .......... OpenSSL function (SSL library)
  34    X509_xxxx() ............. OpenSSL function (Crypto library)
  35    PEM_xxxx() .............. OpenSSL function (Crypto library)
  36    EVP_xxxx() .............. OpenSSL function (Crypto library)
  37    RSA_xxxx() .............. OpenSSL function (Crypto library)
  38
  39 DATA STRUCTURES
  40
  41  Inside the source code you will be confronted with the following
  42  data structures:
  43
  44    server_rec .............. Apache (Virtual) Server
  45    conn_rec ................ Apache Connection
  46    request_rec ............. Apache Request
  47    SSLModConfig ............ mod_ssl (Global)  Module Configuration
  48    SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration
  49    SSLDirConfig ............ mod_ssl Directory Configuration
  50    SSLConnConfig ........... mod_ssl Connection Configuration
  51    SSLFilterRec ............ mod_ssl Filter Context
  52    SSL_CTX ................. OpenSSL Context
  53    SSL_METHOD .............. OpenSSL Protocol Method
  54    SSL_CIPHER .............. OpenSSL Cipher
  55    SSL_SESSION ............. OpenSSL Session
  56    SSL ..................... OpenSSL Connection
  57    BIO ..................... OpenSSL Connection Buffer
  58
  59  For an overview how these are related and chained together have a look at the
  60  page in README.dsov.{fig,ps}. It contains overview diagrams for those data
  61  structures. It's designed for DIN A4 paper size, but you can easily generate
  62  a smaller version inside XFig by specifing a magnification on the Export
  63  panel.
  64
  65 EXPERIMENTAL CODE
  66
  67  Experimental code is always encapsulated as following:
  68
  69    | #ifdef SSL_EXPERIMENTAL_xxxx
  70    | ...
  71    | #endif
  72
  73  This way it is only compiled in when this define is enabled with
  74  the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the
  75  C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_
  76  defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all
  77  SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE
  78  is already defined. Currently the following features are experimental:
  79
  80    o SSL_EXPERIMENTAL_ENGINE
  81      The ability to support the new forthcoming OpenSSL ENGINE stuff.
  82      Until this development branch of OpenSSL is merged into the main
  83      stream, you have to use openssl-engine-0.9.x.tar.gz for this.
  84      mod_ssl automatically recognizes this OpenSSL variant and then can
  85      activate external crypto devices through SSLCryptoDevice directive.
  86
  87 INCOMPATIBILITIES
  88
  89  The following intentional incompatibilities exist between mod_ssl 2.x
  90  from Apache 1.3 and this mod_ssl version for Apache 2.0:
  91
  92  o The complete EAPI-based SSL_VENDOR stuff was removed.
  93  o The complete EAPI-based SSL_COMPAT stuff was removed.
  94  o The <IfDefine> variable MOD_SSL is no longer provided automatically
  95
  96 MAJOR CHANGES
  97
  98  For a complete history of changes for Apache 2.0 mod_ssl, see the
  99  CHANGES file in the top-level httpd-2.0 directory.  The following
 100  is a condensed summary of the major changes were made between
 101  mod_ssl 2.x from Apache 1.3 and this mod_ssl version for Apache 2.0:
 102
 103  o The DBM based session cache is now based on APR's DBM API only.
 104  o The shared memory based session cache is now based on APR's APIs.
 105  o SSL I/O is now implemented in terms of filters rather than BUFF
 106  o Eliminated ap_global_ctx. Storing Persistant information in
 107    process_rec->pool->user_data. The ssl_pphrase_Handle_CB() and
 108    ssl_config_global_* () functions have an extra parameter now -
 109    "server_rec *" -  which is used to retrieve the SSLModConfigRec.
 110  o Properly support restarts, allowing mod_ssl to be added to a server
 111    that is already running and to change server certs/keys on restart
 112  o Various performance enhancements
 113  o proxy support is no longer an "extension", much of the mod_ssl core
 114    was re-written (ssl_engine_{init,kernel,config}.c) to be generic so
 115    it could be re-used in proxy mode.
 116    - the optional function ssl_proxy_enable is provide for mod_proxy
 117      to enable proxy support
 118    - proxy support now requires 'SSLProxyEngine on' to be configured
 119    - proxy now supports SSLProxyCARevocation{Path,File} in addition to
 120      the original SSLProxy* directives
 121  o per-directory SSLCACertificate{File,Path} is now thread-safe but
 122    requires SSL_set_cert_store patch to OpenSSL
 123  o RSA sslc is supported via ssl_toolkit_compat.h
 124  o the ssl_engine_{ds,ext}.c source files are obsolete and no longer
 125    exist
 126
 127 TODO
 128
 129  See the top-level STATUS file in httpd-2.0 for current efforts and goals.