mod_ssl: F.A.Q.

mod_ssl |
Compatibility | Glossary
his chapter is a collection of frequently asked questions (FAQ) and corresponding answers following the popular USENET tradition. Most of these questions occured on the Newsgroup `comp.infosystems.www.servers.unix` or the mod_ssl Support Mailing List `sw-mod-ssl@engelschall.com`. They are collected at this place to avoid answering the same questions over and over. |  |
Table Of Contents
About the module About Configuration About Certificates About SSL Protocol
- ## About the module What are the differences between mod_ssl and Apache-SSL, from where it is derived? This cannot be answered in short, because there are too much changes (see the `CHANGES` and `CHANGES.20` files in the mod_ssl distribution for detailed information). Most of them are internal changes, cleanups and re-organizations of the source code. But the user visible changes are mainly the following: mod_ssl provides a complete documentation (this User Manual) where all configuration directives, environment variables, and other things are documented while Apache-SSL had no such documentation although it existed for over three years when mod_ssl was split from it (in April 1998). Additionally mod_ssl provides answers to often occuring frequently asked questions (this list) in the Apache/SSL/SSLeay area. For instance mod_ssl gives detailed hints about how to setup a CA, how to create real a server Certificate, etc. And the mod_ssl User Manual provides a compact introduction to the complex SSL area itself. Because here are the typical hurdles located every user stumbles over. mod_ssl comes with clean and documented source code with the intent that only this way the user is able to re-view it for backdoors, security holes, etc. This is considered important for security-related software. It was always incomprehensible to the author of mod_ssl how Apache-SSL could exist for over three years while both the source code and the source patches were provided in an undocumented and partly unreadable format. For the mod_ssl package the source codes follows the Apache coding style, is logically ordered to follow the API phases and even the patches to the Apache source tree are annotated with descriptions to give the user a chance to re-view and understand them. mod_ssl uses a generic Extended API to achieve its functionality. This means instead of patching in SSL/crypto-related code into the Apache kernel a clean and well separated Extended API is patched in. This way the SSL and cryptography code is only present inside the SSL module itself (i.e. inside the `src/modules/ssl/` subtree only). The benefit from this is a clean separation and API-conforming SSL solution (which means for instance no direct SSL-references from the kernel, no kludges and hacks to get called, etc). mod_ssl supports Dynamic Shared Object (DSO) building as a direct consequence from using the Extended API. In short DSO support means maximum flexibility under run-time, i.e. you don't have to think under compile-time whether to build or not to build SSL into the Apache httpd executable. Instead you can just load mod_ssl through mod_so's `LoadModule` directive on demand. This is especially interesting for two cases: Vendor package maintainers receive the power they need for creating flexible packages and power users receive the ability to run more than one Apache (non-SSL-aware and SSL-aware) instance from a single Apache installation while still saving RAM. mod_ssl is ported to the Win32 platform, as it's the case for Apache and SSLeay. This way mod_ssl follows the evolution of these packages and provides the always requested support also for this nasty platform. As for the Unix/DSO case under Win32 mod_ssl is well-integrated into Apache through a stand-alone DLL which can be loaded through mod_so's `LoadModule` directive. mod_ssl can be really easily applied to the Apache source tree because it provides a full-featured and automated configuration environment for this task while Apache-SSL forced the user to fiddle with the `patch` and `cp` tools theirself. Just because security is not for amateurs hasn't to mean that user friendliness is not important. So it's a must to assist the user in applying the SSL-stuff to vanilla Apache sources. For this mod_ssl integrates also very-well into the new Apache 1.3 Autoconf-style Interface (APACI). Additionally mod_ssl's configuration mechanism supports the usage of RSAref, arbitrary locations for SSLeay, etc. mod_ssl fixes a lot of bugs and inconsistencies which existed in Apache-SSL. For Apache experts here are a few impressions: Apache-SSL wrote directly to `stderr` instead of the Apache error logfile; it messed up it's error messages with the SSLeay error messages; it directly patched the `SERVER_BASEVERSION` define instead of using the Apache 1.3 conforming `ap_add_version_component` function; it used the unsafe `sprintf` function instead of the robust `ap_snprintf`; it incorrectly spawned and killed the `gcache` auxiliary program and it totally failed to pass the ```gcc -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes -Wmissing-declarations -Wnested-externs -Winline`'' test (while Apache already passes it) because of unclean code. Additionally Apache-SSL didn't provide a way to easily apply it to the Apache source tree (semi-manual editing and patching was required); it didn't seamlessly integrate into the new Apache 1.3 Autoconf-style Interface (APACI) at configuration time; it didn't automatically recognize the difference between an installed SSLeay and an out-of-the-source-only SSLeay; it didn't provide integration into the APACI installation process (`make install`); it used numbers 0 to 2 instead of reasonable names for the argument of `SSLVerifyClient` just because internally an `enum` was used and for the provided `%{version}c` construct of CustomLog it used the results "2", "3" under SSLeay 0.8 while under SSLeay 0.9 the results were "SSL2", "SSL3", etc. pp. mod_ssl adds new functionalities which were missing in Apache-SSL. A few selected points which give you an impression follow: mod_ssl provides a real dedicated SSL log file controlled by log level and the additional features that messages logged at the `error' level are automatically duplicated to the general Apache error log file. And occuring system and SSLeay error messages are automatically appended to mod_ssl messages. Additionally mod_ssl annotates deep-level SSLeay messages with more high-level hints. mod_ssl provides a completely new and enhanced handling of encrypted private key files. First the private keys are kept in a permanent memory pool (as SSLeay already does internally), so Apache now survives server restarts without falling down. Second the pass phrase dialog is a lot more user friendly and advanced: It uses a pass phrase reuse-algorithm to minimize the dialog, it recognizes wrong pass phrases and allows retries (but with a backoff time delay), etc. And additionally a minimal interface is provided to plug-in an external program for providing the pass phrase for special batch security situations. mod_ssl provides the `SSLCACertificateReqFile` directive which can be used to configure a different (from `SSLCACertificateFile`) set of CA Certificates for the SSLv3 feature used by the clients to load CA Certificates from the server for speeding up server authentication. mod_ssl replaced the ``gcache'' stuff of Apache-SSL (used for caching SSL sessions) with a more robust DBM-based solution, because the controlling of an external program cannot be done very reliable from within Apache. Additionally a "mutex" is now used to synchronize the inter-process access to this cache. mod_ssl provides support for the SSLeay+RSAref couple, i.e. mod_ssl supports the building with RSAref. mod_ssl provides a new SSLRequire directive which can be used to implement more granular access control based on arbitrary complex boolean expression. mod_ssl adds support for HTTPS to the Apache Proxy Module (mod_proxy). mod_ssl is the first Open Source version of an SSL extension to Apache which supports the Win32 platform. etc.pp. When you're still really interested in more hard-core details walk through the entries in the `CHANGES` and `CHANGES.20` files in the mod_ssl distribution. Ok, does this mean I should avoid using Apache-SSL from now on? No, it just means that you can use mod_ssl. Beside the well-known flaws Apache-SSL works great. Ben Laurie did and still does a great job in maintaining it. The big difference is just that Ben Laurie's goals are different from Ralf S. Engelschall's goals. So, as long as you don't get bothered by inconsistencies and other flaws you don't have to upgrade. Instead you should decide yourself if you already feel comfortable or not. If yes, stay with Apache-SSL - if not, move to mod_ssl or (even better) one of the commercial SSL solutions for Apache. Or in other words: No solution is better than another in general. Which one you should use depends mainly on your personal requirements. On which Apache-SSL version is mod_ssl actually based? The mod_ssl package was initially created by porting the Apache-SSL 1.17 stuff from Apache 1.2.6 to Apache 1.3b6 in April 1998. Because of conflicts with Ben Laurie's development cycle it then was re-assembled from scratch for Apache 1.3.0 by merging the old mod_ssl with the newer Apache-SSL 1.18. From this point mod_ssl lived its own life and changes with Apache-SSL releases were merged after they were released. In other words: mod_ssl is based on the latest Apache-SSL and always will contain all useful changes which will occur with Apache-SSL in the future. Why is mod_ssl's version starting with 2.0.0? Because initially the mod_ssl project was intended as a contribution to the Apache-SSL project from Ben Laurie. The idea was that mod_ssl formed Apache-SSL 2.0.0. But after Ralf S. Engelschall and Ben Laurie couldn't find a reasonable compromise in merging mod_ssl with Apache-SSL, the stuff was released as a new package named ``mod_ssl''. But to still indicate that it's some ``second generation'' stuff, the first mod_ssl version was named 2.0.0. How do I know which mod_ssl version is for which Apache version? That's trivial: mod_ssl uses version strings of the syntax <mod_ssl-version>-<apache-version>, for instance `2.1.0-1.3.3`. This directly indicates that it's mod_ssl version 2.1.0 for Apache version 1.3.3. And this also means you only can apply this mod_ssl version to exactly this Apache version (unless you use the `--force` option to mod_ssl's `configure` command ;-). ## About Configuration I want to run HTTP and HTTPS on the same machine. Is that possible? Yes, there are two ways to do this: run two server instances, or run both services from the same server instance. Unless there is a good reason to run two (like using a different product for HTTP and HTTPS), it's usually most simples to run a single instance where you enable SSL only for those virtual hosts that need it. If you wish to run two server instances you must make sure that they each only try to bind to their allowed ports (normally port 80 for HTTP and 443 for HTTPS). I know that HTTP is on port 80, but where is HTTPS? You can run HTTPS on any port, but the standards specify port 443, which is where any HTTPS compliant browser will look by default. You can force your browser to look on a different port by specifying it in the URL like this (for port 666): `https://secure.server.dom:666/` How can I speak HTTPS manually for testing purposes? While you usually just use `$ telnet localhost 80` `GET / HTTP/1.0` for simple testing the HTTP protocol of Apache, it's not such easy for HTTPS because of the SSL protocol between TCP and HTTP. But with the help of SSLeay's `s_client` program you can do a similar check even for HTTPS: `$ s_client -connect localhost:443 -state -debug` `GET / HTTP/1.0` Before the actual HTTP response you receive detailed information about the SSL handshake. For a more general command line client which directly understands both the HTTP and HTTPS scheme, can perform GET and POST methods, can use a proxy, supports byte ranges, etc. you should have a look at nifty cURL tool. With it you can directly check if your Apache is running fine on Port 80 and 443 as following: `$ curl http://localhost/` `$ curl https://localhost/` Why does my browser hang when I connect to my SSL-aware Apache server? Because you used an URL of the form ```http://`'' instead of ```https:`''. Really! Also, if you see: ```SSL_Accept failed error:140760EB:SSL routines: SSL23_GET_CLIENT_HELLO:unknown protocol`'' in your Apache error logfile, it's for the same reason. This also happens the other way round, i.e. when you try to use ```https://`'' on a server that doesn't support SSL (on this port). Make sure you are connecting to a virtual server that supports SSL, which is probably the IP associated with your hostname, not localhost (127.0.0.1). How can I use relative hyperlinks to switch between HTTP and HTTPS? Usually you have to use fully-qualified hyperlinks because you have to change the URL scheme. But with the help of some URL manipulations through mod_rewrite you can achieve the same effect while you still can use relative URLs:
          RewriteEngine on
          RewriteRule   ^/(.*):SSL$   https://%{SERVER_NAME}/$1 [R,L]
          RewriteRule   ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1  [R,L]
  This rewrite ruleset lets you use hyperlinks of the form
          <a href="document.html:SSL">
