Module mod_ssl - Apache Interface to SSLeay

Module mod_ssl
Apache Interface to SSLeay

Summary
This module provides strong cryptography for Apache via Netscape's Secure Socket Layer (SSL) through the free SSL implementation library SSLeay from Eric A. Young and Tim Hudson. The mod_ssl package was created by Ralf S. Engelschall and is based in parts on the Apache-SSL package developed by Ben Laurie. The mod_ssl package is licensed under a BSD-style license, which means, in short, that you are free to use it for commercial and non-commercial purposes (although you are advised to read the `` SSLeay - Is this legal'' FAQ before deploying a server), so long as you retain the copyright notices.
Restrictions

ATTENTION: This module uses strong cryptography and falls under certain export/import and use restrictions: Please REMEMBER that export and/or use of cryptography software or even just providing cryptography hooks is illegal in some parts of the world. When you re-distribute this package or even email patches/suggestions to the authors or other people PLEASE PAY CLOSE ATTENTION TO ANY APPLICABLE EXPORT/IMPORT LAWS. The author of mod_ssl is not liable for any violations you make here. So be carefully yourself.

Installation
Actually this module it is both a source extension (the module) and set of source patches for Apache. But because the main source parts are containing in the src/modules/ssl/ subdirectory as a regular Apache module it is documented like a standard module. It is not compiled in by default. You have to configure Apache via
$ SSL_BASE=/path/to/ssleay ./configure ... --enable-module=ssl
to enable this module and the source patches in the Apache kernel sources.

Directives

Main Server Configuration Directives:

SSLMutex
SSLPassPhraseDialog
SSLPassPhraseCaching

Main and/or Virtual Server Configuration Directives:

SSLEngine
SSLCipherSuite
SSLCertificateFile
SSLCertificateKeyFile
SSLCACertificatePath
SSLCACertificateFile
SSLCACertificateReqFile
SSLVerifyClient
SSLVerifyDepth
SSLSessionCache
SSLSessionCacheTimeout
SSLFakeBasicAuth
SSLLog
SSLLogLevel

Per-Directory Configuration Directives:

SSLRequireSSL
SSLRequireCipher
SSLBanCipher

Additional Features

Additional Environment Variables
Additional Custom Log Formats

Frequently Asked Questions

What are the differences between mod_ssl and the original Apache-SSL?
What are the user visible incompatibilities to Apache-SSL?
Ok, does this mean I should avoid using Apache-SSL any longer?
On which Apache-SSL version is mod_ssl actually based?
Why is mod_ssl's version starting with 2.0.0?
How do I know which mod_ssl version is for which Apache version?
I want to run HTTP and HTTPS on the same machine. Is that possible?
I know that HTTP is on port 80, but where is HTTPS?
How can I speak HTTPS manually for testing purposes?
What are RSA private keys, CSR's and Certificates?
Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?
How can I create a dummy SSL server Certificate for testing purposes?
Ok, I've got my server installed and not want to create a real SSL server Certificate for it. How do I do it?
How can I create and use my own Certificate Authority (CA)?
How can I change the pass-phrase on my private key file?
How can I get rid of the pass-phrase dialog on Apache startup time?
How do I verify that a private key matches its Certificate?
Why does my 2048-bit private key not work?
Why does my browser hang when I connect to my SSL-aware Apache server?
How can I use relative hyperlinks to switch between HTTP and HTTPS?
Why has my webserver a higher load now that I run SSL there?
What SSL Ciphers are supported by mod_ssl?

Directives

SSLMutex
Syntax: SSLMutex type
Default: SSLMutex none
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This configures the SSL engines lock which is used for mutual exclusion of operations which have to be done in a syncronized way between the pre-forked Apache server processed. This directive can only be used in the main server because it's only useful to have one global mutex.
The following mutex types are possible:

``none''
This is the default where no mutex is used at all. Use this at your own risk. But because currently the mutex is mainly used for synchronizing write access to the the SSL Session Cache you can life without it as long as you don't use the Session Cache. But it's always recommended to leave this default. Instead configure a real mutex.

``file:/path/to/mutex''
This is the portable and always provided mutex variant where a physical file is used as the mutex. Always use a local disk filesystem for /path/to/mutex and never a file staying on a NFS-filesystem.

``ipcsem''
This is the most elegant but also most non-portable mutex variant where a SysV IPC Semaphore is used. This is only available when the underlaying platform supports it.

