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


  The conflict: mod_ssl vs. Apache-SSL
  ------------------------------------

  The general question is 
  
     ``Why is there a need for another free SSL interface for 
       Apache although there is already Ben Laurie's popular 
       Apache-SSL available?''

  There is no general single answer, but here are a few hints:

   1. Ben's work on Apache-SSL over the last years was really good and I honor
      the effort he has spent to make Apache-SSL work. There is really no
      doubt. Give Ben all the credit for the SSL internals, especially the
      complicated interfacing to SSLeay.

   2. I'm sorry to say that Ben had and still has very different goals with
      his Apache-SSL package and user friendliness is not really one of them.
      But user friendliness is one of my major goals. Just because security is
      not for amateurs doesn't mean that user friendliness is not important.
      So, here are a few unintelligible facts about Apache-SSL which were IMHO
      not acceptable (based on the Apache-SSL 1.18 release from where I
      started with mod_ssl) and which were reasons why mod_ssl was created:

      o Apache-SSL is not reviewable by the end user:
      
        Apache-SSL uses as its main part an apache_ssl.c source file.  Beside
        some minor problems (for instance the filename which doesn't
        seamlessly integrate into Apache's configuration scheme, a few
        inconsistencies in the code, etc.) the most important drawback of this
        source is that it's totally un-reviewable by the average webmaster.

        Not even an Apache expert can immediately review it (I'm an Apache
        expert, but I needed over two weeks to understand it and to clean it
        up).  BUT FOR SECURITY RELATED SOFTWARE IT HAS TO BE ONE OF THE MAJOR
        GOALS TO MAKE THEM REVIEWABLE BY THE END USER AND NOT ONLY BY THE
        AUTHOR. At least when it's _free_ security software for which no
        commercial support exists. Sure, for SSLeay this is even more
        complicated, but that doesn't mean that the Apache SSL interface can
        ignore this requirement.

        [For a complete list of cleanups and fixes I've done for mod_ssl
        please read the CHANGES file.]

      o Apache-SSL is not documented as one would expect it:
      
        Apache-SSL exists for over three years now but still doesn't provide a
        mod_ssl.html document which at least briefly describes the module
        directives. Not only the README does it. Book authors I've asked about
        Apache-SSL said that no module caused them such a lot of time to
        document in their books than Apache-SSL. Think about it.

        [I've now written an mod_ssl.html document for the user which
        describes all directives, environment variables and even contains some
        FAQs]

      o Apache-SSL is not easily applicable to an Apache source tree:
      
        Apache-SSL still just provides its source patch and don't helps the
        user to apply it easily to the Apache source tree (compare the GNU
        patch V2.1 vs. V2.4 incompatibilities, the prefix stripping issue,
        etc.) Just because one thinks security software is not for amateurs
        haven't mean that has to be complicated to build.

        [I've created a configure script and a stripped down 'patch' tool for
        mod_ssl which assists in applying mod_ssl to the Apache source tree
        and totally avoids any manual hacking] 

      o Apache-SSL cannot be cleanly configured under Apache built-time:
        
        Apache-SSL patches src/Makefile and other files inside the Apache
        source tree which then have to manually edited by the user again for
        SSLeay paths, etc. And Apache-SSL doesn't provide clean integration
        into both APACIs build and install process.

        [For mod_ssl _NO MORE_ editing of configuration files and Makefiles is
        required. Everything can be specified on the 'configure' command line.
        Additionally mod_ssl is integrated into the APACI install process.
        Even the differences between an installed SSLeay and an
        out-of-the-source-used SSLeay is automatically recognized.]

  As you can see from just these few points, the internals of Apache-SSL and
  mod_ssl are still very similar. But the way it is provided is totally
  different. 
  
  You can be sure that I've tried hard to find a consensus with Ben Laurie in
  merging mod_ssl into Apache-SSL. Because I wanted to avoid splitting the
  world. But after four(!) weeks of intensive private discussions between us
  we had to came to the conclusion that our personal goals are such different
  that it's _currently_ not possible to reach a compromise for merging the two
  packages which are acceptable to both of us. 
  
  The first main reason for this situation is that my development
  approach for mod_ssl (a CVS tree where Apache 1.3 stays on the vendor branch
  while the mod_ssl stuff is assembled from HEAD, etc.) is more complex than
  Ben wants to accept. He prefers manual editing the patches for every
  release even when the user would greatly benefit from the more complex
  approach. OTOH I prefer an automated CVS approach because this way first one
  can faster produce the SSL interface for every Apache release and second:
  this way the application to the Apache source tree is more robust because
  the patches are directly assembled out of CVS.

  The second main reason is that Ben still cannot accept that I've changed
  Apache-SSL in such a massive way and entered the Apache-SSL developer area,
  although I let him know this a couple of times while I worked on mod_ssl.
  This reason we have to accept but cannot be changed by me. Because I _had_
  to change the source and distribution stuff such dramatically to be able to
  achieve my main goals: cleanness, better support for reviewers, existing
  documentation and robust application to the Apache source tree. One cannot
  achieve them by just patching again.  One has to do a cleanup from the
  ground up!

  I'm still open to merge mod_ssl into Apache-SSL in the future, no doubt. But
  at this time it's better to avoid any more opinion wars and distribute the
  two SSL interfaces separately, even when this causes some confusion to the
  user. At least under configuration- and run-time there are still no
  differences, so this is not really a problem for the user community. My hope
  is that after the users have recognized the benefits of what mod_ssl
  provides, Ben will finally recognize it, too. And then it's perhaps easier
  for us to find an acceptable way to let mod_ssl merge with Apache-SSL.

  So, the user now should think about Apache-SSL and mod_ssl similar to the
  situation of GCC and EGCS: Both provide mostly the same package, but the
  first one more conservative while the latter one follows new technologies
  and provides more features. Decide on your own which one you like best and
  use it.

  Incompatibilities to Ben Laurie's Apache-SSL
  --------------------------------------------

  Ok, now that you know the conflict, the question is: 
  
  ``What visible incompatibilities exist between mod_ssl 
    and Apache-SSL the user should be aware of?'' 
    
  Here is a list of all user visible changes:

   o  ``<IfModule apache_ssl.c>'' ==> ``<IfModule mod_ssl.c>''

      Because of the renamed source files, when you used <IfModule> containers
      inside your httpd.conf file to encapsulate Apache-SSL directives, you
      now have to use the filename mod_ssl.c instead. Although such changes
      are nasty for the users the new name directly follows the Apache module
      conventions.

   o  ``Ben-SSL/1.18'' ==> ``mod_ssl/2.0.0 SSLeay/0.9.0b''

      Because the workhorse of SSL inside Apache is SSLeay and not mod_ssl,
      the SSLeay version is more important in the HTTP Server field. So both
      mod_ssl's and SSLeay's version is now added to the Server field.

   o  ``httpd -DSSL''

      The provided (and installed) _default_ configuration is SSL-ready but
      has the SSL-related directives in an <IfDefine SSL> section.  So, when
      you immediately want to fire up your httpd with SSL enabled you have to
      specify the -DSSL option on the command line. Or edit the
      configuration. 

   o  ``Reading certificate and key for server...''
      ``Skip first time initialization...''
      ``Launching...''

      These verbose terminal messages of Apache-SSL were disabled because its
      nasty to get those messages when a daemon is run (especially when its
      run from Boot scripts or Cron scripts). Instead the remaining useful
      ones are now printed to the Apache error_log.

  Anything else should be internal changes, only. For a complete
  list please read the CHANGES file.

