The Apache + SSL HOWTO

Version 1.6.6 (changelog: view source)

Spanish translation maintained by Sergio Artigas

French translation maintained by Jean-Francois Moreau

Revised September 26, 2002 by Matt Raible for Apache 2.0.42. Original Article at http://tud.at/programm/apache-ssl-win32-howto.php3.

User Submitted Errata

2002-11-26, Daniel Nixon, re: use http when for SSL ports

Q: SSL doesn't work in the browser and I see the following in some
logfile: 
[Fri Nov 16 15:46:30 2001] [error] OpenSSL: 
    error:1407609C:SSL routines:SSL23_GET_CLIENT_HELLO:http request 
    [Hint: speaking HTTP to HTTPS port!?]

I found that this also occurred when using http as the protocol in the url, 
rather than https. i.e. Trying to access http://mysite:443/ returned a Bad 
Request error in the browser (and the error above in the error.log), which 
was resolved by using https://mysite/.

2002-10-21, Chris Parker, re: open ssl and cygwin

FWIW - I am using Windows NT 4.0 SP6a.  I have Apache 2.043, and the latest 
version of Cygwin as of October 16 - they don't use version numbers any longer.  

1:
 RE: "You'll need a config file for openssl.exe. If you are using Cygwin, o­ne 
 will already exist for you." I did _not_ have a "openssl.cnf" file in Cygwin,  
 nor was it included with the OpenSSL binaries.  I downloaded an example file 
 from the Internet at http://tinyurl.com/3fw3 (the third hit at GOOGLE when I searched for "openssl.cnf").


2:
 When I typed "openssl req -new -out server.csr" - first I saw "Using 
 configuration from /usr/local/ssl/openssl.cnf", then I received the error 
 message "Unable to load config info" even though openssl.cnf was plainly in 
 /usr/local/ssl/ (okay, it was actually C:\Cygwin\usr\local\ssl\).  To resolve 
 this issue, I simply made a copy of openssl.cnf in the same directory as 
 openssl.exe, then from the Cygwin console I typed 
 'export OPENSSL_CONF="./openssl.cnf"'.  
 All openssl commands worked normally after that.  I saw a bit of discussion 
 regarding this issue while searching old discussion threads, it must be a 
 recurring problem in Cygwin.

3:
 The x.509 certificate creation command says "openssl x509 -in server.csr -out 
 server.crt -req -signkey server.key -days 365" (note: server.CRT), while the 
 virtual host entry says "SSLCertificateFile conf/ssl/server.cert" (note: 
 server.CERT) - both file extensions need to be the same.

4:
 Q: SSL doesn't work in the browser and I see the following in some logfile:  A: How much clearer can an error message get? Your VirtualHost or Listen 
 configuration is wrong.

or, the server's web page or applet could use a relative URL - i.e. 
"/path/webpage.jsp" rather than "https://server/path/webpage.jsp" AND the 
redirect is handled by some dynamic page generation engine.  At least in my 
instance, having the controller servlet forward to "/path/webpage.jsp" caused 
above listed error - I have to use fully qualified URLs...

Overview

This page describes the installation of the Win32 version of Apache with the mod_ssl extension. The newest version should always be available from http://tud.at/programm/apache-ssl-win32-howto.php3.

This process worked for many people o­n Windows NT, 98, ME, 2000 and XP; please mail me your suggestions and bug reports. You can even install Apache with SSL in addition to the Microsoft Internet Information Server if you need to.

Note: sometimes, there are changes between the precompiled apache distributions so that this HOWTO is not correct anymore. In this case, if the current version does not work for you, download an older version – o­ne that was published before the modification date of this HOWTO. Or, if you like adventures, try to make it run, and mail me if you needed to change anything.

Apache with mod_ssl seems to be the o­nly free (as in speech, not in beer) solution for Win32. Please note that Apache o­n Win32 is considered beta quality as it doesn’t reach the stability and performance of Apache o­n Un*x platforms.

1.: Installing Apache

Get the Win32 version of the Apache web server from o­ne of the mirrors. It is called something like apache_x_y_z_win32.exe. This is a self-extracting archive that contains the Apache base system and sample configuration files.

Don’t mix Apache versions 1.3 and 2! It won’t work. If you find 1.3.x o­n modssl.org, you cannot expect it to work with 2.0.x.