Example:
SSLMutex file:/usr/local/apache/logs/ssl_mutex
SSLPassPhraseDialog
Syntax: SSLPassPhraseDialog type
Default: SSLPassPhraseDialog builtin
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and private key (see SSLCertificateKeyFile) files of the configured virtual servers. Because for security reasons the private key files are usually encrypted, so Apache needs to query the user for a pass phrase in order to read those files. This query can be done in various ways which can be configured with this directives argument:

``builtin''
This is the default uses an interactive terminal prompt to occur at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the pass phrase. Because on restarts the pass phrase is needed again but Apache is then alreadys detached from the terminal (so the interactive query cannot be done again) this is only useful in combination with ``SSLPassPhraseCaching on'' or you server will fall down on forthcoming restarts.

``exec:/path/to/program''
Here an external program is configured which is called at startup and restart times and has to provide the pass phrase as a single line on stdout. When ``SSLPassPhraseCaching off'' is used this is the only way one can provide the pass phrase on restarts. The intent is that this external program first runs security checks to make sure that the system is not vulnerabled by an attacker, and only when these checks were passed successfully it provides the pass-phrase.
Both these security checks and the way the pass phrase is determined can be as complex as one could think about it. Because mod_ssl just defines the interface: An executable program which provides the pass phrase on stdout. Nothing more or less. So, when you're a really paranoid about security, here is your interface. Anything else has to be left as an exercise for the administrator because local security requirements or too different.
NOTE 1: The dialog for a pass phrase is done only once on startup or restart time, independed how much virtual hosts were configured with encrypted private key files. The first virtual host with an encrypted pass phrase forces the pass phrase dialog to occur and the queried pass phrase is then used to read all existing encrypted private key files. So, when you have more than one SSL-aware vitual host configured with encrypted private key files make sure that all those private key files use the same pass phrase.
NOTE 2: The reading of the private key files is done a lot of time later in the internal Apache processing than the pass phrase dialog. So, when the queried pass phrase is wrong, the first time this can be discovered is when the private key files are read. No error message will occur on the terminal. Instead when Apache doesn't startup correctly you have to check the Apache error logfile or the dedicated SSL logfile.
Example:
SSLPassPhraseDialog /usr/local/apache/sbin/pp-filter
SSLPassPhraseCaching
Syntax: SSLPassPhraseCaching on/off
Default: SSLPassPhraseCaching on
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
At server restart time the pass phrase has to be available again to read encrypted private key files. This is only possible in two ways: Either the pass phrase is cached on startup time for forthcoming restarts or an external program has to be used with the SSLPassPhraseDialog directive (which then can be run again at restart time).
With the SSLPassPhraseCaching directive you can control if the pass phrase is cached after the inital query (independed if it was queried interactively or through the external program) for resatrts. When ``SSLPassPhraseDialog builtin'' is used it is highly recommended to let the pass phrase cached. Because else your server falls down on forthcoming restarts. When using an external dialog program this program is either run only once at startup (SSLPassPhraseCaching on) or at startup and every restart (SSLPassPhraseCaching off).
Example:
SSLPassPhraseCaching off
SSLEngine
Syntax: SSLEngine on|off
Default: SSLEngine off
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive switches the usage of the SSL protocol engine. This is usually used inside a virtual host section to enable the SSL protocol engine. Because per default the SSL protocol engine is disabled for the main server and each virtual host.
Compatibility: For backward compatibility with Apache-SSL the deprecated directives SSLEnable and SSLDisable are provided by the mod_sslcompat module. They are automatically mapped to the corresponding SSLEngine directive. But notice that in Apache-SSL the default is SSLEnable, while for mod_ssl the default is SSLDisable.

