76b43e4417bab52e913da39b5f5bc2a130d3f149Timo Sirainen<?xml version="1.0"?>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<modulesynopsis metafile="mod_ssl.xml.meta">

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<name>mod_ssl</name>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<description>Strong cryptography using the Secure Sockets

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenLayer (SSL) and Transport Layer Security (TLS) protocols</description>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<status>Extension</status>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<sourcefile>mod_ssl.c</sourcefile>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<identifier>ssl_module</identifier>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<summary>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<p>This module provides SSL v2/v3 and TLS v1 support for the Apache

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenHTTP Server. It was contributed by Ralf S. Engeschall based on his

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenmod_ssl project and originally derived from work by Ben Laurie.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<p>This module relies on <a href="http://www.openssl.org/">OpenSSL</a>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainento provide the cryptography engine.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen<p>Further details, discussion, and examples are provided in the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<a href="/ssl/">SSL documentation</a>.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</summary>

d67c6dc68cdb90b53434a25ead1590650e4d84e7Timo Sirainen

d67c6dc68cdb90b53434a25ead1590650e4d84e7Timo Sirainen<section id="envvars"><title>Environment Variables</title>

d67c6dc68cdb90b53434a25ead1590650e4d84e7Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<p>This module provides a lot of SSL information as additional environment

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenvariables to the SSI and CGI namespace. The generated variables are listed in

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenthe table below. For backward compatibility the information can

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenbe made available under different names, too. Look in the <a

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainenhref="/ssl/ssl_compat.html">Compatibility</a> chapter for details on the

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainencompatibility variables.</p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<table border="1">

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<columnspec><column width=".3"/><column width=".2"/><column width=".5"/>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</columnspec>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <th><a name="table3">Variable Name:</a></th>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen <th>Value Type:</th>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen <th>Description:</th>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_COMPRESS_METHOD</code></td> <td>string</td> <td>SSL compression method negotiated</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr>

41e09cca158ab614961e03deac60f12a58235cd3Timo Sirainen<tr><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr>

41e09cca158ab614961e03deac60f12a58235cd3Timo Sirainen<tr><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr>

4b231ca0bbe3b536acbd350101e183441ce0247aTimo Sirainen<tr><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CLIENT_V_REMAIN</code></td> <td>string</td> <td>Number of days until client's certificate expires</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr>

0d0451206a91e9f96e522075dce28a89adc2325dTimo Sirainen<tr><td><code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><code>NONE</code>, <code>SUCCESS</code>, <code>GENEROUS</code> or <code>FAILED:</code><em>reason</em></td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>

a23197a5232f34121b1d32b73f2279c5d2f4491cTimo Sirainen<tr><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</table>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<p><em>x509</em> specifies a component of an X.509 DN; one of

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>. In Apache 2.1 and

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenlater, <em>x509</em> may also include a numeric <code>_n</code>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainensuffix. If the DN in question contains multiple attributes of the

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainensame name, this suffix is used as an index to select a particular

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenattribute. For example, where the server certificate subject DN

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenincluded two OU fields, <code>SSL_SERVER_S_DN_OU_0</code> and

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each.</p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainenand later.</p>

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen</section>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<section id="logformats"><title>Custom Log Formats</title>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<p>When <module>mod_ssl</module> is built into Apache or at least

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenloaded (under DSO situation) additional functions exist for the <a

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenhref="mod_log_config.html#formats">Custom Log Format</a> of

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<module>mod_log_config</module>. First there is an

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenadditional ``<code>%{</code><em>varname</em><code>}x</code>''

137c1851d63c6575ebab35d261380423c4cf2b47Timo SiraineneXtension format function which can be used to expand any variables

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainenprovided by any module, especially those provided by mod_ssl which can

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainenyou find in the above table.</p>

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainen<p>

9b5a8e766112d24c12499aca85da5ddf24baad25Timo SirainenFor backward compatibility there is additionally a special

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainen``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainenprovided. Information about this function is provided in the <a

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainenhref="/ssl/ssl_compat.html">Compatibility</a> chapter.</p>

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainen<example><title>Example</title>

9b5a8e766112d24c12499aca85da5ddf24baad25Timo SirainenCustomLog logs/ssl_request_log \

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainen "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

9b5a8e766112d24c12499aca85da5ddf24baad25Timo Sirainen</example>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen</section>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<directivesynopsis>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<name>SSLPassPhraseDialog</name>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<description>Type of pass phrase dialog for encrypted private

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenkeys</description>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<syntax>SSLPassPhraseDialog <em>type</em></syntax>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<default>SSLPassPhraseDialog builtin</default>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<contextlist><context>server config</context></contextlist>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