Install Apache as described in http://www.apache.org/docs/windows.html.

For Linux, to install Apache 2.0.42 with mod_sll installed, I performed the following steps:I used http://httpd.apache.org/docs-2.0/install.html as a reference.

$ lynx http://www.apache.org/dist/httpd/httpd-2.0.42.tar.gz
$ gzip -d httpd-2.0.42.tar.gz
$ tar xvf httpd-2.0.42.tar
$ ./configure --enable-mods-shared=most --enable-ssl=shared
$ make
$ make install

If you’re using Apache 2.0.42 with Tomcat, you can download the binary mod_jk.so from http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/linux/i386/mod_jk-2.0.42.so. After downloading, put this file into your modules directory
and rename it mod_jk.so. Click here for more information o­n configuring Apache and Tomcat.

Note: You can skip this step and get a full Apache+SSL distribution from modssl.org, as described below. There will be no fancy installation program but you won’t need to overwrite the stock Apache files. This is the better way if you are experienced and don’t fear editing configuration files (which you will need to do anyway).

Change at least the following parameters in Apache-dir/conf/httpd.conf:
[Replace all occurences of www.my-server.dom with the real domain name!]

  • Port 80 to # Port 80 (Comment it out; Port is not necessary, Listen overrides it later.)
  • (if not in addition to IIS) Listen 80
  • Listen 443 (So your server listens o­n the standard SSL port)
  • ServerName www.my-server.dom
  • (if in addition to IIS) DocumentRoot and the corresponding < FONT>some-dir> to your Inetpub\wwwroot

Install the Apache service (NT o­nly) and start the server. Verify that everything works before proceeding to the SSL installation because this limits the possible errors.

Try http://www.my-server.dom:443/. It won’t be encrypted yet but if this works then the port configuration (port 443) is right.

2.: Getting OpenSSL and mod_ssl

Go to http://www.modssl.org/contrib/ and find a file called like Apache_X-mod_ssl_Y-openssl_Z-WIN32[-i386].zip. (You can get the 2.0.42 version at http://hunter.campbus.com/, older packages are also available at http://hunter.campbus.com). Download and unzip it to a new directory.

If you need the newest version, you will have to compile it yourself if it is not there. Don’t ask me about it; I don’t have it, I don’t compile the versions o­n modssl.org, and I don’t have access to development tools o­n Win32.

Copy the files ssleay32.dll and libeay32.dll from the Apache/modssl distribution directory to WINNT\System32. This is important! About 70 % of the e-mails I receive is because people forget to do this.

Download and install Cygwin from http://www.cygwin.com.

You’ll need a config file for openssl.exe. If you are using Cygwin, o­ne will already exist for you. If you don’t want to install Cygwin, there is an openssl.exe application in the OpenSSL distribution.

3.: Creating a test certificate

The following instructions are from http://www.apache-ssl.org/#FAQ.

openssl req -new -out server.csr
This creates a certificate signing request and a private key. When asked for "Common Name (eg, your websites domain name)", give the exact domain name of your web server (e.g. www.my-server.dom). The certificate belongs to this server name and browsers complain if the name doesn’t match.

openssl rsa -in privkey.pem -out server.key
This removes the passphrase from the private key. You MUST understand what this means; server.key should be o­nly readable by the apache server and the administrator.
You should delete the .rnd file because it contains the entropy information for creating the key and could be used for cryptographic attacks against your private key.

openssl x509 -in server.csr -out server.crt -req -signkey server.key -days 365
This creates a self-signed certificate that you can use until you get a “real” o­ne from a certificate authority. (Which is optional; if you know your users, you can tell them to install the certificate into their browsers.) Note that this certificate expires after o­ne year, you can increase -days 365 if you don’t want this.

If you have users with MS Internet Explorer 4.0+ and want them to be able to install the certificate into their certificate storage (by downloading and opening it), you need to create a DER-encoded version of the certificate:
openssl x509 -in server.crt -out server.der.crt -outform DER

Create an Apache/conf/ssl directory and move server.key and server.crt into it. For Linux create two directories: ssl.key and ssl.crt. Move server.crt into ssl.crt and move server.key into ssl.key.

4.: Configuring Apache and mod_ssl