Example:
SSLEngine on
SSLCipherSuite
Syntax: SSLCipherSuite list
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the colon-separated list of Ciphers that the client is permitted to negotiate. The current list of known Chipers are the following ones (per default all of them are permitted to negotiate):
NULL-MD5                    EDH-DSS-DES-CBC3-SHA
NULL-SHA                    EXP-EDH-RSA-DES-CBC 
EXP-RC4-MD5                 EDH-RSA-DES-CBC-SHA 
RC4-MD5                     EDH-RSA-DES-CBC3-SHA
RC4-SHA                     EXP-ADH-RC4-MD5     
EXP-RC2-CBC-MD5             ADH-RC4-MD5         
IDEA-CBC-MD5                EXP-ADH-DES-CBC-SHA 
EXP-DES-CBC-SHA             ADH-DES-CBC-SHA     
DES-CBC-SHA                 ADH-DES-CBC3-SHA    
DES-CBC3-SHA                FZA-NULL-SHA        
EXP-DH-DSS-DES-CBC-SHA      FZA-FZA-CBC-SHA     
DH-DSS-DES-CBC-SHA          FZA-RC4-SHA         
DH-DSS-DES-CBC3-SHA         DES-CFB-M1          
EXP-DH-RSA-DES-CBC-SHA      RC2-CBC-MD5         
DH-RSA-DES-CBC-SHA          DES-CBC-MD5         
DH-RSA-DES-CBC3-SHA         DES-CBC3-MD5        
EXP-EDH-DSS-DES-CBC-SHA     RC4-64-MD5          
EDH-DSS-DES-CBC-SHA
Example:
SSLCipherSuite RC4-MD5:RC4-SHA:IDEA-CBC-MD5:DES-CBC3-SHA
SSLCertificateFile
Syntax: SSLCertificateFile file
Default: SSLCertificateFile conf/sslcerts/server.pem
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive points to a PEM-encoded SSL server Certificate file and optionally also to the corresponding server RSA Private Key file (contained in the same file). If the contained private key file is encrypted the pass phrase dialog is forced at startup time and if ``SSLPassPhraseCaching off'' is used even on every restart. Also when you use more than one SSL-aware virtual host with encrypted private key files, make sure all those private key files are encrypted with the same pass phrase.
Example:
SSLCertificateFile /usr/local/apache/conf/sslcerts/server.pem
SSLCertificateKeyFile
Syntax: SSLCertificateKeyFile
Default: same file as given on SSLCertificateFile
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive points to the PEM-encoded private key file for the server. If the private key is not combined with the Certificate in the SSLCertificateFile, use this additional directive to point at the file with the private key. When SSLCertificateFile is used and the file contains both the Certificate and the private key this directive need not be used. If the contained private key file is encrypted the pass phrase dialog is forced at startup time and if ``SSLPassPhraseCaching off'' is used even on every restart. Also when you use more than one SSL-aware virtual host with encrypted private key files, make sure all those private key files are encrypted with the same pass phrase.
Example:
SSLCertificateKeyFile /usr/local/apache/etc/sslkeys/server.pem
SSLCACertificatePath
Syntax: SSLCACertificatePath directory
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the directory path where you keep the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for SSL Client Authentication.
The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the Certificate files there. Additionally you have to create symlinks named hash.0. So you should always make sure this directory contains the appropriate symlinks. Use the Makefile which mod_ssl automatically added to this directory to accomplish this task.
Example:
SSLCACertificatePath /usr/local/apache/etc/sslcerts
SSLCACertificateFile
Syntax: SSLCACertificateFile file
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the all-in-one file where you assembled the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for SSL Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLCaCertificatePath.
Example:
SSLCACertificateFile /usr/local/apache/etc/sslcerts/ca.pem
SSLCACertificateReqFile
Syntax: SSLCACertificateReqFile file
Default: same file as given on SSLCACertifcateFile
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the all-in-one file where you assembled the Certificates of Certification Authorities (CA) whose CAs you deal with. These are optionally used by the clients for SSLv3 Server Authentication to speedup processing. The file is requested by the client via the ``SSLv3 write Certificate request A'' for loading intermediate CA Certificates in a possible Certificate chain (only SSLv3). It's simply the concatenation of the various PEM-encoded Certificate files, in order of preference. Per default this is the same as SSLCACertificateFile.
Example:
SSLCACertificateReqFile /usr/local/apache/etc/sslcerts/careq.pem
SSLVerifyClient
Syntax: SSLVerifyClient level
Default: SSLVerifyClient 0
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the verification level for the SSL Client Authentication. The following levels are available for level:

none: no Certificate is required at all
optional: the client may present a valid Certificate
require: the client has to present a valid Certificate
optional_no_ca: the client may present a valid Certificate but it is not required to have a valid CA
In practice only levels none and require are interesting. Because level optional doesn't work with all browsers and level optional_no_ca is actually against the idea of authentication.
Compatibility: For backward compatibility with Apache-SSL the level aliases 0 (=none), 1 (=optional), 2 (=require) and 3 (=optional_no_ca) are also recognized.