6ef7e31619edfaa17ed044b45861d106a86191efTimo Sirainen<usage>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenWhen Apache starts up it has to read the various Certificate (see

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<directive module="mod_ssl">SSLCertificateFile</directive>) and

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenPrivate Key (see <directive

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenmodule="mod_ssl">SSLCertificateKeyFile</directive>) files of the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSL-enabled virtual servers. Because for security reasons the Private

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenKey files are usually encrypted, mod_ssl needs to query the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenadministrator for a Pass Phrase in order to decrypt those files. This

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenquery can be done in two ways which can be configured by

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<em>type</em>:</p>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<ul>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<li><code>builtin</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen This is the default where an interactive terminal dialog occurs at startup

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen time just before Apache detaches from the terminal. Here the administrator

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen has to manually enter the Pass Phrase for each encrypted Private Key file.

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen Because a lot of SSL-enabled virtual hosts can be configured, the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen following reuse-scheme is used to minimize the dialog: When a Private Key

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen file is encrypted, all known Pass Phrases (at the beginning there are

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen none, of course) are tried. If one of those known Pass Phrases succeeds no

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen dialog pops up for this particular Private Key file. If none succeeded,

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen another Pass Phrase is queried on the terminal and remembered for the next

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen round (where it perhaps can be reused).</p>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This scheme allows mod_ssl to be maximally flexible (because for N encrypted

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen Private Key files you <em>can</em> use N different Pass Phrases - but then

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen you have to enter all of them, of course) while minimizing the terminal

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen dialog (i.e. when you use a single Pass Phrase for all N Private Key files

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen this Pass Phrase is queried only once).</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>|/path/to/program [args...]</code>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <p>This mode allows an external program to be used which acts as a

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen pipe to a particular input device; the program is sent the standard

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen prompt text used for the <code>builtin</code> mode on

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <code>stdin</code>, and is expected to write password strings on

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <code>stdout</code>. If several passwords are needed (or an

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen incorrect password is entered), additional prompt text will be

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen written subsequent to the first password being returned, and more

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen passwords must then be written back.</p></li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<li><code>exec:/path/to/program</code>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen Here an external program is configured which is called at startup for each

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen encrypted Private Key file. It is called with two arguments (the first is

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen of the form ``<code>servername:portnumber</code>'', the second is either

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen server and algorithm it has to print the corresponding Pass Phrase to

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <code>stdout</code>. The intent is that this external program first runs

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen security checks to make sure that the system is not compromised by an

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen attacker, and only when these checks were passed successfully it provides

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen the Pass Phrase.</p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen Both these security checks, and the way the Pass Phrase is determined, can

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen be as complex as you like. Mod_ssl just defines the interface: an

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen executable program which provides the Pass Phrase on <code>stdout</code>.

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen Nothing more or less! So, if you're really paranoid about security, here

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen is your interface. Anything else has to be left as an exercise to the

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen administrator, because local security requirements are so different.</p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen <p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen The reuse-algorithm above is used here, too. In other words: The external

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen program is called only once per unique Pass Phrase.</p></li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</ul>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<example><title>Example</title>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo SirainenSSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</example>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</usage>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</directivesynopsis>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<directivesynopsis>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<name>SSLMutex</name>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<description>Semaphore for internal mutual exclusion of

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainenoperations</description>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<syntax>SSLMutex <em>type</em></syntax>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<default>SSLMutex none</default>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<contextlist><context>server config</context></contextlist>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<usage>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<p>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo SirainenThis configures the SSL engine's semaphore (aka. lock) which is used for mutual

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainenexclusion of operations which have to be done in a synchronized way between the

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainenpre-forked Apache server processes. This directive can only be used in the

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainenglobal server context because it's only useful to have one global mutex.

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenThis directive is designed to closely match the

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<directive module="mpm_common">AcceptMutex</directive> directive.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenThe following Mutex <em>types</em> are available:</p>

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen<ul>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>none | no</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This is the default where no Mutex is used at all. Use it at your own

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen risk. But because currently the Mutex is mainly used for synchronizing

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen write access to the SSL Session Cache you can live without it as long

59dd7ec90e6e2e78df64e954d65a7b3f28eccfb2Timo Sirainen as you accept a sometimes garbled Session Cache. So it's not recommended

59dd7ec90e6e2e78df64e954d65a7b3f28eccfb2Timo Sirainen to leave this the default. Instead configure a real Mutex.</p></li>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<li><code>posixsem</code>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This is an elegant Mutex variant where a Posix Semaphore is used when possible.

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen It is only available when the underlying platform

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen and <glossary>APR</glossary> supports it.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>sysvsem</code>

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen <p>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen This is a somewhat elegant Mutex variant where a SystemV IPC Semaphore is used when

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen possible. It is possible to "leak" SysV semaphores if processes crash before

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen the semaphore is removed. It is only available when the underlying platform

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen and <glossary>APR</glossary> supports it.</p></li>

8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainen<li><code>sem</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This directive tells the SSL Module to pick the "best" semaphore implementation

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen available to it, choosing between Posix and SystemV IPC, in that order. It is only

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen available when the underlying platform and <glossary>APR</glossary> supports at least one of the 2.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>pthread</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This directive tells the SSL Module to use Posix thread mutexes. It is only available

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen if the underlying platform and <glossary>APR</glossary> supports it.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>fcntl:/path/to/mutex</code>

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This is a portable Mutex variant where a physical (lock-)file and the <code>fcntl()</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen fucntion are used as the Mutex.

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen Always use a local disk filesystem for <code>/path/to/mutex</code> and never a file

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen residing on a NFS- or AFS-filesystem. It is only available when the underlying platform

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen and <glossary>APR</glossary> supports it. Note: Internally, the Process ID (PID) of the

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen Apache parent process is automatically appended to

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen <code>/path/to/mutex</code> to make it unique, so you don't have to worry

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen about conflicts yourself. Notice that this type of mutex is not available

838f56174b963779a88083a0d0e85b30d2d846e7Timo Sirainen under the Win32 environment. There you <em>have</em> to use the semaphore

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen mutex.</p></li>

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen<li><code>flock:/path/to/mutex</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This is similar to the <code>fcntl:/path/to/mutex</code> method with the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen exception that the <code>flock()</code> function is used to provide file

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen locking. It is only available when the underlying platform

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen and <glossary>APR</glossary> supports it.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>file:/path/to/mutex</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen This directive tells the SSL Module to pick the "best" file locking implementation

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen available to it, choosing between <code>fcntl</code> and <code>flock</code>,

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen in that order. It is only available when the underlying platform and <glossary>APR</glossary> supports

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen at least one of the 2.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>default | yes</code>

c27f03fa8fd2ef4acd1db814fae7d90e0eb9d3aeTimo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen This directive tells the SSL Module to pick the default locking implementation

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen as determined by the platform and <glossary>APR</glossary>.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</ul>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<example><title>Example</title>

59dd7ec90e6e2e78df64e954d65a7b3f28eccfb2Timo SirainenSSLMutex file:/usr/local/apache/logs/ssl_mutex

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</example>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</usage>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen</directivesynopsis>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<directivesynopsis>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen<name>SSLRandomSeed</name>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen<description>Pseudo Random Number Generator (PRNG) seeding

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainensource</description>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<syntax>SSLRandomSeed <em>context</em> <em>source</em>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen[<em>bytes</em>]</syntax>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<contextlist><context>server config</context></contextlist>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<usage>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<p>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo SirainenThis configures one or more sources for seeding the Pseudo Random Number

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo SirainenGenerator (PRNG) in OpenSSL at startup time (<em>context</em> is

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<code>startup</code>) and/or just before a new SSL connection is established

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen(<em>context</em> is <code>connect</code>). This directive can only be used

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainenin the global server context because the PRNG is a global facility.</p>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<p>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo SirainenThe following <em>source</em> variants are available:</p>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<ul>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<li><code>builtin</code>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen <p> This is the always available builtin seeding source. It's usage

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen consumes minimum CPU cycles under runtime and hence can be always used

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen without drawbacks. The source used for seeding the PRNG contains of the

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen current time, the current process id and (when applicable) a randomly

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen choosen 1KB extract of the inter-process scoreboard structure of Apache.

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen The drawback is that this is not really a strong source and at startup

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen time (where the scoreboard is still not available) this source just

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen produces a few bytes of entropy. So you should always, at least for the

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen startup, use an additional seeding source.</p></li>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen<li><code>file:/path/to/source</code>

c584c749b2894edce2323b12fa24957744ff556aTimo Sirainen <p>

c584c749b2894edce2323b12fa24957744ff556aTimo Sirainen This variant uses an external file <code>/path/to/source</code> as the

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen source for seeding the PRNG. When <em>bytes</em> is specified, only the

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen first <em>bytes</em> number of bytes of the file form the entropy (and

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen <em>bytes</em> is given to <code>/path/to/source</code> as the first

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen argument). When <em>bytes</em> is not specified the whole file forms the

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen entropy (and <code>0</code> is given to <code>/path/to/source</code> as

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen the first argument). Use this especially at startup time, for instance

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen with an available <code>/dev/random</code> and/or

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <code>/dev/urandom</code> devices (which usually exist on modern Unix

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen derivates like FreeBSD and Linux).</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen <em>But be careful</em>: Usually <code>/dev/random</code> provides only as

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen much entropy data as it actually has, i.e. when you request 512 bytes of

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen entropy, but the device currently has only 100 bytes available two things

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen can happen: On some platforms you receive only the 100 bytes while on

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen other platforms the read blocks until enough bytes are available (which

8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainen can take a long time). Here using an existing <code>/dev/urandom</code> is

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen better, because it never blocks and actually gives the amount of requested

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen data. The drawback is just that the quality of the received data may not

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen be the best.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen On some platforms like FreeBSD one can even control how the entropy is

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen actually generated, i.e. by which system interrupts. More details one can

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen find under <em>rndcontrol(8)</em> on those platforms. Alternatively, when

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen your system lacks such a random device, you can use tool

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen like <a href="http://www.lothar.com/tech/crypto/">EGD</a>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen (Entropy Gathering Daemon) and run it's client program with the

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen <code>exec:/path/to/program/</code> variant (see below) or use

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <code>egd:/path/to/egd-socket</code> (see below).</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>exec:/path/to/program</code>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen <p>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen This variant uses an external executable

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen <code>/path/to/program</code> as the source for seeding the

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen PRNG. When <em>bytes</em> is specified, only the first

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <em>bytes</em> number of bytes of its <code>stdout</code> contents

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen form the entropy. When <em>bytes</em> is not specified, the

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen entirety of the data produced on <code>stdout</code> form the

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen entropy. Use this only at startup time when you need a very strong

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen seeding with the help of an external program (for instance as in

5e96e0a8a59aa5d3e2d38a21a211335a023fbbc8Timo Sirainen the example above with the <code>truerand</code> utility you can

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen find in the mod_ssl distribution which is based on the AT&amp;T

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen <em>truerand</em> library). Using this in the connection context

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen slows down the server too dramatically, of course. So usually you

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen should avoid using external programs in that context.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>egd:/path/to/egd-socket</code> (Unix only)

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen This variant uses the Unix domain socket of the

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen external Entropy Gathering Daemon (EGD) (see <a

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen /crypto/</a>) to seed the PRNG. Use this if no random device exists

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen on your platform.</p></li>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen</ul>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen<example><title>Example</title>

beb6125ee872e7fed57745ab33e6de99639180f3Timo SirainenSSLRandomSeed startup builtin<br />

beb6125ee872e7fed57745ab33e6de99639180f3Timo SirainenSSLRandomSeed startup file:/dev/random<br />

beb6125ee872e7fed57745ab33e6de99639180f3Timo SirainenSSLRandomSeed startup file:/dev/urandom 1024<br />

beb6125ee872e7fed57745ab33e6de99639180f3Timo SirainenSSLRandomSeed startup exec:/usr/local/bin/truerand 16<br />

beb6125ee872e7fed57745ab33e6de99639180f3Timo SirainenSSLRandomSeed connect builtin<br />

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSLRandomSeed connect file:/dev/random<br />

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSLRandomSeed connect file:/dev/urandom 1024<br />

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</example>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</usage>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<name>SSLSessionCache</name>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<description>Type of the global/inter-process SSL Session

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo SirainenCache</description>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<syntax>SSLSessionCache <em>type</em></syntax>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<default>SSLSessionCache none</default>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<contextlist><context>server config</context></contextlist>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen<usage>

beb6125ee872e7fed57745ab33e6de99639180f3Timo Sirainen<p>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo SirainenThis configures the storage type of the global/inter-process SSL Session

2abddf4f02571af58bbc5954e07e7d4d68861189Timo SirainenCache. This cache is an optional facility which speeds up parallel request

2abddf4f02571af58bbc5954e07e7d4d68861189Timo Sirainenprocessing. For requests to the same server process (via HTTP keep-alive),

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo SirainenOpenSSL already caches the SSL session information locally. But because modern

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainenclients request inlined images and other data via parallel requests (usually

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainenup to four parallel requests are common) those requests are served by

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen<em>different</em> pre-forked server processes. Here an inter-process cache

2abddf4f02571af58bbc5954e07e7d4d68861189Timo Sirainenhelps to avoid unneccessary session handshakes.</p>

2abddf4f02571af58bbc5954e07e7d4d68861189Timo Sirainen<p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenThe following four storage <em>type</em>s are currently supported:</p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<ul>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>none</code>

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen

19e8adccba16ff419f5675b1575358c2956dce83Timo Sirainen <p>This disables the global/inter-process Session Cache. This

81a5d8714c566ce50c4a2409f59e82e716d576d2Timo Sirainen will incur a noticeable speed penalty and may cause problems if

19e8adccba16ff419f5675b1575358c2956dce83Timo Sirainen using certain browsers, particularly if client certificates are

eddd9bf1a1369aea4a2715f6be1137da6d17d293Timo Sirainen enabled. This setting is not recommended.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>nonenotnull</code>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen <p>This disables any global/inter-process Session Cache. However

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen it does force OpenSSL to send a non-null session ID to

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen accommodate buggy clients that require one.</p></li>

8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainen

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen<li><code>dbm:/path/to/datafile</code>

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen <p>This makes use of a DBM hashfile on the local disk to

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen synchronize the local OpenSSL memory caches of the server

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen processes. This session cache may suffer reliability issues under

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen high load.</p></li>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><code>shm:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>]

