                       _             _ 
   _ __ ___   ___   __| |    ___ ___| |  
  | '_ ` _ \ / _ \ / _` |   / __/ __| |  
  | | | | | | (_) | (_| |   \__ \__ \ |  mod_ssl - Apache Interface to SSLeay  
  |_| |_| |_|\___/ \__,_|___|___/___/_|  http://www.engelschall.com/sw/mod_ssl/
                       |_____|         
  _____________________________________________________________________________


  ChangeLog
  ---------

  This file summarizes *all* types of changes to the mod_ssl package, i.e.
  changes between each betalevel or patchlevel (2.x.y->2.x[.b](y+1) and
  2.x.y->2.(x+1).0).  Take this list as a reference for concrete and detailed
  information about every single change.

  Changes with mod_ssl 2.1b4 (08-Sep-1998 to 17-Sep-1998)

   *) Now mod_ssl is more friendly to the typical user error: Using HTTP
      instead of HTTPS to access an SSL-server. In the past the client has
      just seen an I/O error which often confused a lot of people (including
      the author of mod_ssl ;-). Now when the SSL_accept of SSLeay fails
      mod_ssl recognizes the fact that SSLeay already recognized the HTTP
      protocol. Then mod_ssl does a trick: It does some sort of a request
      roll-back: It reads the remaining bytes of the request, fakes it with an
      own error-request, lets Apache process this error-request and finally
      puts out a HTML error page with a clear description of the problem plus
      a hyperlink to the HTTPS URL. Currently this check works only with
      SSLeay 0.9 until the error code determination can be made more general.

   *) Fixed session cache timeout calculation.

   *) Fixed session cache DBM file initialization.
   
   *) Forward port from 2.0 branch:
      Make the SSL_HOOK_SetupConnection more robust. 

   *) Forward port from 2.0 branch:
      Added checks to APACI to automatically disable DSO for mod_proxy and
      mod_log_config when SSL is used (because they have to be built against
      SSLeay which is not supported in Apache 1.3.1). But we allow the user to
      explicitly use --enable-shared=.., but then at least he gets a warning.
      This way we protect the average user but don't hurt the experts.
      Especially with Apache 1.3.2 the experts want to use
      --enable-rule=SHARED_CHAIN for linking the DSO's against SSLeay.

   *) Forward port from 2.0 branch:
      Renamed `aux' directory to `etc' because `aux' is a special name under
      Windows filesystems (and people at least wanted to extract the stuff
      under windows).

   *) Forward port from 2.0 branch:
      Added Thawte's Strong Extranet module (mod_sxnet.c) to
      the ssl.contrib area. This module can be used together
      with mod_ssl.

   *) Forward port from 2.0 branch:
      In order to
      - reduce the confusion with sslcerts/server.pem and sslkeys/server.pem
      - provide less-problematic non-self-signed certificates on `make certificate'
      - prepare for mod_ssl 2.1 and the forthcoming client auth & CA scripts 
      the following cleanups were done:

      1. The files for the SSL certificate system are now stored in the
         following thee subdirs of the configuration directory:
         ssl.crt/ ...... contains the X.509 certificate(s)
         ssl.csr/ ...... contains the X.509 certificate signing requests(s)
         ssl.key/ ...... contains the RSA private key(s)
         Each directory contains a README file which describes the purpose and
         the contents.

      2. A ssl.crt/snakeoil.crt and ssl.key/snakeoil.key demo CA certificate
         and key is distributed with mod_ssl which is used to sign the test
         certificates the `make certificate' target creates.  This avoids the
         problems with MSIE users because MSIE doesn't like self-signed
         server-certificates very well.

      3. A ssl.crt/ca-bundle.crt is now installed (but not enabled!) which
         contains all 33 CA root certificates of known public CAs.  They were
         extracted from Netscape Communicator 4.06 with my certbundle stuff.

      4. The `make certificate' command now can create four types
         of certificate setups:
         $ make certificate TYPE=dummy    (dummy self-signed Snake Oil cert)
         $ make certificate TYPE=test     (test cert signed by Snake Oil CA)
         $ make certificate TYPE=custom   (custom cert signed by own CA)
         $ make certificate TYPE=official (existing official cert)
                CRT=/path/to/your.crt
                [KEY=/path/to/your.key]
         The default is TYPE=test which is equivalent to the old `make
         certificate' with the exception that now the generated certificate is
         no longer a self-signed one.  This overview text is also now
         displayed under built-time.  When KEY is missing it is assumed that
         it's present in the file from CRT and is extracted from there.

      5. For consistency with 4.) the mod_ssl configure script now
         uses --with-crt=FILE and --with-key=FILE options. When
         --with-key is missing it is assumed that it's present in
         the file from --with-crt and is extracted from there.

   *) Forward port from 2.0 branch:
      Changed the <VirtualHost> example in the conf/httpd.conf-dist file so it
      now uses _default_ instead of the server name. This is more portable and
      totally sufficient for our default configuration where only one virtual
      host is present.

   *) Fixed INSTALL document: rsaref.a has to be copied to librsaref.a

   *) Totally revised my mod_sslcompat idea because it's not really
      practical to have the backward compatibility stuff outside the standard
      mod_ssl code. Another reason is that by including it again into the
      mod_ssl stuff the code gets easier.

   *) Fixed pass phrase dialog: The server name was always displayed
      for a new pass phrase. 

   *) Added support for the idea of SSL_CLIENT_CERT_CHAIN<N> variables (Mark
      Shuttleworth, Thawte Consulting) which enables CGI scripts to verify the
      client certificate chain up to the root:
      SSL_CLIENT_CERT_CHAIN_0 = end entity cert
      SSL_CLIENT_CERT_CHAIN_1 = issuer cert
      SSL_CLIENT_CERT_CHAIN_2 = issuer's issuer cert ...
      But because of problems with system resource limits this is currently
      disabled.

   *) Added support for automatically determining the DBM library. 
      When a vendor DBM library is available we now use this one (because
      typically this is a better and faster one than SDBM).  Only when no
      vendor DBM library could be found we fallback to our built-in SDBM
      library (which is slow, but portable).
   
   *) Splitted the mod_ssl.html document into smaller parts for easier
      reading and maintaining. Same for the CHANGES file. The entries for
      mod_ssl 2.0.x are now stores in CHANGES.20 while mod_ssl 2.1bx entries
      are staying in the CHANGES file.

   *) Fixed some pre-processor and variable declaration inconsitencies 
      which forced portability problems under some non-GCC compilers.

  Changes with mod_ssl 2.1b3 (06-Sep-1998 to 08-Sep-1998)

   *) Removed a few unneccessary local buffer usages in the mod_ssl-related
      code in mod_log_config.c.

   *) Updated the documentation for the recent changes, especially for the new
      SSLRequire directive and the new provided CGI/SSI variables. I've now
      also added a new FAQ which tries to explain why SSL cannot be used
      together with name-based virtual hosts (IP-based virtual hosts have to
      be used).

   *) Fixed ssl_log() (the function which is used produce all kinds of
      SSL logfile messages): It failed for messages with "%" because
      it insecurely used fprintf at some points.

   *) Added --quiet|-q, --verbose|-v and --help|-h options to mod_ssl's
      `configure' script for controlling the verbosity and for more user
      friendlyness.

   *) Now the mod_ssl `configure' script creates a `config.status' script as
      APACI does. This can be used for re-configuring mod_ssl the same way one
      does it for Apache.

   *) The top-level APACI Makefile now gives a hint for `apachectl start-SSL'
      (which internally uses the `httpd -DSSL' command).

   *) Now on `make certificate' the hash symlinks in conf/sslcerts/ are
      generated via the provided Makefile instead of directly linking (which
      fails under some platforms).

   *) Added boolean expression scanning/parsing/evaluation as ssl_expr_*
      sources and a new SSLRequire directive which now uses this
      functionality.  This directive can be used in both per-server and
      per-directory context and has the syntax ``SSLRequire <expr>'' where
      <expr> is defined as:

        expr     ::= "true" | "false" 
                   | "!" expr
                   | expr "&&" expr
                   | expr "||" expr
                   | "(" expr ")"
                   | comp
        comp     ::= word "==" word | word "eq" word
                   | word "!=" word | word "ne" word
                   | word "<"  word | word "lt" word
                   | word "<=" word | word "le" word
                   | word ">"  word | word "gt" word
                   | word ">=" word | word "ge" word
                   | word "in" "{" wordlist "}"
                   | word "=~" regex
                   | word "!~" regex
        wordlist ::= word 
                   | wordlist "," word
        word     ::= digit
                   | cstring
                   | variable
                   | function
        digit    ::= [0-9]+
        cstring  ::= "..."
        variable ::= "%{" [a-zA-Z][a-zA-Z0-9_-]* "}"
        function ::= funcname "(" funcargs ")"

      Here for %{XXXX} mostly _all_ possible server variables can be looked
      up: the standard CGI variables, the SSL CGI variables, the internal
      variables known from mod_rewrite, etc. pp. The intent is the following:
      With <expr> one can specifiy an arbitrary complex boolean expression
      which is evaluated under runtime. When it evaluates to "true" access for
      the current request is granted. If it evaluates to "false" access for
      the current request is denied. The main use for this is for flexible
      certificate screening (because one can lookup all certificate X.509
      fields via %{SSL_CLIENT_xxx}). But it can be used for other
      authentication schemes, too.

      This is now the general authentication workhorse. With it we were able
      to remove the too special SSLRequireCipher and SSLBanCipher directives
      because their functionalities are just special cases of a boolean
      expressions:

      SSLRequireCipher C1 C2 ... => SSLRequire %{SSL_CIPHER} in ("C1", "C2", ...)
      SSLBanCipher     C1 C2 ... => SSLRequire not %{SSL_CIPHER} in ("C1", "C2", ...)

      For mod_ssl 2.1.0 (the release version) the above mapping will be done
      automatically on the fly by the backward-compatibility code.

   *) Removed the __SSLeay prefix inside the source now that the function
      prefixes are documented in the README file.

  Changes with mod_ssl 2.1b2 (02-Sep-1998 to 06-Sep-1998)

   *) Added the first cut of HTTPS support for the proxy module. This is
      currently done by making the generic HTTP handler SSL-aware. But it
      still doesn't provide support for client or server authentication nor
      does it provide a way to configure it. Later we'll add perhaps
      SSLProxyXXXXX directives to allow the users to configure the SSL client
      inside the proxy.  But beside this it's full functional. One can use it
      for proxying https://xxx URLs and also use `ProxyPass https://xxxx'.
      (the sources of SSLeay's s_client and cURL were my friends ;-)

   *) Replaced old kludges in mod_log_config.c and mod_ssl sources to
      determine SSL protocol name with the clean SSL_get_version() which
      already exists in SSLeay 0.8 and 0.9.

   *) As a of the new ssl_var_lookup() the function ssl_ExpandCert() with the
      old less-portable and unclean parsing stuff (parsed the DN into the
      fields on a string basis instead of correctly determining the fields
      from SSLeay structures) was kicked out and the environment annotation is
      now done with generic variable lookups. 

   *) Added a new source file named ssl_engine_vars.c which contains
      a waterfall approach to expanding arbitrary server+SSL variables.  The
      main function is ssl_var_lookup() which can operate in different
      contexts. The idea is to resolve information mainly through this
      function when it's required. Currently the usage is: logfile entries,
      environment annotation. In the future this will be also used for the
      SSLRequire directive.

   *) Cleaned up the API command configuration and shortened the code by using
      #defines. Additionally removed the polymorphic command handling
      functions with real ones (less pointer arithmetic and preparation for
      more config-time syntax checks).

  Changes with mod_ssl 2.1b1 (26-Aug-1998 to 02-Sep-1998)

   *) Again completely rewrote the pass phrase handling. This time because the
      recent dicussions on the sw-mod-ssl mailing lists showed that the direct
      caching of pass phrases under run-time and the forcing of the
      administrator to use a single pass phrase for all private key files is
      not really reasonable. Now the pass phrase handling looks this way:

      1. A directive `SSLPassPhraseDialog builtin|exec:/path/to/program'
         is used for configuring the pass phrase dialog. The `builtin' is a
         terminal based dialog while `exec:/path/to/program' runs an external
         program (which gets `servername:port' as the argument for which the
         pass phrase has to be given on stdout).

      2. The `builtin' terminal dialog is now a lot different:
         First it detacts wrong pass phrases and gives reasonable error
         messages and second it uses Holger Reif's maximum-reuse idea for the
         pass phrase query:

         When a private key file is encrypted, all known pass phrases (at the
         beginner there are none, of course) are tried. If one of those known
         pass phrases succeeds no dialog pops up for this file.  If none
         succeeded, another pass phrase is queried and remembered for the next
         round (where it perhaps can be reused).  This scheme allows mod_ssl
         to be maximum flexible (because for N encrypted private key files you
         _can_ use N different pass phrases - but then you have to enter all
         of them, of course) while minimizing the dialog (i.e.  when you use a
         single pass phrase for all N private key files this pass phrase is
         queried only once).

      3. After the pass phrase dialog the temporarily remembered pass phrases
         are immediately wiped out from memory. Instead only the
         SSLeay-internal representation of the RSA private key and the X.509
         certificate are stored (as SSLeay already does itself). For this a
         per-module global configuration pool is used which survives Apache
         server restarts. This means that Apache will again no longer fall
         down on restarts.

   *) Beside the per-directory and per-server context configurations 
      we now use a per-module global configuration pool which survives both
      the Apache API 2nd init round and server restarts. This is done by using
      an own permanent memory sub-pool. The idea for this tricky approach
      which came from Philip Gwyn. This global configuration pool now holds
      _all_ previous global variables (ssl_g_xxx). This way mod_ssl now uses
      only a single global variable.

   *) Added ssl_engine_ds.c source which contains new data structures (array
      and table) which are based on Apache's API arrays but can contain
      arbitrary data (important especially for the tables).

   *) Removed all explicit ap_clear_pool() calls which are no longer
      necessary because we already got rid of the gcache stuff
      which required it.

   *) Moved all pass phrase handling stuff into own file ssl_engine_pphrase.c
      source file

   *) Now the error messages which are duplicated to the general
      Apache error logfile are prefixed with "mod_ssl:" there to
      indicate from where they come.

   *) Forward-port from 2.0.6: Added RSAref support for the US-citizens:
      mod_ssl now automatically recognizes an SSLeay compiled with -DRSAref,
      automatically finds libRSAglue and librsaref.a or rsaref.a.
      Additionally beside SSL_BASE now the variable RSA_BASE can be used to
      select a particular RSAref source tree (if not installed under system
      locations).  This way mod_ssl provides out-of-the-box support for
      SSLeay+RSAref.

   *) Changed SSLSessionCacheDefault from 0 (none) to a reasonable
      300s default.

   *) The socket connection message in the SSL Engine logfile now
      also displays the Cipher keysizes for even more information
      about the connection.

  Changes with mod_ssl 2.1b0 (17-Aug-1998 to 26-Aug-1998)

   *) Added a few files to the distribution: First my PGP public key as
      ssl.contrib/rse.pgp to the distribution so people can use it on
      forthcoming releases to verify the tarballs signature. Second the files
      WISHES and TODO which contain the mod_ssl wishlist and the ToDo-list for
      2.1.0.

   *) Finally fixed the SSL connection deallocation and removed the old
      FREE_SESSION stuff.

   *) Added support for annotating SSLeay error messages. Now some
      of the raw-level SSLeay error messages are automatically annotated with 
      high-level hints. For instance the unmeaningly message
      ``error:06065064:digital envelope routines:EVP_DecryptFinal:bad
      decrypt'' now reads ``...routines:EVP_DecryptFinal:bad decrypt [Hint:
      wrong pass phrase!?]'' etc.

   *) Removed ERR_load_crypto_strings() call because it's already contained in
      SSL_load_error_string() from SSLeay 0.8 and 0.9.  Additionally now a
      ERR_clear_error() is done after each logfile entry was written to make
      sure no unread SSLeay errors are kept and occur with later messages
      (where they would confuse people).

   *) Renamed `SSLLogFile' to `SSLLog' because it isn't always a file,
      it also can have an argument "|/path/to/filter" and act as
      a reliable pipe to a logging filter program.

   *) Renamed `SSLRequiredCiphers' directive to `SSLCipherSuite'
      because the Apache-SSL directivename `SSLRequiredCiphers' was a full
      accident. Because first it always got intermixed with the per-directory
      context directive `SSLRequireCipher'. And second this sets not Ciphers
      which are all `required'. It just sets the Ciphers the clients is
      permitted to negotiate (the client actually chooses only _one_ Cipher).

   *) Added SSLMutex for mutal expclusion of server process operations.
      This is currently used only for synchronizing access to the new Session
      Cache stuff. Three variants can be configured: `SSLMutex none' (no mutex
      at all - works but risky), `SSLMutex file:/path/to/lockfile' (portable)
      and `SSLMutex ipcsem' (elegant but not portable).

   *) Moved the backward compatibility stuff into its own module:
      mod_sslcompat. This module now already provides configuration directive
      compatibility for both Apache-SSL and Sioux.  More (Stronghold?) can be
      add later, too. Additionally a mod_sslcompat.html document was written
      which described the provided configuration directive mapping.

   *) Split the mod_ssl sources from its large 70KB file into smaller chunks,
      which are now mainly named accoring to the logical modules they contain.
      This way the source inside src/modules/ssl/ is easier to overview.  Just
      one minor drawback: We lose a lot of nice `static' and have to prefix
      really _all_ functions with `ssl_' now.

   *) Replaced the gcache stuff from Apache-SSL days and replaced it
      by a more simple but even more flexible approach. Now the new
      `SSLSessionCache' directive replaces `SSLCacheServerPath' and
      `SSLCacheServerPort'.  The SSLSessionCacheTimeout remains and has the
      old semantics.  So, where is the difference? The old gcache stuff was
      like this: An extra process (ssl_gcache) was running in parallel to the
      httpd server processes and listening to a socket. Through SSLeay
      callbacks the internal SSLeay caches of all server processes were synced
      with this global cache.  For this socket connections were established.
      The drawback of this approach were:

      1. The nasty fiddling with the extra child process was totally buggy

      2. The gcache program itself used another local memory cache. This
         was totally unnecessary because SSLeay already caches the stuff in a
         local memory cache. So, under Apache-SSL three cache layers were used
         (1: SSLeay internal, 2: gcache internal, 3: gcache external) while
         layer 2 is not needed.

      So the intent now was to replace this with a better solution. The idea
      came from Stronghold: We either cache the information never (the
      default), in a hashfile on the local disk (the portable variant -
      already implemented) or even in a hash structure inside a shared memory
      segment ( (non-portable, but fast and elegant - still not implemented,
      only stubs were created to plug this in later).

   *) CORRECTLY SOLVE THE PASS PHRASE DIALOG PROBLEM (the problem is that
      Apache detaches from the terminal before the SSLeay pass phrase dialog
      pops up). First I got rid of the ugly and unsuccessful filedescriptor
      hacks Ben added recently to Apache-SSL because they do not work under
      all platforms as expected. Second I re-ordered the control flow to allow
      the following processing:
      
      Now at the 1st round of the Apache API init cycle the servers are
      scanned for certificate and key files and the first one which uses an
      encrypted key forces the pass phrase dialog to pop up. This dialog is
      either an interactive builtin terminal dialog (`SSLPassPhraseDialog
      builtin' - which is similar to SSLeay default dialog) or can be driven
      in batch by a filtering program which is run once and has to provide the
      pass phrase on stdout (`SSLPassPhraseDialog /path/to/program').  After
      this the pass phrase is _temporarily_ stored in memory for use later in
      the 2nd round of the Apache API init cycle. Now additionally this pass
      phrase can be kept in memory (`SSLPassPhraseCaching on') for forthcoming
      server restarts (`kill -HUP') or is explicitly wiped out from memory
      (`SSLPassPhraseCaching off' - for the paranoid users).

      The following combinations are possible:

      1. THE SMART DEFAULT VARIANT:
         `SSLPassPhraseDialog builtin' + `SSLPassPhraseCaching on':
         This is the default which is reasonable for most of the users. This
         way on Apache startup time the pass phrase is requested on the
         terminal but kept in memory for all forthcoming restarts.

      2. THE THEORY VARIANT:
         `SSLPassPhraseDialog builtin' + `SSLPassPhraseCaching off':
         This combination leads to a server fall-down on any occuring restarts
         because the terminal dialog _cannot_ be done at restart time (Apache
         is already detached).  So, this combination is only interesting in
         theory but should be avoided because its not really useful in
         practice.  

      3. THE BATCH VARIANT:
         `SSLPassPhraseDialog /path/to/program' + `SSLPassPhraseCaching on':
         This is for users who want to remote control the Apache startup or
         make it automatic by controlling the dialog from within a program.
         This program is run only once at startup. Then the pass phrase is
         kept in memory for forthcoming restarts.

      4. THE PARANOIA VARIANT: 
         `SSLPassPhraseDialog /path/to/program' + `SSLPassPhraseCaching off':
         This is for the really paranoid users who want avoid any pass phrase
         caching. Instead both on startup and restart time the pass phrase has
         to be provided by an external program.
      
   *) The SSL logfile is now placed in the main server instead of the virtual
      host because its actually a global logfile, even when it could be used
      only inside a virtual server.  

   *) The expensive operation of generating the temporary RSA key is now done
      before Apache forks the server processes. This speeds up the startup
      phase a little bit.

   *) Added new SSLCACertificateReqFile directive which defaults to the value
      of SSLCACertificateFile. It sets the all-in-one file where one can
      assemble the Certificates of Certification Authorities (CA) whose
      servers you deal with. These are optionally used by the clients for
      SSLv3 Server Authentication to speedup processing. The file is requested
      by the client via the "SSLv3 write certificate request A" for loading
      intermediate CA certificates in the certificate chain (only SSLv3). It
      is simply the concatenation of the various PEM-encoded certification
      files, in order of preference.  

   *) Inlined some functions like init_SSLeay() and init_VerifyType() because
      they were really small functions and only used once in mod_ssl. These
      were stand-alone functions in Apache-SSL without real need.

   *) Made `SSLEnable'/`SSLDisable' directives obsolete by adding the simpler
      `SSEngine on|off'. The old directives are now deprecated but still can
      be used for backward-compatibility with Apache-SSL. Additionally the
      default is now `SSLEngine off' (formerly `SSLDisable') instead of the
      Apache-SSL default of `SSLEngine on'. This breaks a little bit with
      Apache-SSL semantics, but doesn't hurt as much as it sounds.  Because
      people run SSL inside a virtual hosts and thus already have a SSLDisable
      in their main (non-SSL) server. The difference is just that with mod_ssl
      one no longer has to add SSLDisable to all non-SSL virtual hosts (which
      is nasty).  OTOH SSL is an additional feature, so the logic of "disabled
      per default and have to be enabled explicity" is more useful and what is
      expected.

   *) The "SSL rubbish logfile" of Apache-SSL was now replaced by real
      dedicated SSL logfile which contains no longer "rubbish".  For this the
      logging mechanism in mod_ssl was completely re-written from scratch and
      now looks like this:

      1. `SSLogFile <file>' is optional
      2. `SSLogFile /dev/null' disables the logging _without_ overheads
      3. `SSLLogLevel <level>' controls the degree of verbosity in SSLLogFile
      4. `SSLogLevel none' disables the logging _without_ overheads and is the
         default.
      5. Log messages of type `error' are _always_ duplicated to 
         the Apache general error logfile, even under `SSLLogLevel none'.
      6. The maximum logging can be now achieved by using `SSLLogLevel debug'.

      Additionally obsolete logging stuff from Apache-SSL was removed from the
      source code.  Finally the logfiles in the provided default config were
      changed: ssl_log is now the dedicated SSL protocol logfile (SSLLogFile)
      while the custom logfile (CustomLog) containing only one line per
      request is now named ssl_req_log.