Example:
SSLVerifyClient require
SSLVerifyDepth
Syntax: SSLVerifyDepth number
Default: SSLVerifyDepth 0
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets how deeply SSLeay should verify the Certifcate chain before deciding the client doesn't have a valid Certificate. The depth actually is the number of intermediate SSL Certificates between the client Certificate and the one the server knows of. Using the default depth of 0 means the client Certificate has to be signed by a CA which is directly known to the server (i.e. the CA's Certificate is under SSLCACertificatePath or in the SSLCACertificateFile).
Example:
SSLVerifyDepth 10
SSLSessionCache
Syntax: SSLSessionCache type
Default: SSLSessionCache none
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This configures the storage type of the inter-process SSL Session Cache. The inter-process Session Cache is an optional feature which just speeds up parallel requests of the clients. Because for requests to the same server process (via HTTP keep-alive) SSLeay already caches the SSL session information locally. But because modern clients request inlined images and other data via parallel requests (usually up to four parallel requests are common) those requests would be served by different pre-forked server processes. Here an inter-process Session Cache helps to avoid unneccessary session handshake. The following two storage types are currently supported:

``none''
This is the default and just disabled the global inter-process Session Cache. There is now drawback in functionality. But a speed penalty can be observed.

``dbm:/path/to/datafile''
This makes use a a DBM hashfile on the local disk to synchronize the local memory caches of the server processes. The little more amount of I/O on the server results in a visible request speedup for your clients. So it's recommended to use this storage.

Example:
SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
SSLSessionCacheTimeout
Syntax: SSLSessionCacheTimeout seconds
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive set timeout in seconds for the information stored in the inter-process SSL Session Cache and the SSLeay internal memory cache. It can be set to low number like 15 for testing, but should be set to higher values like 300 in real life.
Example:
SSLSessionCacheTimeout 300
SSLFakeBasicAuth
Syntax: SSLFakeBasicAuth
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive translates the Subject Distinguished Name (DN) of the client X509 Certifcate into a HTTP Basic Authorization username. This means that the standard Apache authentication methods can be used for access control. The user name is just the Subject of the client's X509 Certificate (can be determined by running SSLeay's x509 command: x509 -noout -subject -incertificate.pem). Note that no password is obtained from the user. Every entry in the user file needs this password: ``xxj31ZMTZzkVA'', which is the encrypted version of the word ``password''.
Example:
SSLFakeBasicAuth
SSLLog
Syntax: SSLLog file
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the home of the dedicated SSL protocol logfile. Error type messages are additionally duplicated to the general Apache error log file. Put this somewhere where it cannot be used for symlink attacks on a real server (i.e. somewhere where only root can write). If the file does not begin with a slash ('/') then it is assumed to be relative to the Server Root. If file begins with a bar ('|') then the following string is assumed to be a path to an executable program to which a reliable pipe can be established. The directive should occur only once per virtual server config.
Example:
SSLLog logs/ssl_log
SSLLogLevel
Syntax: SSLLogLevel level
Default: SSLLogLevel none
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive sets the verbosity degree of the dedicated SSL protocol logfile. The level is one of the following (in ascending order where higher levels include lower levels):

none: no dedicated SSL logging is done, but errors are still duplicated to the general Apache error logfile.
error: log messages of error type only, but duplicate them to the general Apache error logfile, too.
warn: log also messages of warning type
info: log also messages of information type
debug: log also messages of debugging type

Example:
SSLLogLevel warn
SSLRequireSSL
Syntax: SSLRequireSSL
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive forbids access except when SSL is in use. Very handy inside the SSL-enabled virtual host for defending against configuration errors that expose stuff that should be protected.
Example:
SSLRequireSSL
SSLRequireCipher
Syntax: SSLRequireCipher cipher-list
Default: None
Context: directory, .htaccess
Override: FileInfo
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive adds a cipher to the per directory list of required ciphers.
Example:
SSLRequireCipher RC4-MD5
SSLBanCipher
Syntax: SSLBanCipher cipher-list
Default: None
Context: directory, .htaccess
Override: FileInfo
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.
This directive forces a cipher to be banned in a per directory context.
Example:
SSLBanCipher RC4-MD5
Additional Features