8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>This makes use of a high-performance cyclic buffer

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen (approx. <em>size</em> bytes in size) inside a shared memory

893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0Timo Sirainen segment in RAM (established via <code>/path/to/datafile</code>) to

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen synchronize the local OpenSSL memory caches of the server

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen processes. This is the recommended session cache.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen<li><code>dc:UNIX:/path/to/socket</code>

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen <p>This makes use of the <a

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen href="http://www.distcache.org/">distcache</a> distributed session

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen caching libraries. The argument should specify the location of

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen the server or proxy to be used using the distcache address syntax;

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen for example, <code>UNIX:/path/to/socket</code> specifies a UNIX

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen domain socket (typically a local dc_client proxy);

1b8887ba5759f78f4f819bfeba07f8f7b1133bdbTimo Sirainen <code>IP:server.example.com:9001</code> specifies an IP

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen address.</p></li>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</ul>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<example><title>Examples</title>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data<br />

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</example>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</usage>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</directivesynopsis>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<directivesynopsis>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<name>SSLSessionCacheTimeout</name>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<description>Number of seconds before an SSL session expires

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainenin the Session Cache</description>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<syntax>SSLSessionCacheTimeout <em>seconds</em></syntax>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<default>SSLSessionCacheTimeout 300</default>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<contextlist><context>server config</context>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<context>virtual host</context></contextlist>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<usage>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<p>

