Table of Contents for

Apache Cookbook, 2nd Edition

You want to install SSL on your Apache server.

The solutions to this problem fall into several categories, depending on how you installed Apache in the first place (or whether you are willing to rebuild Apache to get SSL).

If you installed a binary distribution of Apache, your best bet is to return to the place from which you acquired that binary distribution and try to find the necessary files for adding SSL to it.

If you built Apache yourself from source, the solution will depend on whether you are running Apache 1.3 or Apache 2.x.

In Apache 1.3, SSL is an add-on module that you must acquire and install from a location different than that from which you obtained Apache. There are two main choices available: mod_ssl (http://www.modssl.org) and Apache-SSL (http://www.apache-ssl.org); the installation procedure will vary somewhat depending on which one of these you choose.

If you are building Apache 2.x from source, the situation is somewhat simpler; just add --enable-ssl to the ./configure arguments when you build Apache to include SSL as one of the built-in modules.

Consult Chapters 1 and 2 for more information on installing third-party modules, particularly if you have installed a binary distribution of Apache rather than building it yourself from the source code.

If you are attempting to install SSL on Apache for Windows, there is a discussion of this in the Compiling on Windows document, which you can find at http://httpd.apache.org/docs/2.0/platform/win_compiling.html for Apache 2.0. Or if you are using Apache 1.3 on Windows and wish to install SSL, you should consult the file INSTALL.Win32, which comes with the SSL distribution, or look at the HowTo at http://tud.at/programm/apache-ssl-win32-howto.php3.

Finally, note that the Apache SSL modules are an interface between Apache and the OpenSSL libraries, which you must install before any of this can work. You can obtain the OpenSSL libraries from http://www.openssl.org. Although you may already have these libraries installed on your server, it is recommended that you obtain the latest version of the libraries to have the most recent security patches and to protect yourself from exploits.

So, why is this so complicated? Well, there are a variety of reasons, most of which revolve around the legality of encryption. For a long time, encryption has been a restricted technology in the United States. Because Apache is primarily based out of the United States, there is a great deal of caution regarding distributing encryption technology with the package. Even though major changes have been made in the laws, permitting SSL to be shipped with Apache 2.0, there are still some gray areas that make it problematic to ship compiled binary distributions of Apache with SSL enabled.

This makes the situation particularly unpleasant on Microsoft Windows, where most people do not have a compiler readily available to them, and so must attempt to acquire binary builds from third parties to enable SSL on their Apache server on Windows. The URL given previously for compiling Apache 2.0 with SSL on Windows assumes that you do have a compiler, and the document telling you how to build Apache 1.3 with SSL takes great pains to encourage you not to use Apache 1.3 on Windows, where it does not have comparable performance to Apache on Unixish operating systems.

You want to install Apache with SSL on Microsoft Windows.

Obtain XAMPP from http://apachefriends.org and install that.

As was mentioned in the previous recipe, it is certainly possible to build Apache with SSL from source on Microsoft Windows. However, to be honest, this is beyond the expertise of most of us.

Fortunately, the kind folks at ApacheFriends have made available a binary distribution called XAMPP, which includes, among other things, Apache with mod_ssl. The package also includes MySQL, PHP, and Perl, some of the commonly used tools in Web site development.

So, save yourself some pain, take advantage of the great work that has been done by the ApacheFriends guys, and install the XAMPP package.

You want to generate a self-signed certificate to use on your SSL server.

Use the openssl command-line program that comes with OpenSSL:

          % 
          openssl genrsa -out server.key 1024
          % 
          openssl req -new -key server.key -out server.csr
          % 
          cp server.key server.key.org
          %
           openssl rsa -in server.key.org -out server.key
          %
           openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Then move these files to your Apache server’s configuration directory, such as /www/conf/, and then add the following lines in your httpd.conf configuration file:

SSLCertificateFile "/www/conf/server.crt"
SSLCertificateKeyFile "/www/conf/server.key"

The SSL certificate is a central part of the SSL conversation and is required before you can run a secure server. Thus, generating the certificate is a necessary first step to configuring your secure server.

Generating the key is a multistep process, but it is fairly simple.

Generating RSA private key, 1024 bit long modulus
.........................................................++++++
........++++++
e is 65537 (0x10001)

Country Name (2 letter code) [GB]: EX
State or Province Name (full name) [Berkshire]: CO
Locality Name (eg, city) [Newbury]: Example City
Organization Name (eg, company) [My Company Ltd]: Institute of Examples
Organizational Unit Name (eg, section) []: Demonstration Services
Common Name (eg, your name or your server's hostname) []: www.example.com
Email Address []: big-cheese@example.com
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Signature ok
subject=/C=US/ST=KY/L=Wilmore/O=Asbury College/OU=Information
Services/CN=www.asbury.edu/Email=rbowen@asbury.edu
Getting Private key

You want to generate SSL keys that browsers will accept without a warning message.

Issue the following commands:

% CA.pl -newca
% CA.pl -newreq
% CA.pl -signreq
%CA.pl -pkcs12

Recipe 7.2 discusses the lengthy steps that are required to create keys and sign them. Fortunately, OpenSSL comes with a script to automate much of this process so that you don’t have to remember all of those arguments. This script, called CA.pl, is located where your SSL libraries are installed, for example, /usr/share/ssl/misc/CA.pl.

The lines in the Solution hide a certain amount of detail, as you will be asked a number of questions in the process of creating the key and the certificate. Note also that you will probably need to be in the directory where this script lives to get successful results from this recipe.

If you want to omit the passphrase on the certificate so that you don’t have to provide the passphrase each time you start up the server, use -newreq-nodes rather than -newreq when generating the certificate request.

After running this sequence of commands, you can generate more certificates by repeating the -newreq and -signreq commands.

Having run these commands, you will have generated a number of files. The file newcert.pem is the file you specify in your SSLCertificateFile directive, the file newreq.pem is your SSLCertificateKeyFile, and the file demoCA/cacert.pem is the CA certificate file, which will need to be imported into your users’ browsers (for some browsers) so that they can automatically trust certificates signed by this CA. And, finally, newcert.p12 serves the same purpose as demoCA/cacert.pem for certain other browsers.

openssl X509 -demoCA/cacert.pem -out cacert.crt -outform DER

You want to have a certain portion of your site available via SSL exclusively.

This is done by making changes to your httpd.conf file.

For Apache 1.3, add a line such as the following:

Redirect /secure/https://secure.example.com/secure/

For Apache 2.0:

<Directory /www/secure>
    SSLRequireSSL
</Directory>

Note that the SSLRequireSSL directive does not issue a redirect. It merely forbids non-SSL requests.

Or for any version of Apache you can accomplish this using mod_rewrite:

RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/(.*) https://%{SERVER_NAME}/$1 [R,L]

It is perhaps best to think of your site’s normal pages and its SSL-protected pages as being handled by two separate virtual hosts rather than one. Although they may point to the same content, they run on different ports, are configured differently, and, most important, the browser considers them to be completely separate servers. So you should, too.

Don’t think of enabling SSL for a particular directory; rather, you should think of it as redirecting requests for one server to another.

Note that the Redirect directive preserves path information, which means that if a request is made for /secure/something.html, then the redirect will be to https://secure.example.com/secure/something.html.

Be careful where you put this directive. Make sure that you only put it in the HTTP (non-SSL) virtual host declaration. Putting it in the global section of the config file may cause looping, as the new URL will match the Redirect requirement and get redirected itself.

Finally, note that if you want the entire site to be available only via SSL, you can accomplish this by simply redirecting all URLs, rather than a particular directory:

Redirect / https://secure.example.com/

Again, be sure to put that inside the non-SSL virtual host declaration.

You will see various solutions proposed for this situation using RedirectMatch or various RewriteRule directives. There are special cases in which this is necessary, but in most cases, the simple solution offered here works just fine. In particular, you might be compelled to use this solution when you only have access to your .htaccess file, and not to the main server configuration file.

So, the entire setup might look something like this:

NameVirtualHost *

<VirtualHost *>
    ServerName regular.example.com
    DocumentRoot /www/docs

    Redirect /secure/ https://secure.example.com/secure/
</VirtualHost>

<VirtualHost _default_:443>
    SSLEngine On
    SSLCertificateFile /www/conf/ssl/ssl.crt
    SSLCertificateKeyFile /www/conf/ssl/ssl.key

    ServerName secure.example.com
    DocumentRoot /www/docs
</VirtualHost>

The other two solutions are perhaps more straightforward, although they each have a small additional requirement for use.

The second recipe listed, using SSLRequireSSL, will work only if you are using Apache 2.0. It is a directive added specifically to address this need. Placing the SSLRequireSSL directive in a particular <Directory> section will ensure that non-SSL accesses to that directory are not permitted. It does not redirect users to the SSL host; it merely forbids non-SSL access.

The third recipe, using RewriteCond and RewriteRule directives, requires that you have mod_rewrite installed and enabled. Using the RewriteCond directive to check if the client is already using SSL, the RewriteRule is invoked only if they are not. In that case, the request is redirected to a request for the same content but using HTTPS instead of HTTP.

You want to use client certificates to authenticate access to your site.

Add the following mod_ssl directives to your httpd.conf file:

SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile conf/ssl.crt/ca.crt

If you happen to be lucky enough to have a small, closed user community, such as an intranet, or a Web site for a group of friends or family, it is possible to distribute client certificates so that each user can identify himself.

Create client certificates, signing them with your CA certificate file, and then specify the location of this CA certificate file using the SSLCACertificateFile directive, as shown above.

Client certificates are created in the same manner as server certificates, except that the CN (Common Name) on the certificate is the name of the client certificate owner.

You want to run several SSL hosts on a single IP address.

There are several possible answers to this problem, depending on your perspective.

The officially correct answer is that you can only run one SSL host per IP address and port. This has to do with the way that SSL works, and is not a limitation specifically of Apache. Attempting to run multiple SSL hosts on the same IP address and port will result in warning messages being displayed by the browser, because it will be receiving the wrong certificate.

One other possible answer is to use a wildcard certificate. This is covered in the next recipe.

Finally, if you don’t care about the warning messages, you can set up name-based virtual hosts in the usual way, and simply have Apache use the same certificate for all of them.

In the near future, there will be other solutions to this problem, and there are a considerable number of very smart people working on this problem. Unfortunately, it’s still not quite solved.

When an https (SSL) request is made by a browser, the first thing that happens is that the certificate is sent to the browser in order for the SSL encryption to be set up. This happens before the browser has told the server what URL it is requesting, so it is impossible to select a particular virtual host. Thus, it is not possible to associate more than one certificate with a particular IP address and port.

There are basically three types of solutions. Either you ignore the problem, you find a way to use one certificate on multiple hostnames, or you use more IP addresses or ports. We’ll discuss each of these in turn.

https://www.example.com:8443/

You want to use a single certificate for multiple hostnames in the same domain.

Use a wildcard certificate, which works for any name within a particular domain, such as “*.example.com.”

Using the technique described in Recipe 7.2, create a certificate with a Common Name of *.example.com, where example.com is the domain for which you wish to use the certificate. This certificate will now work for any hostname in the example.com domain, such as www.example.com or secure.example.com.

On many browsers, however, the certificate will not work for example.com or for one.two.example.com, but only for hostnames strictly of the form hostname.example.com.

Most certificate authorities will charge considerably more to sign wildcard certificates. This is not because it is somehow more complicated to sign these certificates, but because it is a simple business decision, based on the fact that buying a wildcard certificate means that you don’t need to buy multiple single-host certificates.