Additional Environment Variables
This module provides a few additional environment variables to the SSI and CGI interfaces:

Name Value Description

HTTPS flag HTTPS is being used.

HTTPS_CIPHER string SSL/TLS cipher specification

SSL_CIPHER string The same as HTTPS_CIPHER

SSL_PROTOCOL_VERSION string The SSL protocol version

SSL_SSLEAY_VERSION string The SSLeay program version

HTTPS_KEYSIZE number Number of bits in the session key

HTTPS_SECRETKEYSIZE number Number of bits in the secret key

SSL_CLIENT_DN string DN in client's Certificate

SSL_CLIENT_x509 string Component of client's DN

SSL_CLIENT_I_DN string DN of issuer of client's Certificate

SSL_CLIENT_I_x509 string Component of client's issuer's DN

SSL_SERVER_DN string DN in server's Certificate

SSL_SERVER_x509 string Component of server's DN

SSL_SERVER_I_DN string DN of issuer of server's Certificate

SSL_SERVER_I_x509 string Component of server's issuer's DN

[where x509 is a component of an X509 DN]

Additional Custom Log Formats
The source patches for mod_ssl also added four new format identifiers for the Custom Log Format of mod_log_config.
%...{version}c:    SSL protocol version
%...{cipher}c:     SSL cipher
%...{subjectdn}c:  Client Certificate subject distinguished name
%...{issuerdn}c:   Client Certificate issuer  distinguished name
%...{errcode}c:    X509 verify error code
%...{errstr}c:     X509 verify error string
Use these with the CustomLog directive to create a custom SSL logfile:
CustomLog logs/ssl_req_log \
          "%t %h %{version}c %{cipher}c %{subjectdn}c %{issuerdn}c \"%r\" %b"
Frequently Asked Questions
What are the differences between mod_ssl and the original Apache-SSL?
This cannot be answered in short, because there are a lot of changes (see the CHANGES file in the mod_ssl distribution for detailed information). Most of them are internal changes and re-organizations of the source code. But the user visible changes are mainly the following:

mod_ssl provides a complete documentation (this document) of all configuration directives, environment variables, etc. while Apache-SSL still has no such documentation although it exists for over three years now. 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. Because these are the typical hurdles every user stumbles over.

mod_ssl comes as 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's absolutely incomprehensible to the author 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 can be easily applied to the Apache source tree because it provides an automated process for this task while Apache-SSL forces the user to fiddle with the patch and cp tools theirself. Just because security is not for amateurs haven't 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.

mod_ssl fixes a lot of bugs and inconsistencies 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 passes it) because of unclean code.
Additionally Apache-SSL it 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) under 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 functionality which is missing in Apache-SSL. For instance 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 provides the SSLCACertificateReqFile directive which can be used to configure a different (from SSLCACertificateFile) set of CA Certifcates for the SSLv3 feature used by the clients to load CA Certifcates from the server for speeding up server authentication.

For more details I really advice you to read the CHANGES file from the mod_ssl distribution.

What are the user visible incompatibilities to Apache-SSL?

<IfModule apache_ssl.c> --> <IfModule mod_ssl.c> or <IfDefine MOD_SSL>
Because of the renamed source files, when you used <IfModule> containers inside your server config files to encapsulate Apache-SSL directives, you now have to use the filename mod_ssl.c instead. Although such changes are nasty for the users the new name directly follows the Apache module conventions. Additionally to let you distinguish between Stronghold and mod_ssl (both use mod_ssl.c) a define MOD_SSL is provided which can be used with <IfDefine> sections.

Ben-SSL/1.18 --> mod_ssl/2.0.0 SSLeay/0.9.0b
Because the workhorse of SSL inside Apache is SSLeay and not mod_ssl, the SSLeay version is more important in the HTTP Server field. So both mod_ssl's and SSLeay's version is now added to the Server field.

httpsd --> httpd -DSSL
The provided (and installed) default configuration is SSL-ready but has SSL-related directives encapsulated in <IfDefine SSL> sections. So, when you immediately want to fire up your httpd with SSL enabled you have to specify the -DSSL option on the command line. Or edit the configuration. Additionally the Apache server executable is again named httpd and not httpsd, because the intent is that the mod_ssl package only patches things inside Apache which are really necessary to patch.