bb10ebcf076c959c752f583746d83805d7686df8Timo SirainenThis directive sets the timeout in seconds for the information stored in the

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainenglobal/inter-process SSL Session Cache and the OpenSSL internal memory cache.

bb10ebcf076c959c752f583746d83805d7686df8Timo SirainenIt can be set as low as 15 for testing, but should be set to higher

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenvalues like 300 in real life.</p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<example><title>Example</title>

bb10ebcf076c959c752f583746d83805d7686df8Timo SirainenSSLSessionCacheTimeout 600

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen</example>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen</usage>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen</directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<directivesynopsis>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<name>SSLEngine</name>

287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen<description>SSL Engine Operation Switch</description>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<syntax>SSLEngine on|off|optional</syntax>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<default>SSLEngine off</default>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<contextlist><context>server config</context>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<context>virtual host</context></contextlist>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<usage>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenThis directive toggles the usage of the SSL/TLS Protocol Engine. This

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainenis usually used inside a <directive module="core"

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainentype="section">VirtualHost</directive> section to enable SSL/TLS for a

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainenparticular virtual host. By default the SSL/TLS Protocol Engine is

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainendisabled for both the main server and all configured virtual hosts.</p>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<example><title>Example</title>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen&lt;VirtualHost _default_:443&gt;<br />

bb10ebcf076c959c752f583746d83805d7686df8Timo SirainenSSLEngine on<br />

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen...<br />

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen&lt;/VirtualHost&gt;

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen</example>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<p>In Apache 2.1 and later, <directive>SSLEngine</directive> can be set to

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<code>optional</code>. This enables support for

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenWithin HTTP/1.1. At this time no web browsers support RFC 2817.</p>

bb10ebcf076c959c752f583746d83805d7686df8Timo Sirainen</usage>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</directivesynopsis>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<name>SSLProtocol</name>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<description>Configure usable SSL protocol versions</description>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<syntax>SSLProtocol [+|-]<em>protocol</em> ...</syntax>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<default>SSLProtocol all</default>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<contextlist><context>server config</context>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<context>virtual host</context></contextlist>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen<usage>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<p>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo SirainenThis directive can be used to control which versions of the SSL protocol

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainenwill be accepted in new connections.</p>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<p>

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo SirainenThe available (case-insensitive) <em>protocol</em>s are:</p>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<ul>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>SSLv2</code>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen <p>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen original SSL protocol as designed by Netscape Corporation. Though it's

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen use has been deprecated, because of weaknesses in the security of the protocol.</p></li>

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>SSLv3</code>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen <p>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen This is the Secure Sockets Layer (SSL) protocol, version 3.0, from the Netscape Corportaion.

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen It is the successor to SSLv2 and the predecessor to TLSv1. It's supported by

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen almost all popular browsers.</p></li>

51795bfe9d05d92fe942cb451aec2b9d16d32a11Timo Sirainen

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>TLSv1</code>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen <p>

7e235b3a5f622813121cd18f351e036650aaf8f8Timo Sirainen This is the Transport Layer Security (TLS) protocol, version 1.0. It is the

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen successor to SSLv3 and is defined in <a href="http://www.ietf.org/rfc/rfc2246.txt">RFC2246</a>.

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen Which has been obsoleted by <a href="http://www.ietf.org/rfc/rfc4346.txt">RFC4346</a>.</p></li>

75ef04fc62a3955d3a5310410e09735cbd4e972bTimo Sirainen

a022088674a5ae72ed29ae001834cbad62a4f19fTimo Sirainen<li><code>All</code>