- 5. ## About Certificates What are RSA private keys, CSR's and Certificates? The RSA private key file is a digital file that you can use to decrypt messages sent to you. It has a public component which you distribute (via your Certificate file) which allows people to encrypt those messages to you. A Certificate Signing Request (CSR) is a digital file which contains your public key and your name. You send the CSR to a Certifying Authority (CA) to be converted into a real Certificate. A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by your CA. Browsers that know the CA can verify the signature on that Certificate, thereby obtaining your RSA public key. That enables them to send messages which only you can decrypt. See the Introduction chapter for a general description of the SSL protocol. Seems like there is a difference on startup between the original Apache and an SSL-aware Apache? Yes, in general, starting Apache with a built-in mod_ssl is just like starting an unencumbered Apache, except for the fact that when you have a pass phrase on your SSL private key file. Then a startup dialog pops up asking you to enter the pass phrase. To type in the pass phrase manually when starting the server can be problematic, for instance when starting the server from the system boot scripts. As an alternative to this situation you can follow the steps below under ``How can I get rid of the pass-phrase dialog at Apache startup time?''. How can I create a dummy SSL server Certificate for testing purposes? A Certificate does not have to be signed by a public CA. You can use your private key to sign the Certificate which contains your public key. You can install this Certificate into your server, and people using Netscape Navigator (not MSIE) will be able to connect after clicking OK to a warning dialogue. You can get MSIE to work, and your customers can eliminate the dialogue, by installing that Certificate manually into their browsers. Just use the ```make certificate`'' command at the top-level directory of the Apache source tree right before installing Apache via ```make install`''. This creates a self-signed SSL Certificate which expires after 30 days and isn't encrypted (which means you don't need to enter a pass-phrase at Apache startup time). BUT REMEMBER: YOU REALLY HAVE TO CREATE A REAL CERTIFICATE FOR THE LONG RUN! HOW THIS IS DONE IS DESCRIBED IN THE NEXT ANSWER. Ok, I've got my server installed and not want to create a real SSL server Certificate for it. How do I do it? Here is a step-by-step description: Make sure SSLeay is really installed and in your `PATH`. But some commands even work ok when you just run the ```ssleay`'' program from within the SSLeay source tree as ```./apps/ssleay`''. Create a RSA private key for your Apache server (will be Triple-DES encrypted and PEM formatted): `$ ssleay genrsa -des3 -out server.key 1024` Please backup this `server.key` file and remember the pass-phrase you had to enter at a secure location. You can see the details of this RSA private key via the command: `$ ssleay rsa -noout -text -in server.key` And you could create a decrypted PEM version (not recommended) of this RSA private key via: `$ ssleay rsa -in server.key -out server.key.unsecure` Create a Certificate Signing Request (CSR) for the server RSA private key (output will be PEM formatted): `$ ssleay req -new -days 365 -key server.key -out server.csr` You can see the details of this CSR via the command `$ ssleay req -noout -text -in server.csr` You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) for signing. The result is then a real Certificate which can be used for Apache. Here you have to options: First you can let the CSR sign by a commercial CA like Verisign or Thawte. Then you usually have to post the CSR into a web form, pay for the signing and await the signed Certificate you then can store into a server.crt file. For more information about commercial CAs have a look at the following locations: Verisign http://digitalid.verisign.com/server/apacheNotice.htm Thawte Consulting http://www.thawte.com/certs/server/request.html CertiSign Certificadora Digital Ltda. http://www.certisign.com.br IKS GmbH http://www.iks-jena.de/produkte/ca/ Uptime Commerce Ltd. http://www.uptimecommerce.com BelSign NV/SA http://www.belsign.be Second you can use your own CA and now have to sign the CSR yourself by this CA. Read the next answer in this FAQ on how to sign a CSR with your CA yourself. You can see the details of the received Certificate via the command: `$ ssleay x509 -noout -text -in server.crt` Now you have two files: `server.key` and `server.crt`. These now can be used as following inside your Apache's `httpd.conf` file:
                SSLCertificateFile    /path/to/this/server.crt
                SSLCertificateKeyFile /path/to/this/server.key