Skip first time initialization...
These and other verbose terminal messages of Apache-SSL were completely removed because its nasty to get those messages when a daemon is run (especially when its run from Boot scripts or Cron scripts). Instead the remaining useful ones are now printed to the dedicated SSL logfile.

SSLEnable/SSLDisable --> SSLEngine on/off
The SSLEnable and SSLDisable directives were made obsolete by adding the simpler SSEngine on/off directive. The old directives are now deprecated but still can be used for backward-compatibility to Apache-SSL. Additionally the default is now SSLEngine off (formerly SSLDisable) instead of the Apache-SSL default of SSLEngine on. This breaks a little bit with Apache-SSL semantics, but doesn't hurt as much as it sounds. Because people run SSL inside a virtual hosts and thus already have a SSLDisable in their main (non-SSL) server. The difference is just that with mod_ssl one no longer has to add SSLDisable to all non-SSL virtual hosts (which is nasty especially for ISPs running thousends of virtual hosts). OTOH SSL is an additional feature, so the logic of `disabled per default and have to be enabled explicity' is more useful and what is expected.

Ok, does this mean I should avoid using Apache-SSL any longer?
No, it just means that you can use mod_ssl instead if you prefer maximum cleanness and up-to-date stuff. But beside some bugs Apache-SSL works great. Ben Laurie did and still does a great job in maintaining it. The big difference is just that Ben's goals are not really cleanness or user friendliness. So, as long as you don't get bothered by the inconsistencies and the fact that it's mostly impossible for you to re-view Apache-SSL's internals for security reasons 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. 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.0.1-1.3.1. This directly indicated that it's mod_ssl version 2.0.1 for Apache version 1.3.1. And this also means you only can apply this mod_ssl version to exactly this Apache version.

I want to run HTTP and HTTPS on the same machine. Is that possible?
There are two ways to do this: run two server daemons, or run both services from the same daemon. Unless there is a good reason to run two (like using a different product for secure/non-secure), it's usually simplest to run a single daemon and disable SSL on those virtual hosts that don't need it. If you wish to run two daemons you must make sure that they each only try to bind to their alloted ports (normally port 80 for non-secure and 443 for secure).

I know that HTTP is on port 80, but where is HTTPS?
You can run HTTPS on any port, but the standard specifies port 443, which is where any 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 -host localhost -port 443
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 cURL. 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/

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.

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. This pass phrase you had to enter only once and is stored in memory, so it is available on all following server restarts.
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 on 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 on 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.cert 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.cert
Now you have two files: server.key and server.cert. These now can be used as following inside your Apache's httpd.conf file:
       SSLCertificateFile    /path/to/this/server.cert
       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.cert
You can see the details of this Certificate via the command:
$ ssleay x509 -noout -text -in ca.cert

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.cert 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 on 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.cert
$ ssleay rsa -noout -text -in server.key
The `modulus' and the `public exponent' portions in the key and the Certificate must match.

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 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">
    
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 chipers which are supported by the used version of SSLeay (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

Name	Value	Description

`HTTPS`	flag	HTTPS is being used.
`HTTPS_CIPHER`	string	SSL/TLS cipher specification
`SSL_CIPHER`	string	The same as HTTPS_CIPHER
`SSL_PROTOCOL_VERSION`	string	The SSL protocol version
`SSL_SSLEAY_VERSION`	string	The SSLeay program version
`HTTPS_KEYSIZE`	number	Number of bits in the session key
`HTTPS_SECRETKEYSIZE`	number	Number of bits in the secret key
`SSL_CLIENT_DN`	string	DN in client's Certificate
`SSL_CLIENT_`x509	string	Component of client's DN
`SSL_CLIENT_I_DN`	string	DN of issuer of client's Certificate
`SSL_CLIENT_I_`x509	string	Component of client's issuer's DN
`SSL_SERVER_DN`	string	DN in server's Certificate
`SSL_SERVER_`x509	string	Component of server's DN
`SSL_SERVER_I_DN`	string	DN of issuer of server's Certificate
`SSL_SERVER_I_`x509	string	Component of server's issuer's DN

Module mod_sslApache Interface to SSLeay

Summary

Restrictions

Installation

Directives

Additional Features

Frequently Asked Questions

Directives

Additional Features

Frequently Asked Questions

Module mod_ssl
Apache Interface to SSLeay