a022088674a5ae72ed29ae001834cbad62a4f19fTimo Sirainen <p>

a022088674a5ae72ed29ae001834cbad62a4f19fTimo Sirainen This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a

a022088674a5ae72ed29ae001834cbad62a4f19fTimo Sirainen convenient way for enabling all protocols except one when used in

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen combination with the minus sign on a protocol as the example above

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen shows.</p></li>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen</ul>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<example><title>Example</title>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen# enable SSLv3 and TLSv1, but not SSLv2<br />

80fc743146da5130de34174cdaad2576f103723fTimo SirainenSSLProtocol all -SSLv2

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</example>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</usage>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen</directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<directivesynopsis>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<name>SSLCipherSuite</name>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<description>Cipher Suite available for negotiation in SSL

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenhandshake</description>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<syntax>SSLCipherSuite <em>cipher-spec</em></syntax>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<default>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</default>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<contextlist><context>server config</context>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<context>virtual host</context>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<context>directory</context>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<context>.htaccess</context></contextlist>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<override>AuthConfig</override>

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainen<usage>

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainen<p>

a022088674a5ae72ed29ae001834cbad62a4f19fTimo SirainenThis complex directive uses a colon-separated <em>cipher-spec</em> string

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainenconsisting of OpenSSL cipher specifications to configure the Cipher Suite the

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainenclient is permitted to negotiate in the SSL handshake phase. Notice that this

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainendirective can be used both in per-server and per-directory context. In

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainenper-server context it applies to the standard SSL handshake when a connection

ae8817f05005f57bba32479a610b52d083e2b6ebTimo Sirainenis established. In per-directory context it forces a SSL renegotation with the

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainenreconfigured Cipher Suite after the HTTP request was read but before the HTTP

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenresponse is sent.</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenAn SSL cipher specification in <em>cipher-spec</em> is composed of 4 major

437b1d7e0a91ed93ff66a9056d0aac16ae23603cTimo Sirainenattributes plus a few extra minor ones:</p>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<ul>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li><em>Key Exchange Algorithm</em>:<br />

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen RSA or Diffie-Hellman variants.

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<li><em>Authentication Algorithm</em>:<br />

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen RSA, Diffie-Hellman, DSS or none.

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<li><em>Cipher/Encryption Algorithm</em>:<br />

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen DES, Triple-DES, RC4, RC2, IDEA or none.

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<li><em>MAC Digest Algorithm</em>:<br />

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen MD5, SHA or SHA1.

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</li>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen</ul>

6e07b4251bf6a3cf34019c351a32a65c08392e58Timo Sirainen<p>An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainencipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use,

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenone can either specify all the Ciphers, one at a time, or use aliases to

d67c6dc68cdb90b53434a25ead1590650e4d84e7Timo Sirainenspecify the preference and order for the ciphers (see <a href="#table1">Table

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainen1</a>).</p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<table border="1">

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<columnspec><column width=".5"/><column width=".5"/></columnspec>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><th><a name="table1">Tag</a></th> <th>Description</th></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>kRSA</code></td> <td>RSA key exchange</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td colspan="2"><em>Authentication Algorithm:</em></td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>aNULL</code></td> <td>No authentication</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>aRSA</code></td> <td>RSA authentication</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>aDSS</code></td> <td>DSS authentication</td> </tr>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<tr><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>eNULL</code></td> <td>No encoding</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>DES</code></td> <td>DES encoding</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>RC4</code></td> <td>RC4 encoding</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>RC2</code></td> <td>RC2 encoding</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>MD5</code></td> <td>MD5 hash function</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SHA</code></td> <td>SHA hash function</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td colspan="2"><em>Aliases:</em></td></tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>EXP</code></td> <td>all export ciphers</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen<tr><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr>

80fc743146da5130de34174cdaad2576f103723fTimo Sirainen</table>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<p>

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenNow where this becomes interesting is that these can be put together

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainento specify the order and ciphers you wish to use. To speed this up

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainenthere are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM,

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenHIGH</code>) for certain groups of ciphers. These tags can be joined

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainentogether with prefixes to form the <em>cipher-spec</em>. Available

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainenprefixes are:</p>

aa38d1a0945f0bc13a225d043f53fad2eec666b1Timo Sirainen<ul>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<li>none: add cipher to list</li>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>+</code>: add ciphers to list and pull them to current location in list</li>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>-</code>: remove cipher from list (can be added later again)</li>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<li><code>!</code>: kill cipher from list completely (can <strong>not</strong> be added later again)</li>

db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen</ul>

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen<p>A simpler way to look at all of this is to use the ``<code>openssl ciphers

2a6af811ea3de3cf9e2f15e446674dd21b0705f3Timo Sirainen-v</code>'' command which provides a nice way to successively create the

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainencorrect <em>cipher-spec</em> string. The default <em>cipher-spec</em> string

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainenis ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainenmeans the following: first, remove from consideration any ciphers that do not

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainenauthenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainenuse ciphers using RC4 and RSA. Next include the high, medium and then the low

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainensecurity ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainenend of the list.</p>

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainen<example>

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainen<pre>

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainen$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo SirainenNULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo SirainenNULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo SirainenEDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1

4d5d16ff85dacf56ddd70f76e0ccdb12b9d314d0Timo Sirainen... ... ... ... ...

80fc743146da5130de34174cdaad2576f103723fTimo SirainenEXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export

137c1851d63c6575ebab35d261380423c4cf2b47Timo SirainenEXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export

80fc743146da5130de34174cdaad2576f103723fTimo SirainenEXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export

0f66f12eb4cdbf47670975044c88d8f388bf92dfTimo Sirainen</pre>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen</example>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<p>The complete list of particular RSA &amp; DH ciphers for SSL is given in <a

d67c6dc68cdb90b53434a25ead1590650e4d84e7Timo Sirainenhref="#table2">Table 2</a>.</p>

0f66f12eb4cdbf47670975044c88d8f388bf92dfTimo Sirainen<example><title>Example</title>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo SirainenSSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen</example>

