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


  Versions
  --------

  Because mod_ssl is an source extension and set of source patches for the
  Apache source tree it highly depends on Apache's version. That's the reason
  why mod_ssl's version number has Apache's version number appended to it. The
  following table shows you which version of mod_ssl can be used for which
  version of Apache. The version of SSLeay is also important.

      If you have         ... you have to use ...in combination with
      Apache version...   mod_ssl version...  SSLeay version...
      ------------------- ------------------- ----------------------
      <= 1.3.0            not available       not available
       = 1.3.1            2.0.0-2.0.4         0.8.0 - 0.9.0b

  Prerequisites
  -------------

  To use mod_ssl you need the following packages:

   o  Package:      Apache 
      Version:      1.3.x
      Description:  Apache Group HTTP server project
      Homepage:     http://www.apache.org/
      Distribution: http://www.apache.org/dist/
      Location:     SF, USA
      Author(s):    The Apache Group <apache@apache.org>

   o  Package:      SSLeay
      Version:      0.9.x
      Description:  SSLv3 implementation library 
      Homepage:     http://www.ssleay.org/
      Distribution: ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/
      Location:     Brisbane, Australia
      Author(s):    Eric A. Young <eay@cryptsoft.com>
                    Tim Hudson <tjh@cryptsoft.com>

   o  Package:      mod_ssl
      Description:  Apache 1.3 module to interface with SSLeay
      Homepage:     http://www.engelschall.com/sw/mod_ssl/
      Distribution: http://www.engelschall.com/sw/mod_ssl/dist/
      Location:     Zurich, Switzerland, Europe
      Author(s):    Ralf S. Engelschall <rse@engelschall.com>
 
  Additionally you need the following auxiliary packages installed:

   o  Package:      GZip
      Version:      1.2.4
      Description:  The compression utility
      Homepage:     http://www.gnu.org/
      Distribution: ftp://ftp.gnu.org/pub/gnu/
      Location:     USA
      Author(s):    Free Software Foundation
 
   o  Package:      Perl
      Version:      5.004
      Description:  The Practical Extraction and Reporting Language
      Homepage:     http://www.perl.com/
      Distribution: http://www.perl.com/CPAN/
      Location:     USA
      Author(s):    Larry Wall


  Installation
  ------------

   1. Make sure GZip and Perl are already installed and available through the
      commands `gzip' and `perl'.

   2. Extract the three required packages:
   
      $ gzip -d -c apache_1.3.x.tar.gz | tar xvf -
      $ gzip -d -c mod_ssl-2.0.x-1.3.x.tar.gz | tar xvf -
      $ gzip -d -c SSLeay-0.9.x.tar.gz | tar xvf -

   3. Configure and build the SSLeay library

      $ cd SSLeay-0.9.x
      $ make -f Makefile.ssl links
      $ perl ./Configure gcc [...MORE OPTIONS...]
      $ make
      $ make rehash
      $ make test
      $ cd ..

      NOTE: SSLeay understands a lot more options on the Configure
            command line. For instance you can replace the generic `gcc' with
            your platform name (run `Configure' without arguments to see a
            list of supported platforms) to get maximum performance (because
            on some platforms assembler routines are used instead of C
            variants). Additionally you can add command line options like
            `-DNO_IDEA' for disabling IDEA in Europe, `-DRSAref' for enabling
            the use of the RSAref library in USA or `-DSSL_ALLOW_ENULL' for
            allowing null encryptions, etc.

      NOTE: When your system already has SSLeay installed (for instance some
            Linux distributions ship with SSLeay installed out-of-the-box) in
            system locations you can ignore this step 3.) and instead use
            below `SSL_BASE=SYSTEM' instead of `SSL_BASE=../SSLeay-0.9.0b'

  4. Apply the mod_ssl source extension and source patches to the Apache
     source tree, configure the Apache sources via APACI and build Apache with
     mod_ssl and SSLeay. Actually here you have two options:

     a) The all-in-one mod_ssl+APACI way [FOR JOE AVERAGE]:

        You configure Apache semi-automatically from within mod_ssl's
        `configure' script. You don't have to fiddle with the SSL_BASE
        variable but get no intermediate chance to add more third-party Apache
        modules.

        $ cd mod_ssl-2.0.x-1.3.x
        $ ./configure \
              --with-apache=../apache_1.3.x \
              --with-ssleay=../SSLeay-0.9.x \
             [--with-certificate=/path/to/your/server.pem]
              --prefix=/path/to/apache/install/dir
             [...more APACI options...]
        $ cd ..
        $ cd apache_1.3.x
        $ make 

        [If no --with-certificate was used above you now have the]
        [chance to create a self-signed server certificate your  ]
        [own by running `make certificate'.                      ]

        $ make install

     b) The flexible APACI-only way [RECOMMENDED FOR REAL HACKERS]:

        You configure Apache manually and have a chance to configure and add
        more third-party Apache modules like mod_perl or PHP3. But you have to
        provide the SSL_BASE variable manually and either copy your existing
        certificate manually to conf/sslcerts/server.pem or use `make
        certificate':

        $ cd mod_ssl-2.0.x-1.3.x
        $ ./configure \
              --with-apache=../apache_1.3.x \
             [--with-certificate=/path/to/your/server.pem]
        $ cd ..

        ...NOW PERHAPS ADD MORE MODULES TO THE APACHE SOURCE TREE...

        $ cd apache_1.3.x
        $ SSL_BASE=../SSLeay-0.9.x \
          ./configure 
              --prefix=/path/to/apache/install/dir
              [...more APACI options...]
        $ make 

        [Now either copy your existing certificate file to      ]
        [conf/sslcerts/server.pem or create a self-signed server]
        [certificate your  own by running `make certificate'.   ]

        $ make install

     c) The poor mans way known from Apache 1.2 [JUST FOR COMPATIBILITY]:

        You configure Apache manually by editing the src/Configuration.tmpl
        file manually and running the deep-level src/Configure script. The
        advantage here is that this directly follows the steps you might be
        familiar with from Apache 1.2 and additionally you also have a chance
        to add more third-party Apache modules like mod_perl or PHP3 because
        anything is done manually. But you have to edit the SSL_BASE variable
        manually and more important: you have to install the Apache package
        manually, too. But feel free to be masochistic ;-)

        $ cd mod_ssl-2.0.x-1.3.x
        $ ./configure \
              --with-apache=../apache_1.3.x \
             [--with-certificate=/path/to/your/server.pem]
        $ cd ..

        ...NOW PERHAPS ADD MORE MODULES TO THE APACHE SOURCE TREE...

        $ cd apache_1.3.x/src
        $ cp Configuration.tmpl Configuration
        $ vi Configuration
        [...edit the SSL_BASE variable...]
        $ ./Configure
        $ make 

        [Now when you don't already have a real certificate  ]
        [file you can create a self-signed server certificate]
        [your own by running `make certificate'.             ]

        Up to this point it can be acceptable. But now the friendly world
        stops. The remaining installation steps have to be done manually by
        coping the various files to /path/to/apache/install/dir, including
        your certificate, etc. That's the price for staying with the good old
        days...

  5. Try out the beast without SSL enabled:

     $ /path/to/apache/install/dir/sbin/httpd 
     $ netscape http://localhost/

  6. Try out the beast with SSL enabled:

     $ /path/to/apache/install/dir/sbin/httpd -DSSL
     $ netscape https://localhost/

  7. Finally read the mod_ssl documentation under
     http://localhost/manual/mod/mod_ssl.html carefully and adjust your
     configuration under /path/to/apache/install/dir/etc/httpd.conf.

  8. Bask in the glow ;-)