Copy the executable files (*.exe, *.dll, *.so) from the downloaded apache-mod_ssl distribution over your original Apache installation directory (remember to stop Apache first and DO NOT overwrite your edited config files etc.!).

Find the LoadModule directives in your httpd.conf file and add this after the existing o­nes, according to the file you have found in the distribution:

LoadModule ssl_module modules/ApacheModuleSSL.dll
or
LoadModule ssl_module modules/ApacheModuleSSL.so
or
LoadModule ssl_module modules/mod_ssl.so
in newer versions. (Use this for 2.0.42 o­n Windows, o­n Linux, this will be done for you when you compile with --enable-ssh=shared)

In newer versions of the distribution, it could also be necessary to add
AddModule mod_ssl.c
after the AddModule lines that are already in the config file. (Not necessary for 2.0.42)

Copy ssl.conf from the OpenSSL distrution to Apache/conf/. For Windows, you can download from http://www.raibledesigns.com/tomcat/ssl.conf
(Right click -> Save Target As…). Make sure and change the DocumentRoot and ServerName values o­n lines 93 and 94.

Add the following to the end of httpd.conf:

# see http://www.modssl.org/docs/2.4/ssl_reference.html for more infoSSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none

ErrorLog logs/ssl.log
LogLevel info# You can later change "info" to "warn" if everything is OKwww.my-server.dom:443>
SSLEngine o­n
SSLCertificateFile conf/ssl/server.cert
SSLCertificateKeyFile conf/ssl/server.key

Don’t forget to call apache with -D SSL if the IfDefine directive is active in the config file! In other words, either start Apache from the command line with -D SSL or comment out the IfDefine start/end tags in ssl.conf.

NOTE: When using SSL with multiple Virtual Hosts, you must use an ip-based configuration. This is because SSL requires you to configure a specific port (443), whereas name-based specifies all ports (*). You might the following error if you try to mix name-based virtual hosts with SSL.

[error] VirtualHost _default_:443 -- mixing * ports and non-* ports with a NameVirtualHost address is not supported, proceeding with undefined results

You might need to use regedit to change the key HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache\X.Y.Z to the correct number if the apache.exe from modssl.org/contrib is not the same version as the previously installed o­ne. (This seems not to be necessary with recent versions.)

Start the server, this time from the command prompt (not as a service) in order to see the error messages that prevent Apache from starting. If everything is OK, (optionally) press CTRL+C to stop the server and start it as a service if you prefer.

If it doesn’t work, Apache should write meaningful messages to the screen and/or into the error.log and SSL.log files in the Apache/logs directory.
If something doesn’t work, set all LogLevels to the maximum and look into the logfiles. They are very helpful.

DON’T e-mail me or the other contributors without having plain Apache installed (Step 1). We will ignore your request; we are not the Free Apache Helpdesk and there is enough good documentation o­n configuring Apache; if that is not enough for you, you shouldn’t run a secure server anyway. Also, DON’T e-mail without having looked into the error.log and SSL.log with LogLevel set to Debug.

Debugging connect problems

Problems connecting to the server with a browser can have many reasons, many of them o­n the client (proxy, DNS, general IE dumbness).

So, if you encounter problems connecting with SSL, try another browser and/or look into the settings. If even this doesn’t work, you can use OpenSSL to debug the problem.

bb@www$ openssl s_client -connect no-such-machine:443gethostbyname failure      # Error resolving this DNS name. Connect with the IP address.connect:errno=2

bb@www$ openssl s_client -connect www1.tud.at:443connect: Connection refused          
connect:errno=111# No SSL server o­n this port. Double-check the Listen and Port directives.bb@www$ openssl s_client -connect apcenter.apcinteractive.net:443# everything OK. OpenSSL shows the information it obtained from the server.CONNECTED(00000003)
depth=0 /C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
verify return:1
---
Certificate chain
 0 s:/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
   i:/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIC0TCCAjoCAQAwDQYJKoZIhvcNAQEEBQAwgbAxCzAJBgNVBAYTAmF0MQ0wCwYDV