87ca2e468841829b44c09d618ac02f61a30b7a49Timo Sirainen<table border="1">

87ca2e468841829b44c09d618ac02f61a30b7a49Timo Sirainen<columnspec><column width=".3"/><column width=".1"/><column width=".13"/>

87ca2e468841829b44c09d618ac02f61a30b7a49Timo Sirainen<column width=".1"/><column width=".13"/><column width=".1"/>

f0df86d62853dc11fc76c4111e614ad3a7b5262bTimo Sirainen<column width=".13"/></columnspec>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><th><a name="table2">Cipher-Tag</a></th> <th>Protocol</th> <th>Key Ex.</th> <th>Auth.</th> <th>Enc.</th> <th>MAC</th> <th>Type</th> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td colspan="7"><em>RSA Ciphers:</em></td></tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr>

137c1851d63c6575ebab35d261380423c4cf2b47Timo Sirainen<tr><td><code>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</td> <td></td> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td></td> </tr>

d48a2f3288eba53dd10d9d8029ec583d78a977e0Timo Sirainen<tr><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td></td> </tr>

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainen<tr><td><code>EXP-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainen<tr><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr>

7d9954a0609f942dada5ebf98031f1f1b94c5f35Timo Sirainen<tr><td><code>EXP-RC4-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr>

a022088674a5ae72ed29ae001834cbad62a4f19fTimo Sirainen<tr><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr>

db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen<tr><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr>

db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen<tr><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EXP-EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EXP-EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>DSS</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EXP-ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<tr><td><code>EXP-ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen</table>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen</usage>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen</directivesynopsis>

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen

b529a94ab17fe69cdcfab08d7030266cb2a564e4Timo Sirainen<directivesynopsis>

<name>SSLCertificateFile</name>

<description>Server PEM-encoded X.509 Certificate file</description>

<syntax>SSLCertificateFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive points to the PEM-encoded Certificate file for the server and

optionally also to the corresponding RSA or DSA Private Key file for it

(contained in the same file). If the contained Private Key is encrypted the

Pass Phrase dialog is forced at startup time. This directive can be used up to

two times (referencing different filenames) when both a RSA and a DSA based

server certificate is used in parallel.</p>

<example><title>Example</title>

SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCertificateKeyFile</name>

<description>Server PEM-encoded Private Key file</description>

<syntax>SSLCertificateKeyFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

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

<directive>SSLCertificateFile</directive>, use this additional directive to

point to the file with the stand-alone Private Key. When

<directive>SSLCertificateFile</directive> is used and the file

contains both the Certificate and the Private Key this directive need

not be used. But we strongly discourage this practice. Instead we

recommend you to separate the Certificate and the Private Key. If the

contained Private Key is encrypted, the Pass Phrase dialog is forced

at startup time. This directive can be used up to two times

(referencing different filenames) when both a RSA and a DSA based

private key is used in parallel.</p>

<example><title>Example</title>

SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCertificateChainFile</name>

<description>File of PEM-encoded Server CA Certificates</description>

<syntax>SSLCertificateChainFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive sets the optional <em>all-in-one</em> file where you can

assemble the certificates of Certification Authorities (CA) which form the

certificate chain of the server certificate. This starts with the issuing CA

certificate of of the server certificate and can range up to the root CA

certificate. Such a file is simply the concatenation of the various

PEM-encoded CA Certificate files, usually in certificate chain order.</p>

<p>

This should be used alternatively and/or additionally to <directive

module="mod_ssl">SSLCACertificatePath</directive> for explicitly

constructing the server certificate chain which is sent to the browser

in addition to the server certificate. It is especially useful to

avoid conflicts with CA certificates when using client

authentication. Because although placing a CA certificate of the

server certificate chain into <directive

module="mod_ssl">SSLCACertificatePath</directive> has the same effect

for the certificate chain construction, it has the side-effect that

client certificates issued by this same CA certificate are also

accepted on client authentication. That's usually not one expect.</p>

<p>

But be careful: Providing the certificate chain works only if you are using a

<em>single</em> (either RSA <em>or</em> DSA) based server certificate. If you are

using a coupled RSA+DSA certificate pair, this will work only if actually both

certificates use the <em>same</em> certificate chain. Else the browsers will be

confused in this situation.</p>

<example><title>Example</title>

SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCACertificatePath</name>

<description>Directory of PEM-encoded CA Certificates for

Client Auth</description>

<syntax>SSLCACertificatePath <em>directory-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive sets the directory where you keep the Certificates of

Certification Authorities (CAs) whose clients you deal with. These are used to

verify the client certificate on Client Authentication.</p>

<p>

The files in this directory have to be PEM-encoded and are accessed through

hash filenames. So usually you can't just place the Certificate files

there: you also have to create symbolic links named

<em>hash-value</em><code>.N</code>. And you should always make sure this directory

contains the appropriate symbolic links. Use the <code>Makefile</code> which

comes with mod_ssl to accomplish this task.</p>

<example><title>Example</title>

SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCACertificateFile</name>

<description>File of concatenated PEM-encoded CA Certificates

for Client Auth</description>

<syntax>SSLCACertificateFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive sets the <em>all-in-one</em> file where you can assemble the

Certificates of Certification Authorities (CA) whose <em>clients</em> you deal

with. These are used for 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

<directive module="mod_ssl">SSLCACertificatePath</directive>.</p>

<example><title>Example</title>

SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCADNRequestFile</name>

<description>File of concatenated PEM-encoded CA Certificates

for defining acceptable CA names</description>

<syntax>SSLCADNRequestFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>When a client certificate is requested by mod_ssl, a list of

<em>acceptable Certificate Authority names</em> is sent to the client

in the SSL handshake. These CA names can be used by the client to

select an appropriate client certificate out of those it has

available.</p>

<p>If neither of the directives <directive

module="mod_ssl">SSLCADNRequestPath</directive> or <directive

module="mod_ssl">SSLCADNRequestFile</directive> are given, then the

set of acceptable CA names sent to the client is the names of all the

CA certificates given by the <directive

module="mod_ssl">SSLCACertificateFile</directive> and <directive

