Secured by mod_ssl Interface
Apache Interface to SSLeay
Includes SSLeay Encryption Software

Configuration Reference

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:

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 SSL-aware virtual servers. Because for security reasons the private key files are usually encrypted, Apache needs to query the user for a pass phrase in order to read those files. This query can be done in two ways which can be configured with this directives argument:

Example:

SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter


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.

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.

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:

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:

Example:

SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data


SSLSessionCacheTimeout

Syntax: SSLSessionCacheTimeout seconds
Default: SSLSessionCacheTimeout 300
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 -in certificate.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):

Example:

SSLLogLevel warn


SSLRequireSSL

Syntax: SSLRequireSSL
Default: None
Context: server config, virtual host, directory, >.htaccess
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 or directories for defending against configuration errors that expose stuff that should be protected. When this directive is present all requests are denied which are not using SSL.

Example:

SSLRequireSSL


SSLRequire

Syntax: SSLRequire expression
Default: None
Context: server config, virtual host, directory, .htaccess
Override: FileInfo
Status: Extension
Module: mod_ssl
Compatibility: Only available in Apache 1.3 with mod_ssl applied.

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It's a very powerful directive because the requirement specification is an arbitrary complex boolean expression containing any number of access checks.

The expression must match the following syntax (BNF notation):

expr     ::= "true" | "false" 
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word 
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}" 
function ::= funcname "(" funcargs ")"
while for varname the following names can be used:
HTTP_USER_AGENT          SSL_VERSION_LIBRARY  
HTTP_REFERER             SSL_VERSION_INTERFACE
HTTP_COOKIE              SSL_CIPHER           
HTTP_FORWARDED           SSL_CIPHER_USEKEYSIZE
HTTP_HOST                SSL_CIPHER_ALGKEYSIZE
HTTP_PROXY_CONNECTION    SSL_CLIENT_M_VERSION 
HTTP_ACCEPT              SSL_CLIENT_M_SERIAL  
HTTP:headername          SSL_CLIENT_V_START   
THE_REQUEST              SSL_CLIENT_V_END     
REQUEST_METHOD           SSL_CLIENT_S_DN      
REQUEST_URI              SSL_CLIENT_S_DN_C    
REQUEST_FILENAME         SSL_CLIENT_S_DN_SP   
PATH_INFO                SSL_CLIENT_S_DN_L    
QUERY_STRING             SSL_CLIENT_S_DN_O    
REMOTE_HOST              SSL_CLIENT_S_DN_OU   
REMOTE_IDENT             SSL_CLIENT_S_DN_CN   
IS_SUBREQ                SSL_CLIENT_S_DN_Email
DOCUMENT_ROOT            SSL_CLIENT_A_SIG     
SERVER_ADMIN             SSL_CLIENT_A_KEY     
SERVER_NAME              SSL_CLIENT_CERT      
SERVER_PORT              SSL_SERVER_M_VERSION 
SERVER_PROTOCOL          SSL_SERVER_M_SERIAL  
REMOTE_ADDR              SSL_SERVER_V_START   
REMOTE_USER              SSL_SERVER_V_END     
AUTH_TYPE                SSL_SERVER_S_DN      
SERVER_SOFTWARE          SSL_SERVER_S_DN_C    
API_VERSION              SSL_SERVER_S_DN_SP   
TIME_YEAR                SSL_SERVER_S_DN_L    
TIME_MON                 SSL_SERVER_S_DN_O    
TIME_DAY                 SSL_SERVER_S_DN_OU   
TIME_HOUR                SSL_SERVER_S_DN_CN   
TIME_MIN                 SSL_SERVER_S_DN_Email
TIME_SEC                 SSL_SERVER_A_SIG     
TIME_WDAY                SSL_SERVER_A_KEY     
TIME                     SSL_SERVER_CERT      
ENV:variablename 
and for funcname the following functions are available:
file("..")
Notice that expression is first parsed into an internal machine representation and then evaluated in a second step. Actually in per-server context expression gets parsed at startup time and under runtime the machine representation is used only. For per-directory context this is different: Here expression has to be parsed and immediately evaluated for every request.

Example:

SSLRequire     %{SSL_CIPHER} !~ m/^EXP-/ \
           and %{SSL_CIPHER} !~ m/NULL/  \
           and %{SSL_CLIENT_DN_CN} in ("Joe1", "Joe2", Joe3") \
           and %{REMOTE_ADDR} =~ m/^1\.2\.3\.[0-9]+$/


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.
SSL_PROTOCOL string The SSL protocol version (SSLv2, SSLv3, TLSv1)
SSL_CIPHER string The cipher specification name
SSL_CIPHER_USEKEYSIZE number Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE number Number of cipher bits (possible)
SSL_VERSION_INTERFACE string The mod_ssl program version
SSL_VERSION_LIBRARY string The SSLeay program version
SSL_CLIENT_M_VERSION string The version of the client certificate
SSL_CLIENT_M_SERIAL string The serial of the client certificate
SSL_CLIENT_S_DN string Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 string Component of client's Subject DN
SSL_CLIENT_I_DN string Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 string Component of client's Issuer DN
SSL_CLIENT_V_START string Validity of client's certificate (start time)
SSL_CLIENT_V_END string Validity of client's certificate (end time)
SSL_CLIENT_A_SIG string Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY string Algorithm used for the public key of client's certificate
SSL_SERVER_M_VERSION string The version of the server certificate
SSL_SERVER_M_SERIAL string The serial of the server certificate
SSL_SERVER_S_DN string Subject DN in server's certificate
SSL_SERVER_S_DN_x509 string Component of server's Subject DN
SSL_SERVER_I_DN string Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 string Component of server's Issuer DN
SSL_SERVER_V_START string Validity of server's certificate (start time)
SSL_SERVER_V_END string Validity of server's certificate (end time)
SSL_SERVER_A_SIG string Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY string Algorithm used for the public key of server's certificate

[where x509 is a component of an X.509 DN: C, SP, L, O, OU, CN, Email]


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"