The Apache SSL HOWTO - Jordi的blog - 优友地带 UUZone

The Apache + SSL HOWTO

Version 1.6.7 (changelog: view source)

Overview


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

This process worked for many people on Windows NT, 98, ME, 2000 andXP; please mail me your suggestions and bug reports. You can eveninstall Apache with SSL in addition to the Microsoft InternetInformation Server if you need to.

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



Apache with mod_ssl seems to be the only free (as in speech, not inbeer) solution for Win32. Please note that Apache on Win32 isconsidered beta quality as it doesn't reach the stability andperformance of Apache on Un*x platforms.



1.: Installing Apache


Get the Win32 version of the Apache web server from one 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 on 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 thebinary mod_jk.so fromhttp://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 renameit mod_jk.so. Click here for more information on configuring Apache andTomcat.




Note: You can skip this step and get a full Apache+SSL distributionfrom modssl.org, as described below. There will be no fancyinstallation program but you won't need to overwrite the stock Apachefiles. This is the better way if you are experienced and don't fearediting 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 on the standard SSL port)


ServerName www.my-server.dom


(if in addition to IIS) DocumentRoot and the corresponding some-dir> to your Inetpub\wwwroot




Install the Apache service (NT only) and start the server. Verifythat everything works before proceeding to the SSL installation becausethis 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 likeApache_X-mod_ssl_Y-openssl_Z-WIN32[-i386].zip. (You can get the 2.0.49version athttp://hunter.campbus.com/Apache_2.0.49-Openssl_0.9.7d-Win32.zip, olderpackages are also available at http://hunter.campbus.com). Download andunzip it to a new directory.



If you need the newest version, you will have to compile ityourself if it is not there. Don't ask me about it; I don't have it, Idon't compile the versions on modssl.org, and I don't have access todevelopment tools on Win32.



Copy the files ssleay32.dll and libeay32.dll from the Apache/modssldistribution 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,one 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. Whenasked for "Common Name (eg, your websites domain name)", give the exactdomain name of your web server (e.g. www.my-server.dom). Thecertificate belongs to this server name and browsers complain if thename doesn't match.



openssl rsa -in privkey.pem -out server.key
This removes the passphrase from the private key. You MUSTunderstand what this means; server.key should be only readable by theapache server and the administrator.
You should delete the .rnd file because it contains the entropyinformation for creating the key and could be used for cryptographicattacks 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 youget a "real" one from a certificate authority. (Which is optional; ifyou know your users, you can tell them to install the certificate intotheir browsers.) Note that this certificate expires after one year, youcan increase -days 365 if you don't want this.



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



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



Tip from Olivier Gambier:
You can't create a certificate with openssl.exe without a configfile (you get an error about distinguished names). Thus if the variableOPENSSL_CONF is not defined (and I didn't find it in your doc, nor Ifound a conf file in the distrib I downloaded), you must add: "-configconfigfile" to the certificate creation command, and create a valid"configfile"

I found the information, among with the error message meaning, from http://www.openssl.org/docs/apps/req.html.



4.: Configuring Apache and mod_ssl


Copy the executable files (*.exe, *.dll, *.so) from the downloadedapache-mod_ssl distribution over your original Apache installationdirectory (remember to stop Apache first and DO NOT overwrite youredited config files etc.!).



Find the LoadModule directives in your httpd.conf file and add thisafter the existing ones, according to the file you have found in thedistribution:



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 on Windows, on Linux, thiswill 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/. ForWindows, you can download fromhttp://www.raibledesigns.com/tomcat/ssl.conf (Right click -> SaveTarget As...). Make sure and change the DocumentRoot and ServerNamevalues on 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 info
SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none

ErrorLog logs/ssl.log
LogLevel info
# You can later change "info" to "warn" if everything is OK

www.my-server.dom:443>
SSLEngine On
SSLCertificateFile conf/ssl/server.crt
SSLCertificateKeyFile conf/ssl/server.key



Don't forget to call apache with -D SSL if the IfDefine directiveis active in the config file! In other words, either start Apache fromthe command line with -D SSL or comment out the IfDefine start/end tagsin ssl.conf.



NOTE: When using SSL with multiple Virtual Hosts, you must use anip-based configuration. This is because SSL requires you to configure aspecific port (443), whereas name-based specifies all ports (*). Youmight the following error if you try to mix name-based virtual hostswith SSL.

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



You might need to use regedit to change the key

HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache\X.Y.Z to thecorrect number if the apache.exe from modssl.org/contrib is not thesame version as the previously installed one. (This seems not to benecessary with recent versions.)



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

If it doesn't work, Apache should write meaningful messages to thescreen and/or into the error.log and SSL.log files in the Apache/logsdirectory.


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 plainApache installed (Step 1). We will ignore your request; we are not theFree Apache Helpdesk and there is enough good documentation onconfiguring Apache; if that is not enough for you, you shouldn't run asecure server anyway. Also, DON'T e-mail without having looked into theerror.log and SSL.log with LogLevel set to Debug.



Debugging connect problems


Problems connecting to the server with a browser can have manyreasons, many of them on the client (proxy, DNS, general IE dumbness).

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

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

bb@www$ openssl s_client -connect www1.tud.at:443

connect: Connection refused
connect:errno=111
# No SSL server on 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=LifecycleManagement/CN=apcenter.apcinteractive.net/Email=[e-mail]
verify error:num=18:self signed certificate
verify return:1
depth=0 /C=at/ST=Wien/L=Wien/O=APC interactive/OU=LifecycleManagement/CN=apcenter.apcinteractive.net/Email=[e-mail]
verify return:1
---
Certificate chain
0 s:/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=[e-mail]
i:/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=[e-mail]
---
Server certificate
---BEGIN CERTIFICATE---
MIIC0TCCAjoCAQAwDQYJKoZIhvcNAQEEBQAwgbAxCzAJBgNVBAYTAmF0MQ0wCwYDV
[...]
9ucXUnk=
---END CERTIFICATE---
subject=/C=at/ST=Wien/L=Wien/O=APC interactive/OU=LifecycleManagement/CN=apcenter.apcinteractive.net/Email=[e-mail]
issuer=/C=at/ST=Wien/L=Wien/O=APC interactive/OU=Lifecycle Management/CN=apcenter.apcinteractive.net/Email=[e-mail]
---
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 No InterWiki reference defined in properties for Wiki called 'Enter'!)
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 on 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 on Win9x/ME)?
You can verify this by copying openssl.exe into a directory of itsown and executing it. If it complains about not being able to find someDLLs, then you haven't copied them into the correct directory.
One user told me that he had this problem even when he dideverything right. He then found the problem: corrupt openssl DLLs. Soif you get this error despite having done everything correctly, try theopenssl DLLs from another version from modssl.org/contrib.



Q: I see the following when starting Apache:

Syntax error on 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 on 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 No InterWiki reference defined inproperties for Wiki called 'Fri Nov 16 15'!) [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, recompilingmod_ssl or Apache with EAPI, recompiled versions etc. We have no ideaand 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 DebianGNU/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 only after having looked into theerror logs with LogLevel debug. You can mail me in English, German andHungarian.
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 on NT)
Contributor: Christoph Zich (Windows 98)
Contributor: Torsten Stanienda (Test with 1.3.12, IfDefine directive)


Contributor: Peter Holm (Listen and Port directives)