_ _ _ __ ___ ___ __| | ___ ___| | | '_ ` _ \ / _ \ / _` | / __/ __| | | | | | | | (_) | (_| | \__ \__ \ | mod_ssl - Apache Interface to SSLeay |_| |_| |_|\___/ \__,_|___|___/___/_| http://www.engelschall.com/sw/mod_ssl/ |_____| _____________________________________________________________________________ ``The world does not really need Apache-SSL easier to install.'' -- Ben Laurie, Apache-SSL author INSTALLATION (Unix) Introduction ____________ Because mod_ssl is a complex package there are a lot of installation variants and options. For this different documents exists which explain special things: Read this document when you want to install Apache+mod_ssl under Unix. Read the INSTALL.Win32 document when you want to install it under the Win32 (Windows 95/98/NT) platform. 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: ftp://ftp.apache.org/apache/dist/ Tarball: apache_1.3.x.tar.gz Location: SF, USA Author(s): The Apache Group o Package: mod_ssl Version: 2.2.x Description: Apache Interface to SSLeay Homepage: http://www.engelschall.com/sw/mod_ssl/ Distribution: ftp://ftp.engelschall.com/sw/mod_ssl/ Tarball: mod_ssl-2.2.x-1.3.x.tar.gz Location: Zurich, Switzerland, Europe Author(s): Ralf S. Engelschall If you have the SSLeay package not already installed on your system you additionally need the following package: 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 Tim J. Hudson And if you're an US-citizen then you usually need (because of patent legalities; but check your personal organisation situation first because there are exceptions) 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/ (read the README file there!) ftp://utopia.hacktic.nl/pub/replay/pub/crypto/LIBS/rsa/ Tarball: rsaref20.tar.Z Location: USA Author(s): RSA DSI Finally you need the following auxiliary packages already installed (GZip for unpacking the above tarballs and Perl when configuring 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 (FSF) 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. The 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, independent of location OPTIONAL .. Command is optional and not really needed 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.2.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 an US-citizen you have to build SSLeay in conjunction with the RSAref library. Others can ignore the first six commands, of course) $ cd rsaref-2.0 $ cp -rp install/unix local US $ cd local US $ make US $ mv rsaref.a librsaref.a US $ cd ../.. US NOTE: RSAref has some portability problems. Especially it assumes that an `unsigned long int' represents a four byte word. One result of this bad assumption is that it fails under run-time (not compile-time) on platforms/CPUs, like Alphas, where larger integer sizes are used by the compiler. For instance when mod_ssl's `make certificate' command hangs, you get memory faults or Apache hangs when connecting to it through HTTPS, this all indicates that you ran into this portability problem. The solution is to replace the `typedef unsigned long int UINT4' in rsaref-2.0/source/global.h, line 26. The best is to use `typedef u_int32_t UINT4' when `u_int32_t' is defined by your vendor include files. If not try to use a standard type which is four bytes in length on your platform, e.g. on Alphas `typedef unsigned int UINT4' works. $ 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 test OPTIONAL $ cd .. ALL NOTE: SSLeay understands a lot more options on the `Configure' command line. For instance you can (AND SHOULD!) 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) and platform correctness (some platforms don't work with the generic `gcc' build variant). Additionally you can add some command line options (like `-DSSL_ALLOW_ENULL' for allowing Null encryptions, etc) to adjust the SSLeay internals (see SSLeay's Makefile for details). 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. Then use `SSL_BASE=SYSTEM' instead of `SSL_BASE=../SSLeay-0.9.0b' below. NOTE: When your system already has RSAref installed in system locations you can ignore the RSAref-related steps above and then use `RSAREF_BASE=SYSTEM' instead of `RSAREF_BASE=../rsaref-2.0/local' above. NOTE: You are STRONGLY ADVISES to use SSLeay 0.9.x and not any 0.8.x version. Because although Apache/mod_ssl compiles fine with 0.8.x versions there are known runtime problems with SSLeay 0.8.x. Especially when transferring large files SSLeay 0.8.x fails horrible. So, in your own interest: Use SSLeay 0.9.x, please! BTW, TLS v1 support is also available with SSLeay 0.9.x only. 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 : (dependent on your situation and personal 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.2.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/local \ US --with-crt=/path/to/your/server.crt \ OPTIONAL --with-key=/path/to/your/server.key \ OPTIONAL --prefix=/path/to/apache \ ALL [--enable-shared=ssl] \ OPTIONAL [--disable-rule=SSL_COMPAT] \ OPTIONAL [--enable-rule=SSL_SDBM] \ OPTIONAL [...more APACI options...] OPTIONAL $ cd .. ALL $ cd apache_1.3.x ALL $ make ALL $ make certificate OPTIONAL $ make install ALL $ cd .. NOTE: The --enable-shared=ssl option enables the building of mod_ssl as a DSO `libssl.so'. Read the INSTALL and htdocs/manual/dso.html documents in the Apache source tree for more information about DSO support in Apache. I strongly advise ISPs and package maintainers to use the DSO facility for maximum flexibility with mod_ssl. But notice that DSO is not supported by Apache on all platforms. Additionally SSLeay has problems under DSO situations on some platforms. For instance under smart ix86 platforms like Linux and FreeBSD when you compile a the standard SSLeay libcrypto.a/libssl.a libraries and link those to a mod_ssl DSO libssl.so all works fine. While on other platforms like Solaris 2.6 on a SPARC SSLeay's code will dump core under run-time. When this is the case for you, then try to recompile SSLeay with Position Independent Code (PIC) by adding a `-fPIC' (for GCC) or `-KPIC' (for SVR4-style compilers) to the platform configuration line in SSLeay's `Configure' script. NOTE: The --disable-rule=SSL_COMPAT option disables the building of SSL compatibility code for older mod_ssl versions and other Apache SSL solutions like Apache-SSL, Sioux, Stronghold, etc. NOTE: The --enable-rule=SSL_SDBM option enabled the use of the built-in SDBM library instead of a custom defined or vendor supplied DBM library. This can be useful when the vendor DBM library is buggy or restricts the data size too dramatically (for SSL sessions to be cacheable the DBM library should allow more than 1KB of data to be stored under a particular key). NOTE: You either use `--with-crt'/`--with-key' or `make certificate' above - but never both. The `--with-crt'/`--with-key' options is used only when you already have a real server certificate and private key at hand while `make certificate' is to create a test server test certificate. Read the message box which occurs after the `make' command when building Apache for details. 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, mod_php, mod_frontpage, mod_dav, etc. But you have to provide the SSL_BASE and RSA_BASE variables manually and either copy your existing certificate manually to conf/ssl.crt/server.crt or use `make certificate': $ cd mod_ssl-2.2.x-1.3.x ALL $ ./configure \ ALL --with-apache=../apache_1.3.x \ ALL --with-crt=/path/to/your/server.crt \ OPTIONAL --with-key=/path/to/your/server.key 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/local \ US ./configure \ ALL --enable-module=ssl \ ALL --prefix=/path/to/apache \ ALL [--enable-shared=ssl] \ OPTIONAL [--disable-rule=SSL_COMPAT] \ OPTIONAL [--enable-rule=SSL_SDBM] \ OPTIONAL [...more APACI options...] OPTIONAL $ make ALL $ make certificate OPTIONAL $ make install OPTIONAL NOTE: The optional --enable-shared=ssl option enables the building of mod_ssl as a DSO `libssl.so'. Read the INSTALL and htdocs/manual/dso.html documents in the Apache source tree for more information about DSO support in Apache. I strongly advise ISPs and package maintainers to use the DSO facility for maximum flexibility with mod_ssl. But notice that DSO is not supported by Apache on all platforms. NOTE: The --disable-rule=SSL_COMPAT option disables the building of SSL compatibility code for older mod_ssl versions and other Apache SSL solutions like Apache-SSL, Sioux, Stronghold, etc. NOTE: The --enable-rule=SSL_SDBM option enabled the use of the built-in SDBM library instead of a custom defined or vendor supplied DBM library. This can be useful when the vendor DBM library is buggy or restricts the data size too dramatically (for SSL sessions to be cacheable the DBM library should allow more than 1KB of data to be stored under a particular key). c) The poor mans way known from Apache 1.2 [FOR COMPATIBILITY]: You configure Apache manually by editing the src/Configuration 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 mod_php 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.2.x-1.3.x ALL $ ./configure \ ALL --with-apache=../apache_1.3.x \ ALL --with-crt=/path/to/your/server.crt \ OPTIONAL --with-key=/path/to/your/server.key 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, including your certificate, etc. That's the price for staying with the good old days... 5. Try out Apache without SSL (only HTTP possible): $ /path/to/apache/sbin/apachectl start ALL $ netscape http:/// ALL $ /path/to/apache/sbin/apachectl stop ALL NOTE: Replace the `' with the official name of your host. Do not enter `localhost' here, because this name has to match the Common Name (CN) of the Subject's Distinguished Name (DN) inside your server certificate. 6. Try out Apache with SSL (HTTP and HTTPS possible): $ /path/to/apache/sbin/apachectl startssl ALL $ netscape http:/// ALL $ netscape https:/// ALL $ /path/to/apache/sbin/apachectl stop ALL NOTE: Replace the `' with the official name of your host. Do not enter `localhost' here, because this name has to match the Common Name (CN) of the Subject's Distinguished Name (DN) inside your server certificate. NOTE: When the above tests (steps 6 and 7) fail for some reasons you are _STRONGLY ADVISED_ 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 you're advised to do the following: o Read the mod_ssl documentation very carefully to understand the SSL-part of your Apache configuration: $ netscape http://www.engelschall.com/sw/mod_ssl/docs/2.2/ (official) $ netscape http://localhost/manual/mod/mod_ssl/ (local copy) o Adjust your Apache configuration to your personal requirements: $ vi /path/to/apache/etc/httpd.conf o Subscribe to the sw-mod-ssl support mailing list: $ netscape http://www.engelschall.com/sw/mod_ssl/news/list.html $ echo "subscribe sw-mod-ssl " | mutt -s '' majordomo@engelschall.com NOTE: Replace `' with your official Email address!! 8. Bask in the glow ;-) Upgrading with APXS (EXPERTS ONLY) __________________________________ Once you've built and installed Apache with mod_ssl as a DSO (libssl.so) you can easily upgrade this libssl.so file with a stand-alone built procedure as long as the Extended API (EAPI) didn't change and you've SSLeay installed somewhere. For this you can use the following procedure: $ cd mod_ssl-2.2.x-1.3.x ALL $ ./configure \ ALL --with-apxs[=/path/to/apache/sbin/apxs] \ ALL --with-ssleay=/path/to/ssleay \ ALL --with-rsaref=/path/to/rsaref US $ make ALL $ make install ALL $ make distclean ALL This will build mod_ssl locally inside the pkg.modssl/ directory and then upgrades your existing libssl.so file. This approach is also interesting for package vendors. Because those can create an Apache+EAPI package (with the use of --with-eapi-only) and a APXS-based mod_ssl package (with the use of --with-apxs). Examples ________ As you noticed above there are a lot of possibilities, variants and options for installing mod_ssl. So, in the following we provide some step-by-step examples where you can see how to build mod_ssl with other third-party modules to form your SSL-aware Apache. For simplification we assume some prerequisites for each example. If these don't fit your situation you have to adjust the steps with the help of the above detailed instructions, of course. o Apache + mod_ssl/SSLeay + mod_perl/Perl --------------------------------------- Prerequisites: o Apache should be installed to /path/to/apache o Perl is installed and `perl' is in $PATH o SSLeay is installed under /path/to/ssleay o RSAref is not used in this example Steps: # extract the packages $ gzip -d -c apache_1.3.x.tar.gz | tar xvf - $ gzip -d -c mod_ssl-2.2.x-1.3.x.tar.gz | tar xvf - $ gzip -d -c mod_perl-1.xx.tar.gz | tar xvf - # apply mod_ssl to Apache source tree $ cd mod_ssl-2.2.x-1.3.x $ ./configure \ --with-apache=../apache_1.3.x $ cd .. # apply mod_perl to Apache source tree # and build/install the Perl-side of mod_perl $ cd mod_perl-1.xx $ perl Makefile.PL \ EVERYTHING=1 \ APACHE_SRC=../apache_1.3.x/src \ USE_APACI=1 \ PREP_HTTPD=1 \ DO_HTTPD=1 $ make $ make install $ cd .. # build/install Apache with mod_ssl and mod_perl $ cd apache_1.3.x $ SSL_BASE=/path/to/ssleay ./configure \ --prefix=/path/to/apache \ --enable-module=ssl \ --activate-module=src/modules/perl/libperl.a \ --enable-module=perl $ make $ make certificate $ make install $ cd .. # cleanup after work $ rm -rf mod_perl-1.xx $ rm -rf mod_ssl-2.2.x-1.3.x $ rm -rf apache_1.3.x o Apache + mod_ssl/SSLeay + PHP3/MySQL ------------------------------------ Prerequisites: o Apache should be installed to /path/to/apache o MySQL is installed under /path/to/mysql o SSLeay is installed under /path/to/ssleay o RSAref have not to be used o GNU Make is available as `gmake' in $PATH Steps: # extract the packages $ gzip -d -c apache_1.3.x.tar.gz | tar xvf - $ gzip -d -c mod_ssl-2.2.x-1.3.x.tar.gz | tar xvf - $ gzip -d -c php-3.0.x.tar.gz | tar xvf - # apply mod_ssl to Apache source tree $ cd /mod_ssl-2.2.x-1.3.x $ ./configure \ --with-apache=../apache_1.3.x $ cd .. # pre-configure Apache for PHP3's configure step $ cd apache_1.3.x $ ./configure \ --prefix=/path/to/apache $ cd .. # configure PHP3 and apply it to the Apache source tree $ cd ../php-3.0.x $ CFLAGS='-O2 -I/path/to/ssleay/include' \ ./configure \ --with-apache=../apache_1.3.x \ --with-mysql=/path/to/mysql \ --enable-memory-limit=yes \ --enable-debug=no $ gmake $ gmake install $ cd .. # build/install Apache with mod_ssl and PHP3 $ cd apache_1.3.x $ SSL_BASE=/path/to/ssleay \ ./configure \ --prefix=/path/to/apache \ --enable-module=ssl \ --activate-module=src/modules/php3/libphp3.a \ --enable-module=php3 $ make $ make certificate $ make install $ cd .. # cleanup after work $ rm -rf php-3.0.x $ rm -rf mod_ssl-2.2.x-1.3.x $ rm -rf apache_1.3.x