The `server.csr` file is no longer needed. How can I create and use my own Certificate Authority (CA)? The short answer is to use the `CA.sh` script provided by SSLeay. The long and manual answer is this: Create a RSA private key for your CA (will be Triple-DES encrypted and PEM formatted): `$ ssleay genrsa -des3 -out ca.key 1024` Please backup this `ca.key` file and remember the pass-phrase you currently entered at a secure location. You can see the details of this RSA private key via the command `$ ssleay rsa -noout -text -in ca.key` And you can create a decrypted PEM version (not recommended) of this private key via: `$ ssleay rsa -in ca.key -out ca.key.unsecure` Create a self-signed CA Certificate (X509 structure) for the RSA key of the CA (output will be PEM formatted): `$ ssleay req -new -x509 -days 365 -key ca.key -out ca.crt` You can see the details of this Certificate via the command: `$ ssleay x509 -noout -text -in ca.crt` Prepare a script for signing which is needed because the ```ssleay ca`'' command has some strange requirements and the default SSLeay config doesn't allow one easily to use ```ssleay ca`'' directly. So a script named `ca.sign` is distributed with the mod_ssl distribution. Use this script for signing. Now you can use this CA to sign CSR's in order to create real SSL Certificates for use inside an Apache webserver: `$ ./ca.sign server.csr` This signs the CSR and results in a `server.crt` file. How can I change the pass-phrase on my private key file? You simply have to read it with the old pass-phrase and write it again by specifying the new pass-phrase. You can accomplish this with the following commands: `$ ssleay rsa -des3 -in server.key -out server.key.new` `$ mv server.key.new server.key` Here you're asked two times for a PEM pass-phrase. At the first prompt enter the old pass-phrase and at the second prompt enter the new pass-phrase. How can I get rid of the pass-phrase dialog at Apache startup time? The reason why this dialog pops up at startup and every re-start is that the RSA private key inside your server.key file is stored in encrypted format for security reasons. The pass-phrase is needed to be able to read and parse this file. When you can be sure that your server is secure enough you perform two steps: Remove the encryption from the RSA private key (while preserving the original file): `$ cp server.key server.key.org` `$ ssleay rsa -in server.key.org -out server.key` Make sure the server.key file is now only readable by root: `$ chmod 400 server.key` Now `server.key` will contain an unencrypted copy of the key. If you point your server at this file it will not prompt you for a pass-phrase. HOWEVER, if anyone gets this key they will be able to impersonate you on the net. PLEASE make sure that the permissions on that file are really such that only root or the web server user can read it (preferably get your web server to start as root but run as another server, and have the key readable only by root). How do I verify that a private key matches its Certificate? The private key contains a series of numbers. Two of those numbers form the "public key", the others are part of your "private key". The "public key" bits are also embedded in your Certificate (we get them from your CSR). To check that the public key in your cert matches the public portion of your private key, you need to view the cert and the key and compare the numbers. To view the Certificate and the key run the commands: `$ ssleay x509 -noout -text -in server.crt` `$ ssleay rsa -noout -text -in server.key` The `modulus' and the `public exponent' portions in the key and the Certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: `$ ssleay x509 -noout -modulus -in server.crt | ssleay md5` `$ ssleay rsa -noout -modulus -in server.key | ssleay md5` And then compare these really shorter numbers. With overwhelming probability they will differ if the keys are different. BTW, if I want to check to which key or certificate a particular CSR belongs you can compute `$ ssleay req -noout -modulus -in server.csr | ssleay md5` Why does my 2048-bit private key not work? The private key sizes must be either 512 or 1024 for compatibility with certain web browsers. A keysize of 1024 bits is recommended because keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit. Why is client authentication broken after upgrading from SSLeay version 0.8 to 0.9? The CA certificates under the path you configured with `SSLCACertificatePath` are found by SSLeay through hash symlinks. These hash values are generated by the ``ssleay x509 -noout -hash`' command. But the algorithm used to calculate the hash for a certificate has changed between SSLeay 0.8 and 0.9. So you have to remove all old hash symlinks and re-create new ones after upgrading. Use the `Makefile` mod_ssl placed into this directory. ## About SSL Protocol Why has my webserver a higher load now that I run SSL there? Because SSL uses strong cryptographic encryption and this needs a lot of number crunching. And because when you request a webpage via HTTPS even the images are transfered encrypted. There is dramatically more to do on the webserver, so the load increases. What SSL Ciphers are supported by mod_ssl? Usually just all SSL ciphers which are supported by the version of SSLeay in use (can depend on the way you built SSLeay). Typically this at least includes the following: RC4 with MD5 RC4 with MD5 (export version restricted to 40-bit key) RC2 with MD5 RC2 with MD5 (export version restricted to 40-bit key) IDEA with MD5 DES with MD5 Triple-DES with MD5 To determine the actual list of supported ciphers you can run the following command: `$ ssleay ciphers -v` Why can't I use SSL with name-based/non-IP-based virtual hosts? The reason is very technical. Actually it's some sort of a chicken and egg problem: The SSL protocol layer stays below the HTTP protocol layer and encapsulates HTTP. When an SSL connection (HTTPS) is established Apache/mod_ssl has to negotiate the SSL protocol parameters with the client. For this mod_ssl has to consult the configuration of the virtual server (for instance it has to look for the cipher suite, the server certificate, etc.). But in order to dispatch to the correct virtual server Apache has to know the `Host` HTTP header field. For this the HTTP request header has to be read. This cannot be done before the SSL handshake is finished. But the information is already needed at the SSL handshake phase. Bingo!
Compatibility | Glossary
mod_ssl 2.1, User Manual The Apache Interface to SSLeay | Copyright © 1998 Ralf S. Engelschall All Rights Reserved