![]()
Apache Interface to SSLeay![]()
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:
- ``
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.
- ``
sem
''This is the most elegant but also most non-portable mutex variant where a SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) 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 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:
- ``
builtin
''This is the default where an interactive terminal dialog occurs at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the pass phrase for each encrypted private key file. Because a lot of SSL-aware virtual hosts can be configured, the following reuse-scheme is used to minimize the dialog: When a private key file is encrypted, all known pass phrases (at the beginner there are none, of course) are tried. If one of those known pass phrases succeeds no dialog pops up for this file. If none succeeded, another pass phrase is queried and remembered for the next round (where it perhaps can be reused).
This scheme allows mod_ssl to be maximum flexible (because for N encrypted private key files you can use N different pass phrases - but then you have to enter all of them, of course) while minimizing the dialog (i.e. when you use a single pass phrase for all N private key files this pass phrase is queried only once).
- ``
exec:/path/to/program
''Here an external program is configured which is called at startup for each encrypted private key file. It is called with an argument of
servername:portnumber
for which it has to print the corresponding pass phrase tostdout
. 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.The reuse-algorithm above is used here, too. In other words: The external program is called only once per unique pass phrase.
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
andSSLDisable
are provided by themod_sslcompat
module. They are automatically mapped to the correspondingSSLEngine
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-SHAExample:
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 onSSLCertificateFile
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. WhenSSLCertificateFile
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.
- 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
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: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):
- 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, 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):
while forexpr ::= "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 ")"varname
the following names can be used:and forHTTP_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:variablenamefuncname
the following functions are available: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.file("..")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_
x509string Component of client's Subject DN SSL_CLIENT_I_DN
string Issuer DN of client's certificate SSL_CLIENT_I_DN_
x509string 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_
x509string Component of server's Subject DN SSL_SERVER_I_DN
string Issuer DN of server's certificate SSL_SERVER_I_DN_
x509string 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 stringUse these with theCustomLog
directive to create a custom SSL logfile:CustomLog logs/ssl_req_log \ "%t %h %{version}c %{cipher}c %{subjectdn}c %{issuerdn}c \"%r\" %b"