_ _ _ __ ___ ___ __| | ___ ___| | mod_ssl | '_ ` _ \ / _ \ / _` | / __/ __| | Apache Interface to OpenSSL | | | | | | (_) | (_| | \__ \__ \ | www.modssl.org |_| |_| |_|\___/ \__,_|___|___/___/_| ftp.modssl.org |_____| _____________________________________________________________________________ ``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 the following packages: o Package: Apache Version: 1.3.x Description: The Apache Group HTTP Server Reason: The webserver base package on which all is based 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 Type: MANDATORY o Package: mod_ssl Version: 2.6.x Description: The Apache Interface to OpenSSL Reason: The interface module for Apache Homepage: http://www.modssl.org/ Distribution: ftp://ftp.modssl.org/source/ Tarball: mod_ssl-2.6.x-1.3.x.tar.gz Location: Zurich, Switzerland, Europe Author(s): Ralf S. Engelschall Type: MANDATORY o Package: OpenSSL Version: 0.9.x Description: The Open Source Toolkit for SSL/TLS Reason: The library which implements SSL/TLS Homepage: http://www.openssl.org/ Distribution: ftp://ftp.openssl.org/source/ Tarball: openssl-0.9.x.tar.gz Location: Zurich, Switzerland, Europe Author(s): The OpenSSL Project Type: MANDATORY o Package: RSAref Version: 2.0 Description: RSA Reference Implementation Reason: Deprecated RSA library for US citizens Homepage: - Distribution: Search on http://ftpsearch.lycos.com/ for "rsaref20.tar.Z" !! Tarball: rsaref20.tar.Z Location: Netherlands (because no longer distributed by RSA DSI) Author(s): RSA DSI Type: OPTIONAL (only mandatory for US-citizens) o Package: MM Version: 1.1.x Description: Shared Memory Library Reason: The portable library for shared memory in Apache/EAPI Homepage: http://www.engelschall.com/sw/mm/ Distribution: http://www.engelschall.com/sw/mm/ Tarball: mm-1.1.x.tar.gz Location: Zurich, Switzerland, Europe Author(s): Ralf S. Engelschall Type: OPTIONAL o Package: GZip Version: 1.2.4 Description: The compression utility Reason: To unpack the above tarballs 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) Type: MANDATORY o Package: Perl Version: 5.004 or 5.005 Description: The Practical Extraction and Reporting Language Reason: To configure OpenSSL and for APXS tool in Apache Homepage: http://www.perl.com/ Distribution: http://www.perl.com/CPAN/src/ Tarball: perl5.00x.tar.gz Location: USA Author(s): Larry Wall Type: MANDATORY 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: (the syntax is for a Bourne-Shell style shell, when you're using a C-Shell style shell you've to adjust the commands according to your shell's manual) 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 OpenSSL. When you've these packages still not installed, do this first. 2. Extract the required packages: $ gzip -d -c apache_1.3.x.tar.gz | tar xvf - ALL $ gzip -d -c mod_ssl-2.6.x-1.3.x.tar.gz | tar xvf - ALL $ gzip -d -c openssl-0.9.x.tar.gz | tar xvf - ALL $ gzip -d -c mm-1.1.x.tar.gz | tar xvf - OPTIONAL $ mkdir rsaref-2.0 US $ (cd rsaref-2.0; gzip -d -c ../rsaref20.tar.Z | tar xvf -) US 3. Configure and build the OpenSSL library: (When you're an US-citizen you have to build OpenSSL 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 and nasty restrictions. 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. Additionally with RSAref not all RSA functionality in OpenSSL will be available. It'll still work for the requirements of mod_ssl, but for instance the RSA OEAP functionality isn't supported by RSAref. $ cd openssl-0.9.x ALL $ sh config \ ALL no-idea \ EU -L`pwd`/../rsaref-2.0/local/rsaref \ US -fPIC OPTIONAL $ make ALL $ make test OPTIONAL $ cd .. ALL NOTE: OpenSSL understands a lot more options on the `config' command line. For instance you can add some command line options (like `-DSSL_FORBID_ENULL' for not allowing Null encryptions, or adding `-DSSL_ALLOW_ADH' for allowing Anonymous Diffie-Hellman ciphers, etc) to adjust the OpenSSL internals (see OpenSSL's top-level Makefile for details). NOTE: When your system already has OpenSSL installed (for instance some Linux distributions ship with OpenSSL installed out-of-the-box) in system locations you can ignore the OpenSSL steps above, too. Then use `SSL_BASE=SYSTEM' instead of `SSL_BASE=../openssl-0.9.x' below and mod_ssl will search for OpenSSL's binary, header and library files in $PATH and system locations. 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/' below. NOTE: The -fPIC option builds OpenSSL with Position Independent Code (PIC) which is only important when building mod_ssl as a Dynamic Shared Object (DSO). Please notice, that you really have to use -fPIC and not -fpic, as the latter will usually cause the build to fail. See below for more details. 4. Optionally you now can build the MM Shared Memory library when you want shared memory support in Apache/EAPI. For instance this allows mod_ssl to use a high-performance RAM-based session cache instead of a disk-based one. $ cd mm-1.1.x OPTIONAL $ ./configure --disable-shared OPTIONAL $ make OPTIONAL $ cd .. OPTIONAL NOTE: When your system already has MM installed in system locations you can ignore the steps above and then use `EAPI_MM=SYSTEM' instead of `EAPI_MM=../mm-1.1.x' below. NOTE: Do not forget the --disable-shared option above. Else you've to establish an explicit LD_LIBRARY_PATH which includes the /path/to/mm-1.1.x/.libs/ directory or the compilation of Apache will fail because the shared library cannot be found. 5. 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 OpenSSL. 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.6.x-1.3.x ALL $ ./configure \ ALL --with-apache=../apache_1.3.x \ ALL --with-ssl=../openssl-0.9.x \ ALL --with-rsa=../rsaref-2.0/local \ US --with-mm=../mm-1.1.x \ OPTIONAL --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 [--enable-rule=SSL_EXPERIMENTAL] \ OPTIONAL [--enable-rule=SSL_VENDOR] \ OPTIONAL [...more APACI options...] OPTIONAL $ cd .. ALL $ cd apache_1.3.x ALL $ make ALL $ make certificate OPTIONAL $ make install ALL $ cd .. ALL 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. We 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 OpenSSL has problems under DSO situations on some platforms. For instance under smart ix86 platforms like Linux and FreeBSD when you compile a the standard OpenSSL 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 OpenSSL's code will dump core under run-time. When this is the case for you, then try to recompile OpenSSL with Position Independent Code (PIC) by adding a `-fPIC' (for GCC) or `-KPIC' (for SVR4-style compilers) to the platform configuration line in OpenSSL's `Configure' script. The -fPIC option above when you build OpenSSL. 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: The --enable-rule=SSL_EXPERIMENTAL and --enable-rule=SSL_VENDOR options enable various experimental and vendor extension code. Please read the src/Configuration.tmpl file inside the Apache source tree for more details. 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, RSA_BASE and EAPI_MM variables manually and either copy your existing certificate manually to conf/ssl.crt/server.crt or use `make certificate': $ cd mod_ssl-2.6.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=../openssl-0.9.x \ ALL RSA_BASE=../rsaref-2.0/local \ US EAPI_MM=../mm-1.1.x \ OPTIONAL ./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 [--enable-rule=SSL_EXPERIMENTAL] \ OPTIONAL [--enable-rule=SSL_VENDOR] \ OPTIONAL [...more APACI options...] OPTIONAL $ make ALL $ make certificate OPTIONAL $ make install OPTIONAL $ cd .. ALL 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. We 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 OpenSSL has problems under DSO situations on some platforms. For instance under smart ix86 platforms like Linux and FreeBSD when you compile a the standard OpenSSL 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 OpenSSL's code will dump core under run-time. When this is the case for you, then try to recompile OpenSSL with Position Independent Code (PIC) by adding a `-fPIC' (for GCC) or `-KPIC' (for SVR4-style compilers) to the platform configuration line in OpenSSL's `Configure' script. The -fPIC option above when you build OpenSSL. 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: The --enable-rule=SSL_EXPERIMENTAL and --enable-rule=SSL_VENDOR options enable various experimental and vendor extension code. Please read the src/Configuration.tmpl file inside the Apache source tree for more details. 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, RSA_BASE and EAPI_MM variables manually and more important: you have to install the Apache package manually, too. But feel free to be masochistic ;-) $ cd mod_ssl-2.6.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 EAPI_MM 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, yeah? 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... 6. Try out Apache without SSL (only HTTP protocol possible): $ /path/to/apache/bin/apachectl start ALL $ netscape http:/// ALL $ /path/to/apache/bin/apachectl stop ALL 7. Try out Apache with SSL (both HTTP and HTTPS protocol possible): $ /path/to/apache/bin/apachectl startssl ALL $ netscape http:/// ALL $ netscape https:/// ALL $ /path/to/apache/bin/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: If you have built and installed under root (uid 0), leave out the the `' and `' strings above. If you have built and installed under a different user than root, replace `' with `:8080' and `' with `:8443' above. The reason just is that Apache pre-configures the installed configuration file for direct use (at least as long the APACI option --without-confadjust is not used). For using the official ports (80 for HTTP and 443 for HTTPS) root priviledges are required under run-time, so APACI assumes that it has to use alternate ports (8080 for HTTP and 8443 for HTTPS) if the built and installation is done under non-root users. 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. NOTE: When you *re*install Apache many times, make sure you restart your browsers between the tests if you created test or custom certificates. Else connections might fail because the browser cached the certificate details of the previous installation. 8. Finally you're advised to do the following: o Read the mod_ssl user manual very carefully to understand the SSL-part of your Apache configuration: $ netscape http://www.modssl.org/docs/2.6/ (official) $ netscape http://localhost/manual/mod/mod_ssl/ (local copy) o Adjust your Apache configuration to your personal requirements. The configuration is already pre-configured for SSL, but usually it has to be tweaked a little bit more to fit the local situation. When you had already a httpd.conf file, this one is preserved. Then look inside /path/to/apache/etc/httpd.conf.default for the pre-configured SSL configuration and take it over manually into httpd.conf. $ vi /path/to/apache/etc/httpd.conf o Subscribe to the modssl-users@modssl.org support mailing list with the provided web interface: $ netscape http://www.modssl.org/news/list.html 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 OpenSSL installed somewhere. For this you can use the following procedure: $ cd mod_ssl-2.6.x-1.3.x ALL $ ./configure \ ALL --with-apxs[=/path/to/apache/bin/apxs] \ ALL --with-ssl=/path/to/openssl \ ALL --with-rsa=/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/OpenSSL + mod_perl/Perl --------------------------------------- Prerequisites: o Apache should be installed to /path/to/apache o Perl is installed and `perl' is in $PATH o OpenSSL is installed under /path/to/openssl 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.6.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.6.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/openssl ./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.6.x-1.3.x $ rm -rf apache_1.3.x o Apache + mod_ssl/OpenSSL + PHP3/MySQL ------------------------------------- Prerequisites: o Apache should be installed to /path/to/apache o MySQL is installed under /path/to/mysql o OpenSSL is installed under /path/to/openssl 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.6.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.6.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/openssl/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/openssl \ ./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.6.x-1.3.x $ rm -rf apache_1.3.x