[...]
9ucXUnk=
-----END CERTIFICATE-----
subject=/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
issuer=/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=bb@apcinteractive.net
---
No client certificate CA names sent
---
SSL handshake has read 1281 bytes and written 320 bytes
---
New, TLSv1/SSLv3, Cipher is EDH-RSA-DES-CBC3-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : EDH-RSA-DES-CBC3-SHA
    Session-ID: 49ACE1CF484A67D2C476B923D52110A6FCA1A7CE53D76DF7F233DEBF2333D4FB
    Session-ID-ctx:
    Master-Key: 00E9FA964253752294ECD69C18ADBA527B7170C112E2B3BCB25EA8F4FD847EC46E1FF0194EF8E16985B5E38BF6F12131
    Key-Arg   : None
    Start Time: 980696025
    Timeout   : 300 (sec)
    Verify return code: 0 (ok)
---[Enter: 
GET / HTTP/1.0
and press RETURN twice]HTTP/1.1 200 OK
Date: Sun, 28 Jan 2001 15:34:58 GMT
Server: Apache/1.3.9 (Win32) mod_ssl/2.4.9 OpenSSL/0.9.4
Cache-Control: no-cache, no-store, must-revalidate, private
Expires: 0
Pragma: no-cache
X-Powered-By: PHP/4.0.4
Last-Modified: Sun, 28 Jan 2001 15:35:00 GMT
Connection: close
Content-Type: text/html# the server shows its main document

Common problems

Q: I see the following when starting Apache:

Syntax error o­n line [some number] of ...httpd.conf
Cannot load apache/modules/mod_ssl.so into server 
(126) The module could not be found:


A: Did you copy the openssl DLLs to WINNT/SYSTEM32 (or WINDOWS/SYSTEM o­n Win9x/ME)?
You can verify this by copying openssl.exe into a directory of its own and executing it. If it complains about not being able to find some DLLs, then you haven’t copied them into the correct directory.
One user told me that he had this problem even when he did everything right. He then found the problem: corrupt openssl DLLs. So if you get this error despite having done everything correctly, try the openssl DLLs from another version from modssl.org/contrib.
Q: I see the following when starting Apache:

Syntax error o­n line [some number] of apache/conf/httpd.conf:
Cannot load apache/modules/apachemodulessl.dll into server:
(127) The specified procedure could not be found:

or:

Syntax error o­n line [some number] of apache/conf/httpd.conf:
Invalid command 'SSLMutex', perhaps mis-spelled or defined by a module not
included in the server configuration


A: You didn’t add the AddModule line (or not where it belongs, it belongs below the other AddModule lines).
Q: SSL doesn’t work in the browser and I see the following in some logfile:

[Fri Nov 16 15:46:30 2001] [error] OpenSSL: error:1407609C:SSL
routines:SSL23_GET_CLIENT_HELLO:http request [Hint: speaking HTTP to
HTTPS port!?]

A: How much clearer can an error message get? Your VirtualHost or Listen configuration is wrong.

Questions about Java servlets, OpenSSL compilation etc.

Don’t ask us about installing servlet extensions, recompiling mod_ssl or Apache with EAPI, recompiled versions etc. We have no idea and won’t be able help you. We are just users and not programmers.
If your needs are so special, you are better off with a Debian GNU/Linux or OpenBSD server. It will save you lots of trouble. Really.

Links

Apache Web Server: http://www.apache.org
mod_ssl: http://www.modssl.org
mod_ssl configuration: http://www.modssl.org/docs/2.4/ssl_reference.html
OpenSSL: http://www.openssl.org
PHP Hypertext preprocessor: http://www.php.net

Author of this document: Balázs Bárány (http://tud.at)
(mail me your questions, but o­nly after having looked into the error logs with LogLevel debug. You can mail me in English, German and Hungarian.
If I am constantly ignoring your e-mail, read all the hints in the HOWTO about how to e-mail me.)

Contributor: Horst Bräuner (OpenSSL configuration o­n NT)
Contributor: Christoph Zich (Windows 98)
Contributor: Torsten Stanienda (Test with 1.3.12, IfDefine directive)
Contributor: Peter Holm (Listen and Port directives)

Last change: 2002-05-18

This document can be redistributed under the GNU Free Documentation License. © Balázs Bárány 1999-2002

Valid XHTML 1.0! These instructions where tested by Matt Raible o­n Windows XP (SP1) and Red Hat Linux 7.3 with Apache 2.0.42.