diff options
| author | Joshua Slive <slive@apache.org> | 2001-11-06 17:06:13 +0100 |
|---|---|---|
| committer | Joshua Slive <slive@apache.org> | 2001-11-06 17:06:13 +0100 |
| commit | 1d1879992424deea80e44444ac63b56b261605fd (patch) | |
| tree | ac8ff252c13706a22108cf495bec7d1b5dc6ca97 /docs/manual/mod/mod_ssl.html | |
| parent | These comments are pretty much useless now AFAICT. (diff) | |
| download | apache2-1d1879992424deea80e44444ac63b56b261605fd.tar.xz apache2-1d1879992424deea80e44444ac63b56b261605fd.zip | |
I am just moving the reference chapter of the ssl docs into the modules directory
to be the baseline. The next commit will put it in the correct format.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91764 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs/manual/mod/mod_ssl.html')
| -rw-r--r-- | docs/manual/mod/mod_ssl.html | 2539 |
1 files changed, 2539 insertions, 0 deletions
diff --git a/docs/manual/mod/mod_ssl.html b/docs/manual/mod/mod_ssl.html new file mode 100644 index 0000000000..f7ecb633ff --- /dev/null +++ b/docs/manual/mod/mod_ssl.html @@ -0,0 +1,2539 @@ +<html> +<head> +<title>mod_ssl: Reference</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-3.gif" alt="3" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-ref.gif" alt="Reference" width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="150" summary=""> +<tr> +<td> +<em> +``Try to understand everything, +but believe nothing!'' +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Unknown +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_reference.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> +his chapter provides a reference to all configuration directives and +additional user visible features mod_ssl provides. It's intended as the +official resource when you want to know how a particilar mod_ssl functionality +is actually configured or activated. Each directive is documented similar to +the way standard Apache directives are documented in the official Apache +documentation set, i.e. for each directive especially the syntax, default and +context where applicable is given. +<p> +Notice that there are three major classes of directives which are used by +mod_ssl: First <em>Global Directives</em> (i.e. directives with context +``server config''), which can occur inside the server config files but only +outside of any sectioning commands like <VirtualHost>. Second +<em>Per-Server Directives</em> (i.e. those with context ``server config, +virtual host''), which can occur inside the server config files both outside +(for the main/default server) and inside <VirtualHost> sections. +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> +<a href="#ToC1"><strong>Configuration Directives</strong></a><br> + <a href="#ToC2"><strong>SSLPassPhraseDialog</strong></a><br> + <a href="#ToC3"><strong>SSLMutex</strong></a><br> + <a href="#ToC4"><strong>SSLRandomSeed</strong></a><br> + <a href="#ToC5"><strong>SSLSessionCache</strong></a><br> + <a href="#ToC6"><strong>SSLSessionCacheTimeout</strong></a><br> + <a href="#ToC7"><strong>SSLEngine</strong></a><br> + <a href="#ToC8"><strong>SSLProtocol</strong></a><br> + <a href="#ToC9"><strong>SSLCipherSuite</strong></a><br> + <a href="#ToC10"><strong>SSLCertificateFile</strong></a><br> + <a href="#ToC11"><strong>SSLCertificateKeyFile</strong></a><br> + <a href="#ToC12"><strong>SSLCertificateChainFile</strong></a><br> + <a href="#ToC13"><strong>SSLCACertificatePath</strong></a><br> + <a href="#ToC14"><strong>SSLCACertificateFile</strong></a><br> + <a href="#ToC15"><strong>SSLCARevocationPath</strong></a><br> + <a href="#ToC16"><strong>SSLCARevocationFile</strong></a><br> + <a href="#ToC17"><strong>SSLVerifyClient</strong></a><br> + <a href="#ToC18"><strong>SSLVerifyDepth</strong></a><br> + <a href="#ToC19"><strong>SSLLog</strong></a><br> + <a href="#ToC20"><strong>SSLLogLevel</strong></a><br> + <a href="#ToC21"><strong>SSLOptions</strong></a><br> + <a href="#ToC22"><strong>SSLRequireSSL</strong></a><br> + <a href="#ToC23"><strong>SSLRequire</strong></a><br> +<a href="#ToC24"><strong>Additional Features</strong></a><br> + <a href="#ToC25"><strong>Environment Variables</strong></a><br> + <a href="#ToC26"><strong>Custom Log Formats</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<p> +And third <em>Per-Directory Directives</em> (i.e. those with context ``server +config, virtual host, directory, .htaccess''), which can pretty much occur +everywhere. Especially both inside the server config files and the +per-directory <code>.htaccess</code> files. The three classes are subsets of +each other, i.e. directives from the per-directory class can also be used in +the per-server and global context, and directives from the per-server class +can also be used the in the global context. +<p> +Additional directives and environment variables provided by mod_ssl (via +on-the-fly mapping) for backward compatiblity to other Apache SSL solutions +are documented in the <a href="ssl_compat.html">Compatibility</a> chapter. +<h1><a name="ToC1">Configuration Directives</a></h1> +The most visible and error-prone things of mod_ssl are its configuration +directives. So we document them in great detail here to assist you in setting +up the best possible configuration of your SSL-aware webserver. +<!-- SSLPassPhraseDialog --------------------------------------------> +<p> +<br> +<a name="SSLPassPhraseDialog"></a> +<h2><a name="ToC2">SSLPassPhraseDialog</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLPassPhraseDialog</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of pass phrase dialog for encrypted private keys</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLPassPhraseDialog</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLPassPhraseDialog builtin</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +When Apache starts up it has to read the various Certificate (see <a +href="#SSLCertificateFile">SSLCertificateFile</a>) and Private Key (see <a +href="#SSLCertificateKeyFile">SSLCertificateKeyFile</a>) files of the +SSL-enabled virtual servers. Because for security reasons the Private Key +files are usually encrypted, mod_ssl needs to query the administrator for a +Pass Phrase in order to decrypt those files. This query can be done in two ways +which can be configured by <em>type</em>: +<ul> +<li><code>builtin</code> + <p> + This is the default where an interactive terminal dialog occurs at startup + time just before Apache detaches from the terminal. Here the administrator + has to manually enter the Pass Phrase for each encrypted Private Key file. + Because a lot of SSL-enabled virtual hosts can be configured, the + following reuse-scheme is used to minimize the dialog: When a Private Key + file is encrypted, all known Pass Phrases (at the beginning there are + none, of course) are tried. If one of those known Pass Phrases succeeds no + dialog pops up for this particular Private Key file. If none succeeded, + another Pass Phrase is queried on the terminal and remembered for the next + round (where it perhaps can be reused). + <p> + This scheme allows mod_ssl to be maximally flexible (because for N encrypted + Private Key files you <em>can</em> use N different Pass Phrases - but then + you have to enter all of them, of course) while minimizing the terminal + dialog (i.e. when you use a single Pass Phrase for all N Private Key files + this Pass Phrase is queried only once). +<p> +<li><code>exec:/path/to/program</code> + <p> + Here an external program is configured which is called at startup for each + encrypted Private Key file. It is called with two arguments (the first is + of the form ``<code>servername:portnumber</code>'', the second is either + ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which + server and algorithm it has to print the corresponding Pass Phrase to + <code>stdout</code>. The intent is that this external program first runs + security checks to make sure that the system is not compromised by an + attacker, and only when these checks were passed successfully it provides + the Pass Phrase. + <p> + Both these security checks, and the way the Pass Phrase is determined, can + be as complex as you like. Mod_ssl just defines the interface: an + executable program which provides the Pass Phrase on <code>stdout</code>. + Nothing more or less! So, if you're really paranoid about security, here + is your interface. Anything else has to be left as an exercise to the + administrator, because local security requirements are so different. + <p> + The reuse-algorithm above is used here, too. In other words: The external + program is called only once per unique Pass Phrase. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter +</pre> +</blockquote> +<!-- SSLMutex -------------------------------------------------------> +<p> +<br> +<a name="SSLMutex"></a> +<h2><a name="ToC3">SSLMutex</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLMutex</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Semaphore for internal mutual exclusion of operations</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLMutex</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLMutex none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex. +<p> +The following Mutex <em>types</em> are available: +<ul> +<li><code>none</code> + <p> + This is the default where no Mutex is used at all. Use it at your own + risk. But because currently the Mutex is mainly used for synchronizing + write access to the SSL Session Cache you can live without it as long + as you accept a sometimes garbled Session Cache. So it's not recommended + to leave this the default. Instead configure a real Mutex. +<p> +<li><code>file:/path/to/mutex</code> + <p> + This is the portable and (under Unix) always provided Mutex variant where + a physical (lock-)file is used as the Mutex. Always use a local disk + filesystem for <code>/path/to/mutex</code> and never a file residing on a + NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the + Apache parent process is automatically appended to + <code>/path/to/mutex</code> to make it unique, so you don't have to worry + about conflicts yourself. Notice that this type of mutex is not available + under the Win32 environment. There you <i>have</i> to use the semaphore + mutex. +<p> +<li><code>sem</code> + <p> + This is the most elegant but also most non-portable Mutex variant where a + SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used + when possible. It is only available when the underlying platform + supports it. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLMutex file:/usr/local/apache/logs/ssl_mutex +</pre> +</blockquote> +<!-- SSLRandomSeed --------------------------------------------------> +<p> +<br> +<a name="SSLRandomSeed"></a> +<h2><a name="ToC4">SSLRandomSeed</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRandomSeed</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Pseudo Random Number Generator (PRNG) seeding source</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>none</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in OpenSSL at startup time (<em>context</em> is +<code>startup</code>) and/or just before a new SSL connection is established +(<em>context</em> is <code>connect</code>). This directive can only be used +in the global server context because the PRNG is a global facility. +<p> +The following <em>source</em> variants are available: +<ul> +<li><code>builtin</code> + <p> This is the always available builtin seeding source. It's usage + consumes minimum CPU cycles under runtime and hence can be always used + without drawbacks. The source used for seeding the PRNG contains of the + current time, the current process id and (when applicable) a randomly + choosen 1KB extract of the inter-process scoreboard structure of Apache. + The drawback is that this is not really a strong source and at startup + time (where the scoreboard is still not available) this source just + produces a few bytes of entropy. So you should always, at least for the + startup, use an additional seeding source. +<p> +<li><code>file:/path/to/source</code> + <p> + This variant uses an external file <code>/path/to/source</code> as the + source for seeding the PRNG. When <em>bytes</em> is specified, only the + first <em>bytes</em> number of bytes of the file form the entropy (and + <em>bytes</em> is given to <code>/path/to/source</code> as the first + argument). When <em>bytes</em> is not specified the whole file forms the + entropy (and <code>0</code> is given to <code>/path/to/source</code> as + the first argument). Use this especially at startup time, for instance + with an available <code>/dev/random</code> and/or + <code>/dev/urandom</code> devices (which usually exist on modern Unix + derivates like FreeBSD and Linux). + <p> + <em>But be careful</em>: Usually <code>/dev/random</code> provides only as + much entropy data as it actually has, i.e. when you request 512 bytes of + entropy, but the device currently has only 100 bytes available two things + can happen: On some platforms you receive only the 100 bytes while on + other platforms the read blocks until enough bytes are available (which + can take a long time). Here using an existing <code>/dev/urandom</code> is + better, because it never blocks and actually gives the amount of requested + data. The drawback is just that the quality of the received data may not + be the best. + <p> + On some platforms like FreeBSD one can even control how the entropy is + actually generated, i.e. by which system interrupts. More details one can + find under <i>rndcontrol(8)</i> on those platforms. Alternatively, when + your system lacks such a random device, you can use tool + like <a href="http://www.lothar.com/tech/crypto/">EGD</a> + (Entropy Gathering Daemon) and run it's client program with the + <code>exec:/path/to/program/</code> variant (see below) or use + <code>egd:/path/to/egd-socket</code> (see below). +<p> +<li><code>exec:/path/to/program</code> + <p> + This variant uses an external executable <code>/path/to/program</code> as + the source for seeding the PRNG. When <em>bytes</em> is specified, only the + first <em>bytes</em> number of bytes of its <code>stdout</code> contents + form the entropy. When <em>bytes</em> is not specified, the entirety of + the data produced on <code>stdout</code> form the entropy. Use this only + at startup time when you need a very strong seeding with the help of an + external program (for instance as in the example above with the + <code>truerand</code> utility you can find in the mod_ssl distribution + which is based on the AT&T <em>truerand</em> library). Using this in + the connection context slows down the server too dramatically, of course. + So usually you should avoid using external programs in that context. +<p> +<li><code>egd:/path/to/egd-socket</code> (Unix only) + <p> + This variant uses the Unix domain socket of the + external Entropy Gathering Daemon (EGD) (see <a + href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech + /crypto/</a>) to seed the PRNG. Use this if no random device exists + on your platform. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLRandomSeed startup builtin +SSLRandomSeed startup file:/dev/random +SSLRandomSeed startup file:/dev/urandom 1024 +SSLRandomSeed startup exec:/usr/local/bin/truerand 16 +SSLRandomSeed connect builtin +SSLRandomSeed connect file:/dev/random +SSLRandomSeed connect file:/dev/urandom 1024 +</pre> +</blockquote> +<!-- SSLSessionCache ------------------------------------------------> +<p> +<br> +<a name="SSLSessionCache"></a> +<h2><a name="ToC5">SSLSessionCache</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCache</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of the global/inter-process SSL Session Cache</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCache</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCache none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +<em>different</em> pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes. +<p> +The following two storage <em>type</em>s are currently supported: +<ul> +<li><code>none</code> + <p> + This is the default and just disables the global/inter-process Session + Cache. There is no drawback in functionality, but a noticeable speed + penalty can be observed. +<p> +<li><code>dbm:/path/to/datafile</code> + <p> + This makes use of a DBM hashfile on the local disk to synchronize the + local OpenSSL memory caches of the server processes. The slight increase + in I/O on the server results in a visible request speedup for your + clients, so this type of storage is generally recommended. +<p> +<li><code>shm:/path/to/datafile</code>[<code>(</code><i>size</i><code>)</code>] + <p> + This makes use of a high-performance hash table (approx. <i>size</i> bytes + in size) inside a shared memory segment in RAM (established via + <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory + caches of the server processes. This storage type is not available on all + platforms. See the mod_ssl <code>INSTALL</code> document for details on + how to build Apache+EAPI with shared memory support. +</ul> +<p> +Examples: +<blockquote> +<pre> +SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data +SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) +</pre> +</blockquote> +<!-- SSLSessionCacheTimeout -----------------------------------------> +<p> +<br> +<a name="SSLSessionCacheTimeout"></a> +<h2><a name="ToC6">SSLSessionCacheTimeout</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCacheTimeout</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Number of seconds before an SSL session expires in the Session Cache</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCacheTimeout</code> <em>seconds</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCacheTimeout 300</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life. +<p> +Example: +<blockquote> +<pre> +SSLSessionCacheTimeout 600 +</pre> +</blockquote> +<!-- SSLEngine ------------------------------------------------------> +<p> +<br> +<a name="SSLEngine"></a> +<h2><a name="ToC7">SSLEngine</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLEngine</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> SSL Engine Operation Switch</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLEngine</code> <em>on|off</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLEngine off</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive toggles the usage of the SSL/TLS Protocol Engine. This is +usually used inside a <VirtualHost> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is disabled +for both the main server and all configured virtual hosts. +<p> +Example: +<blockquote> +<pre> +<VirtualHost _default_:443> +SSLEngine on +... +</VirtualHost> +</pre> +</blockquote> +<!-- SSLProtocol ----------------------------------------------------> +<p> +<br> +<a name="SSLProtocol"></a> +<h2><a name="ToC8">SSLProtocol</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLProtocol</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure usable SSL protocol flavors</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLProtocol</code> [+-]<em>protocol</em> ...</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLProtocol all</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols. +<p> +The available (case-insensitive) <em>protocol</em>s are: +<ul> +<li><code>SSLv2</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the + original SSL protocol as designed by Netscape Corporation. +<p> +<li><code>SSLv3</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the + successor to SSLv2 and the currently (as of February 1999) de-facto + standardized SSL protocol from Netscape Corporation. It's supported by + almost all popular browsers. +<p> +<li><code>TLSv1</code> + <p> + This is the Transport Layer Security (TLS) protocol, version 1.0. It is the + successor to SSLv3 and currently (as of February 1999) still under + construction by the Internet Engineering Task Force (IETF). It's still + not supported by any popular browsers. +<p> +<li><code>All</code> + <p> + This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a + convinient way for enabling all protocols except one when used in + combination with the minus sign on a protocol as the example above shows. +</ul> +<p> +Example: +<blockquote> +<pre> +# enable SSLv3 and TLSv1, but not SSLv2 +SSLProtocol all -SSLv2 +</pre> +</blockquote> +<!-- SSLCipherSuite -------------------------------------------------> +<p> +<br> +<a name="SSLCipherSuite"></a> +<h2><a name="ToC9">SSLCipherSuite</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCipherSuite</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Cipher Suite available for negotiation in SSL handshake</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCipherSuite</code> <em>cipher-spec</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This complex directive uses a colon-separated <em>cipher-spec</em> string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent. +<p> +An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major +attributes plus a few extra minor ones: +<ul> +<li><em>Key Exchange Algorithm</em>:<br> + RSA or Diffie-Hellman variants. +<p> +<li><em>Authentication Algorithm</em>:<br> + RSA, Diffie-Hellman, DSS or none. +<p> +<li><em>Cipher/Encryption Algorithm</em>:<br> + DES, Triple-DES, RC4, RC2, IDEA or none. +<p> +<li><em>MAC Digest Algorithm</em>:<br> + MD5, SHA or SHA1. +</ul> +An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 +cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, +one can either specify all the Ciphers, one at a time, or use aliases to +specify the preference and order for the ciphers (see <a href="#table1">Table +1</a>). +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 1: OpenSSL Cipher Specification Tags</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><b>Tag</b></td> <td><b>Description</b></td> +<tr id="H"><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> +<tr id="D"><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> +<tr id="H"><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> +<tr id="D"><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> +<tr id="H"><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> +<tr id="H"><td colspan="2"><em>Authentication Algorithm:</em></td></tr> +<tr id="D"><td><code>aNULL</code></td> <td>No authentication</td></tr> +<tr id="H"><td><code>aRSA</code></td> <td>RSA authentication</td></tr> +<tr id="D"><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> +<tr id="H"><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> +<tr id="D"><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr></tr> +<tr id="H"><td><code>eNULL</code></td> <td>No encoding</td> </tr> +<tr id="D"><td><code>DES</code></td> <td>DES encoding</td> </tr> +<tr id="H"><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr> +<tr id="D"><td><code>RC4</code></td> <td>RC4 encoding</td> </tr> +<tr id="H"><td><code>RC2</code></td> <td>RC2 encoding</td> </tr> +<tr id="D"><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr> +<tr id="H"><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> +<tr id="D"><td><code>MD5</code></td> <td>MD5 hash function</td></tr> +<tr id="H"><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> +<tr id="D"><td><code>SHA</code></td> <td>SHA hash function</td> </tr> +<tr id="H"><td colspan="2"><em>Aliases:</em></td></tr> +<tr id="D"><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr> +<tr id="H"><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> +<tr id="D"><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> +<tr id="H"><td><code>EXP</code></td> <td>all export ciphers</td> </tr> +<tr id="D"><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> +<tr id="H"><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> +<tr id="D"><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> +<tr id="H"><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> +<tr id="D"><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> +<tr id="H"><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> +<tr id="D"><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> +<tr id="D"><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> +<tr id="D"><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +Now where this becomes interesting is that these can be put together +to specify the order and ciphers you wish to use. To speed this up +there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, +HIGH</code>) for certain groups of ciphers. These tags can be joined +together with prefixes to form the <em>cipher-spec</em>. Available +prefixes are: +<ul> +<li>none: add cipher to list +<li><code>+</code>: add ciphers to list and pull them to current location in list +<li><code>-</code>: remove cipher from list (can be added later again) +<li><code>!</code>: kill cipher from list completely (can <b>not</b> be added later again) +</ul> +A simpler way to look at all of this is to use the ``<code>openssl ciphers +-v</code>'' command which provides a nice way to successively create the +correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string +is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which +means the following: first, remove from consideration any ciphers that do not +authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, +use ciphers using RC4 and RSA. Next include the high, medium and then the low +security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the +end of the list. +<blockquote> +<pre> +$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP' +NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1 +NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5 +EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 +... ... ... ... ... +EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export +EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +</pre> +</blockquote> +The complete list of particular RSA & DH ciphers for SSL is given in <a +href="#table2">Table 2</a>. +<p> +Example: +<blockquote> +<pre> +SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW +</pre> +</blockquote> +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 2: Particular SSL Ciphers</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><b>Cipher-Tag</b></td> <td><b>Protocol</b></td> <td><b>Key Ex.</b></td> <td><b>Auth.</b></td> <td><b>Enc.</b></td> <td><b>MAC</b></td> <td><b>Type</b></td> </tr> +<tr id="H"><td colspan="7"><em>RSA Ciphers:</em></td></tr> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +<tr id="D"><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> +<tr id="H"><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> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<!-- SSLCertificateFile ---------------------------------------------> +<p> +<br> +<a name="SSLCertificateFile"></a> +<h2><a name="ToC10">SSLCertificateFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded X.509 Certificate file</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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: +<blockquote> +<pre> +SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt +</pre> +</blockquote> +<!-- SSLCertificateKeyFile ------------------------------------------> +<p> +<br> +<a name="SSLCertificateKeyFile"></a> +<h2><a name="ToC11">SSLCertificateKeyFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateKeyFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded Private Key file</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateKeyFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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 +<code>SSLCertificateFile</code>, use this additional directive to point to the +file with the stand-alone Private Key. When <code>SSLCertificateFile</code> +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: +<blockquote> +<pre> +SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +</pre> +</blockquote> +<!-- SSLCertificateChainFile ----------------------------------------> +<p> +<br> +<a name="SSLCertificateChainFile"></a> +<h2><a name="ToC12">SSLCertificateChainFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateChainFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of PEM-encoded Server CA Certificates</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateChainFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3.6 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +This should be used alternatively and/or additionally to <a +href="#SSLCACertificatePath">SSLCACertificatePath</a> 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 <a +href="#SSLCACertificatePath">SSLCACertificatePath</a> 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> +But be careful: Providing the certificate chain works only if you are using a +<i>single</i> (either RSA <i>or</i> DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the <i>same</i> certificate chain. Else the browsers will be +confused in this situation. +<p> +Example: +<blockquote> +<pre> +SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt +</pre> +</blockquote> +<!-- SSLCACertificatePath -------------------------------------------> +<p> +<br> +<a name="SSLCACertificatePath"></a> +<h2><a name="ToC13">SSLCACertificatePath</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificatePath</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA Certificates for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificatePath</code> <em>directory</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +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 +<i>hash-value</i><tt>.N</tt>. 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: +<blockquote> +<pre> +SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ +</pre> +</blockquote> +<!-- SSLCACertificateFile -------------------------------------------> +<p> +<br> +<a name="SSLCACertificateFile"></a> +<h2><a name="ToC14">SSLCACertificateFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificateFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA Certificates for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificateFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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 <a +href="#SSLCACertificatePath">SSLCACertificatePath</a>. +<p> +Example: +<blockquote> +<pre> +SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt +</pre> +</blockquote> +<!-- SSLCARevocationPath --------------------------------------------> +<p> +<br> +<a name="SSLCARevocationPath"></a> +<h2><a name="ToC15">SSLCARevocationPath</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationPath</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA CRLs for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationPath</code> <em>directory</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +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 +<i>hash-value</i><tt>.rN</tt>. 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: +<blockquote> +<pre> +SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ +</pre> +</blockquote> +<!-- SSLCARevocationFile --------------------------------------------> +<p> +<br> +<a name="SSLCARevocationFile"></a> +<h2><a name="ToC16">SSLCARevocationFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA CRLs for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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 <a href="#SSLCARevocationPath">SSLCARevocationPath</a>. +<p> +Example: +<blockquote> +<pre> +SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl +</pre> +</blockquote> +<!-- SSLVerifyClient -------------------------------------------------> +<p> +<br> +<a name="SSLVerifyClient"></a> +<h2><a name="ToC17">SSLVerifyClient</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyClient</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of Client Certificate verification</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyClient</code> <em>level</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyClient none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +The following levels are available for <em>level</em>: +<ul> +<li><strong>none</strong>: + no client Certificate is required at all +<li><strong>optional</strong>: + the client <em>may</em> present a valid Certificate +<li><strong>require</strong>: + the client <em>has to</em> present a valid Certificate +<li><strong>optional_no_ca</strong>: + the client may present a valid Certificate<br> + but it need not to be (successfully) verifiable. +</ul> +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: +<blockquote> +<pre> +SSLVerifyClient require +</pre> +</blockquote> +<!-- SSLVerifyDepth -------------------------------------------------> +<p> +<br> +<a name="SSLVerifyDepth"></a> +<h2><a name="ToC18">SSLVerifyDepth</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyDepth</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Maximum depth of CA Certificates in Client Certificate verification</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyDepth</code> <em>number</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyDepth 1</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +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 +<code>SSLCACertificatePath</code>), etc. +<p> +Example: +<blockquote> +<pre> +SSLVerifyDepth 10 +</pre> +</blockquote> +<!-- SSLLog ---------------------------------------------------------> +<p> +<br> +<a name="SSLLog"></a> +<h2><a name="ToC19">SSLLog</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLog</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Where to write the dedicated SSL engine logfile</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLog</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the name of the dedicated SSL protocol engine logfile. +Error type messages are additionally duplicated to the general Apache error +log file (directive <code>ErrorLog</code>). Put this somewhere where it cannot +be used for symlink attacks on a real server (i.e. somewhere where only root +can write). If the <em>filename</em> does not begin with a slash +('<code>/</code>') then it is assumed to be relative to the <em>Server +Root</em>. If <em>filename</em> begins with a bar ('<code>|</code>') then the +following string is assumed to be a path to an executable program to which a +reliable pipe can be established. The directive should occur only once per +virtual server config. +<p> +Example: +<blockquote> +<pre> +SSLLog /usr/local/apache/logs/ssl_engine_log +</pre> +</blockquote> +<!-- SSLLogLevel ----------------------------------------------------> +<p> +<br> +<a name="SSLLogLevel"></a> +<h2><a name="ToC20">SSLLogLevel</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLogLevel</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Logging level for the dedicated SSL engine logfile</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLogLevel</code> <em>level</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLLogLevel none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the verbosity degree of the dedicated SSL protocol engine +logfile. The <em>level</em> is one of the following (in ascending order where +higher levels include lower levels): +<ul> +<li><code>none</code><br> + no dedicated SSL logging is done, but messages of level + ``<code>error</code>'' are still written to the general Apache error + logfile. +<p> +<li><code>error</code><br> + log messages of error type only, i.e. messages which show fatal situations + (processing is stopped). Those messages are also duplicated to the + general Apache error logfile. +<p> +<li><code>warn</code><br> + log also warning messages, i.e. messages which show non-fatal problems + (processing is continued). +<p> +<li><code>info</code><br> + log also informational messages, i.e. messages which show major + processing steps. +<p> +<li><code>trace</code><br> + log also trace messages, i.e. messages which show minor processing steps. +<p> +<li><code>debug</code><br> + log also debugging messages, i.e. messages which show development and + low-level I/O information. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLLogLevel warn +</pre> +</blockquote> +<!-- SSLOptions -----------------------------------------------------> +<p> +<br> +<a name="SSLOptions"></a> +<h2><a name="ToC21">SSLOptions</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLOptions</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure various SSL engine run-time options</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLOptions</code> [+-]<em>option</em> ...</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<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> +The available <em>option</em>s are: +<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><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_compat.html">Compatibility</a> chapter for details + on the particular variables generated. +<p> +<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><i>n</i> (with <i>n</i> = 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><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><code>StrictRequire</code> + <p> + This <i>forces</i> 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 + <tt>Satisfy</tt> 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><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 <i>every</i> per-directory reconfiguration of + SSL parameters causes a <i>full</i> 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. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLOptions +FakeBasicAuth -StrictRequire +<Files ~ "\.(cgi|shtml)$"> + SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData +<Files> +</pre> +</blockquote> +<!-- SSLRequireSSL --------------------------------------------------> +<p> +<br> +<a name="SSLRequireSSL"></a> +<h2><a name="ToC22">SSLRequireSSL</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequireSSL</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Deny access when SSL is not used for the HTTP request</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequireSSL</code></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +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: +<blockquote> +<pre> +SSLRequireSSL +</pre> +</blockquote> +<!-- SSLRequire -----------------------------------------------------> +<p> +<br> +<a name="SSLRequire"></a> +<h2><a name="ToC23">SSLRequire</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequire</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Allow access only when an arbitrarily complex boolean expression is true</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequire</code> <em>expression</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks. +<p> +The <em>expression</em> must match the following syntax (given as a BNF +grammar notation): +<blockquote> +<pre> +expr ::= "<b>true</b>" | "<b>false</b>" + | "<b>!</b>" expr + | expr "<b>&&</b>" expr + | expr "<b>||</b>" expr + | "<b>(</b>" expr "<b>)</b>" + | comp + +comp ::= word "<b>==</b>" word | word "<b>eq</b>" word + | word "<b>!=</b>" word | word "<b>ne</b>" word + | word "<b><</b>" word | word "<b>lt</b>" word + | word "<b><=</b>" word | word "<b>le</b>" word + | word "<b>></b>" word | word "<b>gt</b>" word + | word "<b>>=</b>" word | word "<b>ge</b>" word + | word "<b>in</b>" "<b>{</b>" wordlist "<b>}</b>" + | word "<b>=~</b>" regex + | word "<b>!~</b>" regex + +wordlist ::= word + | wordlist "<b>,</b>" word + +word ::= digit + | cstring + | variable + | function + +digit ::= [0-9]+ +cstring ::= "..." +variable ::= "<b>%{</b>" varname "<b>}</b>" +function ::= funcname "<b>(</b>" funcargs "<b>)</b>" +</pre> +</blockquote> +while for <code>varname</code> any variable from <a href="#table3">Table 3</a> +can be used. Finally for <code>funcname</code> the following functions +are available: +<ul> +<li><code>file(</code><em>filename</em><code>)</code> + <p> + This function takes one string argument and expands to the contents of the + file. This is especially useful for matching this contents against a + regular expression, etc. +</ul> +Notice that <em>expression</em> is first parsed into an internal machine +representation and then evaluated in a second step. Actually, in Global and +Per-Server Class context <em>expression</em> is parsed at startup time and +at runtime only the machine representation is executed. For Per-Directory +context this is different: here <em>expression</em> has to be parsed and +immediately executed for every request. +<p> +Example: +<blockquote> +<pre> +SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ + and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ + and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ + and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \ + and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \ + or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ +</pre> +</blockquote> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 3: Available Variables for SSLRequire</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""><tr><td> +<em>Standard CGI/1.0 and Apache variables:</em> +<pre> +HTTP_USER_AGENT PATH_INFO AUTH_TYPE +HTTP_REFERER QUERY_STRING SERVER_SOFTWARE +HTTP_COOKIE REMOTE_HOST API_VERSION +HTTP_FORWARDED REMOTE_IDENT TIME_YEAR +HTTP_HOST IS_SUBREQ TIME_MON +HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY +HTTP_ACCEPT SERVER_ADMIN TIME_HOUR +HTTP:headername SERVER_NAME TIME_MIN +THE_REQUEST SERVER_PORT TIME_SEC +REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY +REQUEST_SCHEME REMOTE_ADDR TIME +REQUEST_URI REMOTE_USER ENV:<b>variablename</b> +REQUEST_FILENAME +</pre> +<em>SSL-related variables:</em> +<pre> +HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION + SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL +SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START +SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END +SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN +SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C +SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST +SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L +SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O +SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU + SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN + SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T + SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I + SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G + SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S + SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D + SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID + SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email + SSL_CLIENT_I_DN SSL_SERVER_I_DN + SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C + SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST + SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L + SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O + SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU + SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN + SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T + SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I + SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G + SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S + SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D + SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID + SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email + SSL_CLIENT_A_SIG SSL_SERVER_A_SIG + SSL_CLIENT_A_KEY SSL_SERVER_A_KEY + SSL_CLIENT_CERT SSL_SERVER_CERT + SSL_CLIENT_CERT_CHAIN<b>n</b> + SSL_CLIENT_VERIFY +</pre> +</td></tr></table> +</td> +</tr></table> +</td></tr></table> +</div> +<br> +<br> +<p> +<h1><a name="ToC24">Additional Features</a></h1> +<h2><a name="ToC25">Environment Variables</a></h2> +This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +<a href="#table4">Table 4</a>. For backward compatibility the information can +be made available under different names, too. Look in the <a +href="ssl_compat.html">Compatibility</a> chapter for details on the +compatibility variables. +<p> +<div align="center"> +<a name="table4"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 4: SSI/CGI Environment Variables</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="H"> + <td><b>Variable Name:</b></td> + <td><b>Value Type:</b></td> + <td><b>Description:</b></td> +</tr> +<tr id="D"><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> +<tr id="H"><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr> +<tr id="H"><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> +<tr id="D"><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr> +<tr id="D"><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> +<tr id="H"><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> +<tr id="D"><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> +<tr id="H"><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> +<tr id="D"><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> +<tr id="H"><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> +<tr id="D"><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> +<tr id="H"><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CERT_CHAIN</code><i>n</i></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr> +<tr id="H"><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><tt>NONE</tt>, <tt>SUCCESS</tt>, <tt>GENEROUS</tt> or <tt>FAILED:</tt><i>reason</i></td></tr> +<tr id="D"><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> +<tr id="H"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> +<tr id="D"><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> +</table> +[ where <em>x509</em> is a component of a X.509 DN: + <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ] +</td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<h2><a name="ToC26">Custom Log Formats</a></h2> +When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the <a +href="../mod_log_config.html#formats">Custom Log Format</a> of <a +href="../mod_log_config.html">mod_log_config</a>. First there is an additional +``<code>%{</code><em>varname</em><code>}x</code>'' eXtension format function +which can be used to expand any variables provided by any module, especially +those provided by mod_ssl which can you find in <a href="#table4">Table 4</a>. +<p> +For backward compatibility there is additionally a special +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +provided. Information about this function is provided in the <a +href="ssl_compat.html">Compatibility</a> chapter. +<p> +Example: +<blockquote> +<pre> +CustomLog logs/ssl_request_log \ + "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" +</pre> +</blockquote> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> |