Module mod_ssl - Apache Interface to SSLeay

> | 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.

> - ```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 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 to `stdout`. 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` 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:

> - 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: `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):

> >     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"