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


  Versions
  --------

  Because mod_ssl is a 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.7         0.8.0 - 0.9.0b

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

  To use mod_ssl you need at least the following two packages:

   o  Package:      Apache 
      Version:      1.3.x
      Description:  Apache Group HTTP Server
      Homepage:     http://www.apache.org/
      Distribution: http://www.apache.org/dist/
      Tarball:      apache_1.3.x.tar.gz
      Location:     SF, USA
      Author(s):    The Apache Group <apache@apache.org>

   o  Package:      mod_ssl
      Version:      2.0.x
      Description:  Apache Interface to SSLeay
      Homepage:     http://www.engelschall.com/sw/mod_ssl/
      Distribution: http://www.engelschall.com/sw/mod_ssl/dist/
      Tarball:      mod_ssl-2.0.x-1.3.x.tar.gz
      Location:     Zurich, Switzerland, Europe
      Author(s):    Ralf S. Engelschall <rse@engelschall.com>

  If you have the SSLeay package not already installed on your system you
  additionally need the following:

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

  And if you're a US-citizen then you need (because of patent legalities) also
  the following package in conjunction with SSLeay:

   o  Package:      RSAref
      Version:      2.0
      Description:  RSA Reference Implementation
      Homepage:     -
      Distribution: ftp://ftp.rsa.com/rsaref/*/
      Tarball:      rsaref20.tar.Z
      Location:     USA
      Author(s):    RSA

  Finally you need the following auxiliary packages already installed (GZip
  for unpacking the above tarballs and Perl for building SSLeay):

   o  Package:      GZip
      Version:      1.2.4
      Description:  The compression utility
      Homepage:     http://www.gnu.org/
      Distribution: ftp://ftp.gnu.org/pub/gnu/
      Tarball:      gzip-1.2.4.tar.Z
      Location:     USA
      Author(s):    Free Software Foundation
 
   o  Package:      Perl
      Version:      5.004 or 5.005
      Description:  The Practical Extraction and Reporting Language
      Homepage:     http://www.perl.com/
      Distribution: http://www.perl.com/CPAN/src/
      Tarball:      perl5.00x.tar.gz
      Location:     USA
      Author(s):    Larry Wall


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

  The following is a step-by-step list on how to install an SSL-aware Apache.
  It's actual steps you have to perform depend on the location where _YOU_ and
  your webserver stay.  So the commands are marked at the right-side with the
  following tags:
  
  US ........ Command has to be run by citizens of the United States only
  EU ........ Command has to be run by citizens of a European state only
  ALL ....... Command has to be run by anyone, independend of location
  OPTIONAL .. Command is optional

  Now follow these steps:

   1. Make sure GZip and Perl are already installed and available through the
      commands `gzip' and `perl' They are needed for unpacking the tarballs
      and for configuring SSLeay.

   2. Extract the required packages:

      $ gzip -d -c apache_1.3.x.tar.gz | tar xvf -                         ALL
      $ gzip -d -c mod_ssl-2.0.x-1.3.x.tar.gz | tar xvf -                  ALL
      $ gzip -d -c SSLeay-0.9.x.tar.gz | tar xvf -                         ALL
      $ mkdir rsaref-2.0                                                    US
      $ (cd rsaref-2.0; gzip -d -c ../rsaref20.tar.Z | tar xvf -)           US

   3. Configure and build the SSLeay library: 
      (When you're a US-citizen you have to build SSLeay in conjunction with
      the RSAref library)

      $ cd rsaref-2.0
      $ cp -rp install/unix local                                           US
      $ cd local                                                            US
      $ make                                                                US
      $ mv rsaref.a librsaref.a                                             US
      $ cd ../..                                                            US
      $ cd SSLeay-0.9.x                                                    ALL
      $ make -f Makefile.ssl links                                         ALL
      $ perl ./Configure gcc                                               ALL
             -DNO_IDEA                                                      EU
             -DRSAref -lRSAglue -L`pwd`/../rsaref-2.0/local/ -lrsaref       US
      $ cp rsaref/rsaref.h include/                                         US
      $ make                                                               ALL
      $ make rehash                                                   OPTIONAL
      $ make test                                                     OPTIONAL
      $ cd ..                                                              ALL

      NOTE: When your system already has RSAref installed in system locations
            you can ignore the RSAref-related steps above and instead below
            use `RSAREF_BASE=SYSTEM' instead of `RSAREF_BASE=../rsaref-2.0'

      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 `perl 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
            `-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 the SSLeay steps above, too.
            Instead use `SSL_BASE=SYSTEM' instead of
            `SSL_BASE=../SSLeay-0.9.0b' below.

  4. Now apply the mod_ssl source extension and source patches to the Apache
     source tree, configure the Apache sources and build Apache with mod_ssl
     and SSLeay. 
     
     Actually here you have three options :
     (dependend of your situation and skill ;-)

     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 and
        RSA_BASE variables but get no intermediate chance to add more
        third-party Apache modules (e.g. mod_perl, PHP3, etc).

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

        NOTE: You either use only one of `--with-certifcate' and `make
              certificate' above or none of them. The `--with-certificate' is
              when you already have a real server certificate at hand while
              `make certificate' is to create a self-signed server test
              certificate.

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

        You configure Apache manually and have the chance to configure and add
        third-party Apache modules like mod_perl or PHP3. But you have to
        provide the SSL_BASE and RSA_BASE variables 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                                           ALL
        $ ./configure                                                      ALL
              --with-apache=../apache_1.3.x                                ALL
              --with-certificate=/path/to/your/server.pem             OPTIONAL
        $ cd ..                                                            ALL
        [...Now add more Apache modules to the Apache source tree...] OPTIONAL
        $ cd apache_1.3.x                                                  ALL
        $ SSL_BASE=../SSLeay-0.9.x                                         ALL
          RSA_BASE=../rsaref-2.0                                            US
          ./configure                                                      ALL
              --prefix=/path/to/apache/install/dir                         ALL
              [...more APACI options...]                              OPTIONAL
        $ make                                                             ALL
        $ make certificate                                            OPTIONAL
        $ make install                                                OPTIONAL

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

        You configure Apache manually by editing the src/Configuration.tmpl
        file 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 and RSA_BASE
        variables 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                                           ALL
        $ ./configure                                                      ALL
              --with-apache=../apache_1.3.x                                ALL
              --with-certificate=/path/to/your/server.pem             OPTIONAL
        $ cd ..                                                            ALL
        [...Add more Apache modules to the Apache source tree...]     OPTIONAL
        $ cd apache_1.3.x/src                                              ALL
        $ cp Configuration.tmpl Configuration                              ALL
        $ vi Configuration                                                 ALL
        [...edit the SSL_BASE variable...]                                 ALL
        [...edit the RSA_BASE variable...]                                  US
        [...edit the `AddModule' line of libssl.a...]                      ALL
        $ ./Configure                                                      ALL
        $ make                                                             ALL
        $ make certificate                                            OPTIONAL

        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 (only HTTP possible):

     $ /path/to/apache/install/dir/sbin/apachectl start                    ALL
     $ netscape http://<local-host-name>/                                  ALL
     $ /path/to/apache/install/dir/sbin/apachectl stop                     ALL

     NOTE: Replace the "<local-host-name>" with the official name of your
           host. Do not enter "localhost" here, because this name has to match
           the Subject DN of your server certificate.

  6. Try out the beast with SSL enabled (HTTP and HTTPS possible):

     $ /path/to/apache/install/dir/sbin/apachectl startssl                 ALL
     $ netscape http://<local-host-name>/                                  ALL
     $ netscape https://<local-host-name>/                                 ALL
     $ /path/to/apache/install/dir/sbin/apachectl stop                     ALL

     NOTE: Replace the "<local-host-name>" with the official name of your
           host. Do not enter "localhost" here, because this name has to match
           the Subject DN of your server certificate.

     NOTE: When the above tests (steps 5 and 6) fail for some reasons
           you are _STRONGLY ADVICED_ to look into the Apache error logfile
           before you ask someone other for help. In the error logfile there
           should be a hint where to find the reason for the failure.

  7. Finally read the mod_ssl documentation under
     http://<local-host-name>/manual/mod/mod_ssl.html carefully and adjust
     your configuration under /path/to/apache/install/dir/etc/httpd.conf.

  8. Bask in the glow ;-)