module="mod_ssl">SSLCACertificatePath</directive> directives; in other

words, the names of the CAs which will actually be used to verify the

client certificate.</p>

<p>In some circumstances, it is useful to be able to send a set of

acceptable CA names which differs from the actual CAs used to verify

the client certificate - for example, if the client certificates are

signed by intermediate CAs. In such cases, <directive

module="mod_ssl">SSLCADNRequestPath</directive> and/or <directive

module="mod_ssl">SSLCADNRequestFile</directive> can be used; the

acceptable CA names are then taken from the complete set of

certificates in the directory and/or file specified by this pair of

directives.</p>

<p><directive module="mod_ssl">SSLCADNRequestFile</directive> must

specify an <em>all-in-one</em> file containing a concatenation of

PEM-encoded CA certificates.</p>

<example><title>Example</title>

SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCADNRequestPath</name>

<description>Directory of PEM-encoded CA Certificates for

defining acceptable CA names</description>

<syntax>SSLCADNRequestPath <em>directory-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>This optional directive can be used to specify the set of

<em>acceptable CA names</em> which will be sent to the client when a

client certificate is requested. See the <directive

module="mod_ssl">SSLCADNRequestFile</directive> directive for more

details.</p>

<p>The files in this directory have to be PEM-encoded and are accessed

through hash filenames. So usually you can't just place the

Certificate files there: you also have to create symbolic links named

<em>hash-value</em><code>.N</code>. And you should always make sure

this directory contains the appropriate symbolic links. Use the

<code>Makefile</code> which comes with mod_ssl to accomplish this

task.</p>

<example><title>Example</title>

SSLCADNRequestPath /usr/local/apache2/conf/ca-names.crt/

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCARevocationPath</name>

<description>Directory of PEM-encoded CA CRLs for

Client Auth</description>

<syntax>SSLCARevocationPath <em>directory-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive sets the directory where you keep the Certificate Revocation

Lists (CRL) of Certification Authorities (CAs) whose clients you deal with.

These are used to revoke the client certificate on Client Authentication.</p>

<p>

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 CRL files there.

Additionally you have to create symbolic links named

<em>hash-value</em><code>.rN</code>. And you should always make sure this directory

contains the appropriate symbolic links. Use the <code>Makefile</code> which

comes with <module>mod_ssl</module> to accomplish this task.</p>

<example><title>Example</title>

SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLCARevocationFile</name>

<description>File of concatenated PEM-encoded CA CRLs for

Client Auth</description>

<syntax>SSLCARevocationFile <em>file-path</em></syntax>

<contextlist><context>server config</context>

<context>virtual host</context></contextlist>

<usage>

<p>

This directive sets the <em>all-in-one</em> file where you can

assemble the Certificate Revocation Lists (CRL) of Certification

Authorities (CA) whose <em>clients</em> you deal with. These are used

for Client Authentication. Such a file is simply the concatenation of

the various PEM-encoded CRL files, in order of preference. This can be

used alternatively and/or additionally to <directive

module="mod_ssl">SSLCARevocationPath</directive>.</p>

<example><title>Example</title>

SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLVerifyClient</name>

<description>Type of Client Certificate verification</description>

<syntax>SSLVerifyClient <em>level</em></syntax>

<default>SSLVerifyClient none</default>

<contextlist><context>server config</context>

<context>virtual host</context>

<context>directory</context>

<context>.htaccess</context></contextlist>

<override>AuthConfig</override>

<usage>

<p>

This directive sets the Certificate verification level for the Client

Authentication. Notice that this directive can be used both in per-server and

per-directory context. In per-server context it applies to the client

authentication process used in the standard SSL handshake when a connection is

established. In per-directory context it forces a SSL renegotation with the

reconfigured client verification level after the HTTP request was read but

before the HTTP response is sent.</p>

<p>

The following levels are available for <em>level</em>:</p>

<ul>

<li><strong>none</strong>:

no client Certificate is required at all</li>

<li><strong>optional</strong>:

the client <em>may</em> present a valid Certificate</li>

<li><strong>require</strong>:

the client <em>has to</em> present a valid Certificate</li>

<li><strong>optional_no_ca</strong>:

the client may present a valid Certificate<br />

but it need not to be (successfully) verifiable.</li>

</ul>

<p>In practice only levels <strong>none</strong> and

<strong>require</strong> are really interesting, because level

<strong>optional</strong> doesn't work with all browsers and level

<strong>optional_no_ca</strong> is actually against the idea of

authentication (but can be used to establish SSL test pages, etc.)</p>

<example><title>Example</title>

SSLVerifyClient require

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLVerifyDepth</name>

<description>Maximum depth of CA Certificates in Client

Certificate verification</description>

<syntax>SSLVerifyDepth <em>number</em></syntax>

<default>SSLVerifyDepth 1</default>

<contextlist><context>server config</context>

<context>virtual host</context>

<context>directory</context>

<context>.htaccess</context></contextlist>

<override>AuthConfig</override>

<usage>

<p>

This directive sets how deeply mod_ssl should verify before deciding that the

clients don't have a valid certificate. Notice that this directive can be

used both in per-server and per-directory context. In per-server context it

applies to the client authentication process used in the standard SSL

handshake when a connection is established. In per-directory context it forces

a SSL renegotation with the reconfigured client verification depth after the

HTTP request was read but before the HTTP response is sent.</p>

<p>

The depth actually is the maximum number of intermediate certificate issuers,

i.e. the number of CA certificates which are max allowed to be followed while

verifying the client certificate. A depth of 0 means that self-signed client

certificates are accepted only, the default depth of 1 means the client

certificate can be self-signed or has to be signed by a CA which is directly

known to the server (i.e. the CA's certificate is under

<directive module="mod_ssl">SSLCACertificatePath</directive>), etc.</p>

<example><title>Example</title>

SSLVerifyDepth 10

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLOptions</name>

<description>Configure various SSL engine run-time options</description>

<syntax>SSLOptions [+|-]<em>option</em> ...</syntax>

<contextlist><context>server config</context>

<context>virtual host</context>

