Apache Howto SSL

From openSUSE

Quickstart.SSL

How to get your SSL server up and running as fast as possible

You need to have read the Apache Quickstart HOWTO before going on with this one!

Prerequisites

• make sure that apache starts with mod_ssl loaded. The following command adapts /etc/sysconfig/apache2:APACHE_MODULES so it is done:

 a2enmod ssl

• make sure that the SSL configuration is active. The following command enables it (similarly to a2enmod command, it changes APACHE_SERVER_FLAGS):

 a2enflag SSL

The reason why the flag SSL is also needed is because all SSL configuration is enclosed in <IfDefine> statements. This way it can be dormant until the necessary prerequisite are present (keys) and you want to use it at all. In addition, it can be useful to be able to start apache unattended at boot time even if you use encrypted keys that need a passphrase otherwise.

Keys

• for a real SSL setup, I recommend TinyCA (http://tinyca.sm-zone.net/) to create and manage a real SSL setup. It is available on SUSE Linux as package "tinyca2". Also, please refer to the mod_ssl documentation.

• The following steps will create _dummy_ keys in a very simple way:
  • run /usr/bin/gensslcert
  • it will (over)write these files:

                       /etc/apache2/ssl.crt/ca.crt
                       /etc/apache2/ssl.key/server.key
                       /etc/apache2/ssl.crt/server.crt
                       /etc/apache2/ssl.csr/server.csr

• a copy of ca.crt will be installed as /srv/www/htdocs/CA.crt for download.

Create a virtual host (required)

(Note) Note that virtual host must be IP-based, otherwise it wouldn't work (see [1]) {{{2}}}

• copy /etc/apache2/vhosts.d/vhost-ssl.template to /etc/apache2/vhosts.d/vhost-ssl.conf and adapt it al gusto.
• a separate virtual host is needed because a vhost cannot speak both HTTP and HTTPS
• note that the file must end in ".conf" to be read automatically
• restart apache, /etc/init.d/apache2 restart
• to check your vhost setup, use "httpd2 -S -DSSL"

Configuration questions

For all configuration questions, consult the manual: http://localhost/manual (if the apache2-doc package is installed), or http://httpd.apache.org/docs-2.2/ (the online version)

Read the documentation under /usr/share/doc/packages/apache2/ (where you will also find example configuration files).

TROUBLESHOOTING

If all does not work...

• fire up "tail -F /var/log/apache2/*_log &" in a root shell
• reproduce what is not working (starting apache, doing client requests, or whatever), while how it is reflected in the logs
• make use of https://bugzilla.novell.com if you suspect a bug

Common catch

The server logs this,

 [Thu Aug 28 21:07:39 2003] [error] [client 192.168.0.180] Invalid method in request j

while the client shows this:

 SSL error: error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol

Cause: client speaks HTTPS, server speaks HTTP. If that happens to be port 443, it means that the server is listening on the port but not with SSL.

If it was the other way round (client speaks HTTP, server speaks HTTPS), the server would log 400 and the client show an error 400 (HTTP_BAD_REQUEST) page.