<context>directory</context>

<context>.htaccess</context></contextlist>

<override>Options</override>

<usage>

<p>

This directive can be used to control various run-time options on a

per-directory basis. Normally, if multiple <code>SSLOptions</code>

could apply to a directory, then the most specific one is taken

completely; the options are not merged. However if <em>all</em> the

options on the <code>SSLOptions</code> directive are preceded by a

plus (<code>+</code>) or minus (<code>-</code>) symbol, the options

are merged. Any options preceded by a <code>+</code> are added to the

options currently in force, and any options preceded by a

<code>-</code> are removed from the options currently in force.</p>

<p>

The available <em>option</em>s are:</p>

<ul>

<li><code>StdEnvVars</code>

<p>

When this option is enabled, the standard set of SSL related CGI/SSI

environment variables are created. This per default is disabled for

performance reasons, because the information extraction step is a

rather expensive operation. So one usually enables this option for

CGI and SSI requests only.</p>

</li>

<li><code>CompatEnvVars</code>

<p>

When this option is enabled, additional CGI/SSI environment variables are

created for backward compatibility to other Apache SSL solutions. Look in

the <a href="/ssl/ssl_compat.html">Compatibility</a> chapter for details

on the particular variables generated.</p>

</li>

<li><code>ExportCertData</code>

<p>

When this option is enabled, additional CGI/SSI environment variables are

created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and

<code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em> (with <em>n</em> = 0,1,2,..).

These contain the PEM-encoded X.509 Certificates of server and client for

the current HTTPS connection and can be used by CGI scripts for deeper

Certificate checking. Additionally all other certificates of the client

certificate chain are provided, too. This bloats up the environment a

little bit which is why you have to use this option to enable it on

demand.</p>

</li>

<li><code>FakeBasicAuth</code>

<p>

When this option is enabled, the Subject Distinguished Name (DN) of the

Client X509 Certificate is translated 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 OpenSSL's

<code>openssl x509</code> command: <code>openssl x509 -noout -subject -in

</code><em>certificate</em><code>.crt</code>). Note that no password is

obtained from the user. Every entry in the user file needs this password:

``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the

word `<code>password</code>''. Those who live under MD5-based encryption

(for instance under FreeBSD or BSD/OS, etc.) should use the following MD5

hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.</p>

</li>

<li><code>StrictRequire</code>

<p>

This <em>forces</em> forbidden access when <code>SSLRequireSSL</code> or

<code>SSLRequire</code> successfully decided that access should be

forbidden. Usually the default is that in the case where a ``<code>Satisfy

any</code>'' directive is used, and other access restrictions are passed,

denial of access due to <code>SSLRequireSSL</code> or

<code>SSLRequire</code> is overridden (because that's how the Apache

<code>Satisfy</code> mechanism should work.) But for strict access restriction

you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in

combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an

additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has

decided to deny access.</p>

</li>

<li><code>OptRenegotiate</code>

<p>

This enables optimized SSL connection renegotiation handling when SSL

directives are used in per-directory context. By default a strict

scheme is enabled where <em>every</em> per-directory reconfiguration of

SSL parameters causes a <em>full</em> SSL renegotiation handshake. When this

option is used mod_ssl tries to avoid unnecessary handshakes by doing more

granular (but still safe) parameter checks. Nevertheless these granular

checks sometimes maybe not what the user expects, so enable this on a

per-directory basis only, please.</p>

</li>

</ul>

<example><title>Example</title>

SSLOptions +FakeBasicAuth -StrictRequire<br />

&lt;Files ~ "\.(cgi|shtml)$"&gt;<br />

SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData<br />

&lt;Files&gt;

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLRequireSSL</name>

<description>Deny access when SSL is not used for the

HTTP request</description>

<syntax>SSLRequireSSL</syntax>

<contextlist><context>directory</context>

<context>.htaccess</context></contextlist>

<override>AuthConfig</override>

<usage>

<p><!-- XXX: I think the syntax is wrong -->

This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for

the current connection. This is 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.</p>

<example><title>Example</title>

SSLRequireSSL

</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SSLRequire</name>

<description>Allow access only when an arbitrarily complex

boolean expression is true</description>

<syntax>SSLRequire <em>expression</em></syntax>

<contextlist><context>directory</context>

<context>.htaccess</context></contextlist>

<override>AuthConfig</override>

<usage>

<p>

This directive specifies a general access requirement which has to be

fulfilled in order to allow access. It is a very powerful directive because the

requirement specification is an arbitrarily complex boolean expression

containing any number of access checks.</p>

<note type="warning">

<p>The implementation of <code>SSLRequire</code> is not thread safe.

Using <code>SSLRequire</code> inside <code>.htaccess</code> files

on a threaded <a href="/mpm.html">MPM</a> may cause random crashes.

</p>

</note>

<p>

The <em>expression</em> must match the following syntax (given as a BNF

grammar notation):</p>

<blockquote>

<pre>

expr ::= "<strong>true</strong>" | "<strong>false</strong>"

| "<strong>!</strong>" expr

| expr "<strong>&amp;&amp;</strong>" expr

| expr "<strong>||</strong>" expr

| "<strong>(</strong>" expr "<strong>)</strong>"

| comp

comp ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word

| word "<strong>!=</strong>" word | word "<strong>ne</strong>" word

| word "<strong>&lt;</strong>" word | word "<strong>lt</strong>" word

| word "<strong>&lt;=</strong>" word | word "<strong>le</strong>" word

| word "<strong>&gt;</strong>" word | word "<strong>gt</strong>" word

| word "<strong>&gt;=</strong>" word | word "<strong>ge</strong>" word

| word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>"

| word "<strong>in</strong>" "<strong>PeerExtList(</strong>" word "<strong>)</strong>"

| word "<strong>=~</strong>" regex

| word "<strong>!~</strong>" regex

wordlist ::= word

| wordlist "<strong>,</strong>" word

word ::= digit

| cstring

| variable

| function

digit ::= [0-9]+

cstring ::= "..."

variable ::= "<strong>%{</strong>" varname "<strong>}</strong>"