diff options
| author | Bob Beck <beck@cvs.openbsd.org> | 1999-03-01 04:29:16 +0000 |
|---|---|---|
| committer | Bob Beck <beck@cvs.openbsd.org> | 1999-03-01 04:29:16 +0000 |
| commit | a20ee2041618d60562f0f98a6ad11ead188b1976 (patch) | |
| tree | 9189f7c643d85bb9478c0374e113cb70fadd1fd9 /usr.sbin/httpd/htdocs | |
| parent | 73f5dc18e2819ceeac315964fa0c66cb18786cc7 (diff) | |
import apache 1.3.27 and mod_ssl 2.8.11
Diffstat (limited to 'usr.sbin/httpd/htdocs')
54 files changed, 10847 insertions, 0 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/images/apache_pb.gif b/usr.sbin/httpd/htdocs/manual/images/apache_pb.gif Binary files differnew file mode 100644 index 00000000000..6fd80e2db86 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/apache_pb.gif diff --git a/usr.sbin/httpd/htdocs/manual/images/mod_ssl_sb.gif b/usr.sbin/httpd/htdocs/manual/images/mod_ssl_sb.gif Binary files differnew file mode 100644 index 00000000000..aecd3c119c6 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/images/mod_ssl_sb.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/index.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/index.html new file mode 100644 index 00000000000..3b5f78867d2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/index.html @@ -0,0 +1,209 @@ +<html> +<head> +<title>mod_ssl: Title Page</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<tr> + <td> +<br> +<table cellspacing="0" cellpadding="0" border="0"> +<tr> + <td> + <img + src="ssl_cover_title.gif" + alt="User Manual" + width="377" height="56"> + </td> +</tr> +<tr> + <td> + <a + href="http://www.engelschall.com" +><img + src="ssl_cover_logo.jpg" + alt="mod_ssl - The Apache Interface to SSLeay" + border="0" + width="546" height="294"></a> + </td> +</tr> +<tr> + <td align="right"> + <table> + <tr> + <td> + Ralf S. Engelschall<br> + <font size="-1">rse@engelschall.com</font><br> + <font size="-1">www.engelschall.com</font><br> + </td> + <td> + + </td> + <td align="right" valign="bottom"> +<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_unknown1_n = new Image(); + ro_img_unknown1_n.src = "ssl_template.navbut-next-n.gif"; + ro_img_unknown1_o = new Image(); + ro_img_unknown1_o.src = "ssl_template.navbut-next-s.gif"; +} +// done hiding --> +</script> +<a href="ssl_overview.html" + onMouseOver="ro_imgOver('ro_img_unknown1', 'next page'); return true" + onMouseOut="ro_imgNormal('ro_img_unknown1'); return true" +><img + name="ro_img_unknown1" + src="ssl_template.navbut-next-n.gif" + alt="next page" + width="70" height="18" + border="0" +></a><br>Overview + </td> + </tr> + </table> + </td> +</tr> +</table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.gfont000.gif Binary files differnew file mode 100644 index 00000000000..3131a672bf9 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.html new file mode 100644 index 00000000000..f362f7e10d8 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.html @@ -0,0 +1,567 @@ +<html> +<head> +<title>mod_ssl: Compatibility</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-4.gif" alt="4" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_reference.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">Reference</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_howto.html" + onMouseOver="ro_imgOver('ro_img_next_top', 'next page'); return true" + onMouseOut="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">HowTo</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-compat.gif" alt="Compatibility" width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="200"> +<tr> +<td> +<em>All PCs are compatible. But some of +them are more compatible than others.</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Unknown +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> +<img src="ssl_compat.gfont000.gif" alt="H" width="40" height="34" border="0" align="left"> +ere we talk about backward compatibility to other SSL solutions. As you +perhaps know mod_ssl is not the only existing SSL solution for Apache. +Actually there are four additional products available: Ben Laurie's freely +available <a href="http://www.apache-ssl.org/">Apache-SSL</a> (from where +mod_ssl were originally derived), RedHat's commercial <a +href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web +Server</a> (which is based on mod_ssl), Covalent's commercial <a +href="http://raven.covalent.net/">Raven SSL Module</a> (also based on +Apache-SSL) and finally C2Net's commercial product <a +href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a +different evolution branch named Sioux). +</td> +<td> + +</td> +<td> +<DIV align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff"> +<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>Environment Variables</strong></a><br> + <a href="#ToC3"><strong>Custom Log Functions</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<p> +The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a +superset of the functionality of all other solutions we can easily provide +backward compatibility for most of the cases. Actually there are three +compatibility areas we currently address: configuration directives, +environment variables and custom log functions. +<H2><a name="ToC1">Configuration Directives</a></H2> +For backward compatibility to the configuration directives of other SSL +solutions we do an on-the-fly mapping: directives which have a direct +counterpart in mod_ssl are mapped silently while other directives lead to a +warning message in the logfiles. The currently implemented directive mapping +is listed in <a href="#table1">Table 1</a>. Currently full backward +compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. +Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of +special functionality in these interfaces which mod_ssl (still) doesn't +provide. +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 1: Configuration Directive Mapping</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<tr id="D"> +<td><strong>Old Directive</strong></td> +<td><strong>mod_ssl Directive</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id="H"><td colspan="3"><b>Apache-SSL 1.x & mod_ssl 2.0.x compatibility:</b></td></tr> +<tr id="D"><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr> +<tr id="H"><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr> +<tr id="D"><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr> +<tr id="H"><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>", ...}</code></td><td>generalized</td></tr> +<tr id="H"><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>", ...})</code></td><td>generalized</td></tr> +<tr id="D"><td><code>SSLFakeBasicAuth</td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr> +<tr id="H"><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr> +<tr id="D"><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr> +<tr id="H"><td colspan="3"><b>Apache-SSL 1.x compatibility:</b></td></tr> +<tr id="D"><td><code>SSLExportClientCertificates</td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr> +<tr id="H"><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td colspan="3"><b>Sioux 1.x compatibility:</b></td></tr> +<tr id="H"><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherList</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr> +<tr id="D"><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr> +<tr id="H"><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr> +<tr id="D"><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td colspan="3"><b>Stronghold 2.x compatibility:</b></td></tr> +<tr id="H"><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id="D"><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr> +</table></td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<H2><a name="ToC2">Environment Variables</a></H2> +When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment +variables are generated. They all correspond to existing official mod_ssl +variables. The currently implemented variable derivation is listed in <a +href="#table2">Table 2</a>. +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 2: Environment Variable Derivation</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<tr id="D"> +<td><strong>Old Variable</strong></td> +<td><strong>mod_ssl Variable</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id="H"><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr> +<tr id="H"><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr> +<tr id="D"><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id="H"><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr> +<tr id="D"><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +</table></td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<H2><a name="ToC3">Custom Log Functions</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> as documented in the Reference +Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>'' +eXtension format function which can be used to expand any variables provided +by any module, an additional Cryptography +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +exists for backward compatibility. The currently implemented function calls +are listed in <a href="#table3">Table 3</a>. +<p> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 3: Custom Log Cryptography Function</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<tr id="H"> + <td><strong>Function Call</strong></td> + <td><strong>Description</strong></td> +</tr> +<tr id="D"><td><code>%...{version}c</code></td> <td>SSL protocol version</td></tr> +<tr id="H"><td><code>%...{cipher}c</code></td> <td>SSL cipher</td></tr> +<tr id="D"><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr> +<tr id="H"><td><code>%...{issuerdn}c</code></td> <td>Client Certificate Issuer Distinguished Name</td></tr> +<tr id="D"><td><code>%...{errcode}c</code></td> <td>Certificate Verification Error (numerical)</td></tr> +<tr id="H"><td><code>%...{errstr}c</code></td> <td>Certificate Verification Error (string)</td></tr> +</table></td> +</tr></table> +</td></tr></table> +</div> + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_reference.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">Reference</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_howto.html" + onMouseOver="ro_imgOver('ro_img_next_bot', 'next page'); return true" + onMouseOut="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">HowTo</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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.wml new file mode 100644 index 00000000000..512f239b7cb --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_compat.wml @@ -0,0 +1,245 @@ + +#use "ssl_template.inc" title="Compatibility" tag=compat num=4 + +<page_prev name="Reference" url="ssl_reference.html"> +<page_next name="HowTo" url="ssl_howto.html"> + +#use wml::std::toc style=nbsp + +<quotation width=200 author="Unknown"> +All PCs are compatible. But some of +them are more compatible than others. +</quotation> + +<p> +<table cellspacing=0 cellpadding=0 border=0> +<tr valign=bottom> +<td> + +<big H>ere we talk about backward compatibility to other SSL solutions. As you +perhaps know mod_ssl is not the only existing SSL solution for Apache. +Actually there are four additional products available: Ben Laurie's freely +available <a href="http://www.apache-ssl.org/">Apache-SSL</a> (from where +mod_ssl were originally derived), RedHat's commercial <a +href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web +Server</a> (which is based on mod_ssl), Covalent's commercial <a +href="http://raven.covalent.net/">Raven SSL Module</a> (also based on +Apache-SSL) and finally C2Net's commercial product <a +href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a +different evolution branch named Sioux). + +</td> +<td> + +</td> +<td> + +<div align=right> +<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff"> +<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> +<toc> +</font> +</td> +</tr> +</table> +</div> + +</td> +</tr> +</table> + +<p> +The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a +superset of the functionality of all other solutions we can easily provide +backward compatibility for most of the cases. Actually there are three +compatibility areas we currently address: configuration directives, +environment variables and custom log functions. + +<h2>Configuration Directives</h2> + +For backward compatibility to the configuration directives of other SSL +solutions we do an on-the-fly mapping: directives which have a direct +counterpart in mod_ssl are mapped silently while other directives lead to a +warning message in the logfiles. The currently implemented directive mapping +is listed in <a href="#table1">Table 1</a>. Currently full backward +compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. +Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of +special functionality in these interfaces which mod_ssl (still) doesn't +provide. + +<p> +<float name="table1" caption="Table 1: Configuration Directive Mapping"> +<table border=0 cellspacing=0 cellpadding=2 width=598> +<tr id=D> +<td><strong>Old Directive</strong></td> +<td><strong>mod_ssl Directive</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id=H><td colspan=3><b>Apache-SSL 1.x & mod_ssl 2.0.x compatibility:</b></td></tr> +<tr id=D><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr> +<tr id=H><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr> +<tr id=D><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr> +<tr id=H><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>", ...}</code></td><td>generalized</td></tr> +<tr id=H><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>", ...})</code></td><td>generalized</td></tr> +<tr id=D><td><code>SSLFakeBasicAuth</td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr> +<tr id=H><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr> +<tr id=D><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr> + +<tr id=H><td colspan=3><b>Apache-SSL 1.x compatibility:</b></td></tr> +<tr id=D><td><code>SSLExportClientCertificates</td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr> +<tr id=H><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> + +<tr id=D><td colspan=3><b>Sioux 1.x compatibility:</b></td></tr> +<tr id=H><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherList</code> <em>arg</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr> +<tr id=D><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr> +<tr id=H><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr> +<tr id=D><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> + +<tr id=D><td colspan=3><b>Stronghold 2.x compatibility:</b></td></tr> +<tr id=H><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id=D><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr> +<tr id=H><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id=D><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=H><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id=D><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr> +</table> +</float> + +<p> +<br> +<h2>Environment Variables</h2> + +When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment +variables are generated. They all correspond to existing official mod_ssl +variables. The currently implemented variable derivation is listed in <a +href="#table2">Table 2</a>. + +<p> +<float name="table2" caption="Table 2: Environment Variable Derivation"> +<table border=0 cellspacing=0 cellpadding=2 width=598> +<tr id=D> +<td><strong>Old Variable</strong></td> +<td><strong>mod_ssl Variable</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id=H><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr> +<tr id=H><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr> +<tr id=D><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id=H><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr> +<tr id=D><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr> +<tr id=H><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr> +<tr id=D><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=D><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=D><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=D><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=D><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=D><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id=H><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +</table> +</float> + +<p> +<br> +<h2>Custom Log Functions</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> as documented in the Reference +Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>'' +eXtension format function which can be used to expand any variables provided +by any module, an additional Cryptography +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +exists for backward compatibility. The currently implemented function calls +are listed in <a href="#table3">Table 3</a>. + +<p> +<float name="table3" caption="Table 3: Custom Log Cryptography Function"> +<table border=0 cellspacing=0 cellpadding=2 width=598> +<tr id=H> + <td><strong>Function Call</strong></td> + <td><strong>Description</strong></td> +</tr> +<tr id=D><td><code>%...{version}c</code></td> <td>SSL protocol version</td></tr> +<tr id=H><td><code>%...{cipher}c</code></td> <td>SSL cipher</td></tr> +<tr id=D><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr> +<tr id=H><td><code>%...{issuerdn}c</code></td> <td>Client Certificate Issuer Distinguished Name</td></tr> +<tr id=D><td><code>%...{errcode}c</code></td> <td>Certificate Verification Error (numerical)</td></tr> +<tr id=H><td><code>%...{errstr}c</code></td> <td>Certificate Verification Error (string)</td></tr> +</table> +</float> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover.wml new file mode 100644 index 00000000000..c1166016469 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover.wml @@ -0,0 +1,51 @@ +#!wml -oindex.html + +#use "ssl_template.inc" title="Title Page" tag=title num=0 + +<br> +<table cellspacing=0 cellpadding=0 border=0> +<tr> + <td> + <img + src="ssl_cover_title.gif" + alt="User Manual" + > + </td> +</tr> +<tr> + <td> + <a + href="http://www.engelschall.com" + ><img + src="ssl_cover_logo.jpg" + alt="mod_ssl - The Apache Interface to SSLeay" + border=0 + ></a> + </td> +</tr> +<tr> + <td align=right> + <table> + <tr> + <td> + Ralf S. Engelschall<br> + <font size=-1>rse@engelschall.com</font><br> + <font size=-1>www.engelschall.com</font><br> + </td> + <td> + + </td> + <td align=right valign=bottom> + <rollover + href="ssl_overview.html" + src="ssl_template.navbut-next-n.gif" + oversrc="ssl_template.navbut-next-s.gif" + alt="next page" + ><br>Overview + </td> + </tr> + </table> + </td> +</tr> +</table> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover_logo.jpg b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover_logo.jpg Binary files differnew file mode 100644 index 00000000000..af92da6127e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_cover_logo.jpg diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.gfont000.gif Binary files differnew file mode 100644 index 00000000000..7fb5db91b00 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.html new file mode 100644 index 00000000000..355cf43dda4 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.html @@ -0,0 +1,1296 @@ +<html> +<head> +<title>mod_ssl: F.A.Q.</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-6.gif" alt="6" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_howto.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">HowTo</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_glossary.html" + onMouseOver="ro_imgOver('ro_img_next_top', 'next page'); return true" + onMouseOut="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">Glossary</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-faq.gif" alt="F.A.Q." width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="200"> +<tr> +<td> +<em>``The wise man doesn't give the right answers, +he poses the right questions.''</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Claude Levi-Strauss +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> +<img src="ssl_faq.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> +his chapter is a collection of frequently asked questions (FAQ) and +corresponding answers following the popular USENET tradition. Most of these +questions occured on the Newsgroup <a +href="news:comp.infosystems.www.servers.unix"> +<code>comp.infosystems.www.servers.unix</code></a> or the mod_ssl Support +Mailing List <a href="mailto:sw-mod-ssl@engelschall.com"> +<code>sw-mod-ssl@engelschall.com</code></a>. They are collected at this place +to avoid answering the same questions over and over. +<p> +Please read this chapter at least once when installing mod_ssl or at least +search for your problem here before submitting a problem report to the +author. +</td> +<td> + +</td> +<td> +<DIV align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" width="300"> +<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>About the module</strong></a><br> + <a href="#ToC2"><strong>Apache-SSL vs. mod_ssl: difference?</strong></a><br> + <a href="#ToC3"><strong>Should Apache-SSL be avoided?</strong></a><br> + <a href="#ToC4"><strong>Which Apache-SSL version is the base?</strong></a><br> + <a href="#ToC5"><strong>Why starting with version 2.0.0?</strong></a><br> + <a href="#ToC6"><strong>mod_ssl/Apache versions?</strong></a><br> + <a href="#ToC7"><strong>mod_ssl and Year 2000?</strong></a><br> + <a href="#ToC8"><strong>mod_ssl and Wassenaar Arrangement?</strong></a><br> + <a href="#ToC9"><strong>About Configuration</strong></a><br> + <a href="#ToC10"><strong>HTTP and HTTPS on same machine?</strong></a><br> + <a href="#ToC11"><strong>Where is the HTTPS port?</strong></a><br> + <a href="#ToC12"><strong>How to test HTTPS manually?</strong></a><br> + <a href="#ToC13"><strong>Why does my browser hang?</strong></a><br> + <a href="#ToC14"><strong>How to switch with relative hyperlinks?</strong></a><br> + <a href="#ToC15"><strong>About Certificates</strong></a><br> + <a href="#ToC16"><strong>What are Keys, CSRs and Certs?</strong></a><br> + <a href="#ToC17"><strong>Difference on startup?</strong></a><br> + <a href="#ToC18"><strong>How to create a dummy cert?</strong></a><br> + <a href="#ToC19"><strong>How to create a real cert?</strong></a><br> + <a href="#ToC20"><strong>How to create my own CA?</strong></a><br> + <a href="#ToC21"><strong>How to change a pass phrase?</strong></a><br> + <a href="#ToC22"><strong>How to remove a pass phrase?</strong></a><br> + <a href="#ToC23"><strong>How to verify a key/cert pair?</strong></a><br> + <a href="#ToC24"><strong>Why does a 2048-bit key not work?</strong></a><br> + <a href="#ToC25"><strong>Why is client auth broken?</strong></a><br> + <a href="#ToC26"><strong>About SSL Protocol</strong></a><br> + <a href="#ToC27"><strong>Why has the server a higher load?</strong></a><br> + <a href="#ToC28"><strong>Which ciphers are supported?</strong></a><br> + <a href="#ToC29"><strong>HTTPS and name-based vhosts</strong></a><br> + <a href="#ToC30"><strong>The lock icon in Netscape locks very late</strong></a><br> + <a href="#ToC31"><strong>About Support</strong></a><br> + <a href="#ToC32"><strong>Resources in case of problems?</strong></a><br> + <a href="#ToC33"><strong>Support in case of problems?</strong></a><br> + <a href="#ToC34"><strong>How to write a problem report?</strong></a><br> + <a href="#ToC35"><strong>How to get a backtrace?</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<H2><a name="ToC1">About the module</a></H2> +<ul> +<p> +<li><a name="ToC2"></a> + <a name="apssl-diff"></a> + <strong id="faq">What are the differences between mod_ssl and Apache-SSL, from where it is derived?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#apssl-diff"><b>L</b></a>] + <p> + This cannot be answered in short, because there are too much changes (see + the <code>CHANGES</code> and <code>CHANGES.20</code> files in the mod_ssl + distribution for detailed information). Most of them are internal changes, + cleanups and re-organizations of the source code. But the user visible + changes are mainly the following: + <p> + <ul> + <li><em>mod_ssl provides a complete documentation</em> (this User Manual) + where all configuration directives, environment variables, and other + things are documented while Apache-SSL had no such documentation + although it existed for over three years when mod_ssl was split from + it (in April 1998). Additionally mod_ssl provides answers to often + occuring frequently asked questions (this list) in the + Apache/SSL/SSLeay area. For instance mod_ssl gives detailed hints + about how to setup a CA, how to create real a server Certificate, etc. + And the mod_ssl User Manual provides a compact introduction to the + complex SSL area itself. Because here are the typical hurdles located + every user stumbles over. + <p> + <li><em>mod_ssl comes with clean and documented source code</em> with the + intent that only this way the user is able to re-view it for + backdoors, security holes, etc. This is considered important for + security-related software. It was always incomprehensible to the + author of mod_ssl how Apache-SSL could exist for over three years + while both the source code and the source patches were provided in an + undocumented and partly unreadable format. For the mod_ssl package + the source codes follows the Apache coding style, is logically + ordered to follow the API phases and even the patches to the + Apache source tree are annotated with descriptions to give the + user a chance to re-view and understand them. + <p> + <li><em>mod_ssl uses a generic Extended API</em> to achieve + its functionality. This means instead of patching in + SSL/crypto-related code into the Apache kernel a clean and well + separated Extended API is patched in. This way the SSL and + cryptography code is <em>only</em> present inside the SSL module + itself (i.e. inside the <code>src/modules/ssl/</code> subtree only). + The benefit from this is a clean separation and API-conforming SSL + solution (which means for instance no direct SSL-references from the + kernel, no kludges and hacks to get called, etc). + <p> + <li><em>mod_ssl supports Dynamic Shared Object (DSO) building</em> + as a direct consequence from using the Extended API. In short DSO + support means maximum flexibility under run-time, i.e. you don't have + to decide under compile-time whether to build or not to build SSL into + the Apache httpd executable. Instead you can just load mod_ssl through + mod_so's <code>LoadModule</code> directive <em>on demand</em>. This + is especially interesting for two cases: Vendor package maintainers + receive the power they need for creating flexible packages and power + users receive the ability to run more than one Apache (non-SSL-aware + and SSL-aware) instance from a single Apache installation while still + saving RAM. + <p> + <li><em>mod_ssl is ported to the Win32 platform</em>, + as it's the case for Apache and SSLeay. This way mod_ssl follows the + evolution of these packages and provides the always requested support + also for this nasty platform. As for the Unix/DSO case under Win32 + mod_ssl is well-integrated into Apache through a stand-alone DLL which + can be loaded through mod_so's <code>LoadModule</code> directive. + <p> + <li><em>mod_ssl can be really easily applied to the Apache source tree</em> because + it provides a full-featured and automated configuration environment + for this task while Apache-SSL forced the user to fiddle with the + <code>patch</code> and <code>cp</code> tools theirself. Just + because security is not for amateurs hasn't to mean that user + friendliness is not important. So it's a must to assist the user + in applying the SSL-stuff to vanilla Apache sources. For this + mod_ssl integrates also very-well into the new Apache 1.3 + Autoconf-style Interface (APACI). Additionally mod_ssl's + configuration mechanism supports the usage of RSAref, arbitrary + locations for SSLeay, etc. + <p> + <li><em>mod_ssl fixes a lot of bugs and inconsistencies</em> which + existed in Apache-SSL. For Apache experts here are a few impressions: + Apache-SSL wrote directly to <code>stderr</code> instead of the Apache + error logfile; it messed up it's error messages with the SSLeay error + messages; it directly patched the <code>SERVER_BASEVERSION</code> + define instead of using the Apache 1.3 conforming + <code>ap_add_version_component</code> function; it used the unsafe + <code>sprintf</code> function instead of the robust + <code>ap_snprintf</code>; it incorrectly spawned and killed the + <code>gcache</code> auxiliary program and it totally failed to pass the + ``<code>gcc -Wall -Wshadow -Wpointer-arith -Wcast-align + -Wmissing-prototypes -Wmissing-declarations -Wnested-externs + -Winline</code>'' test (while Apache already passes it) because of + unclean code. + <p> + Additionally Apache-SSL didn't provide a way to easily apply it to + the Apache source tree (semi-manual editing and patching was + required); it didn't seamlessly integrate into the new Apache 1.3 + Autoconf-style Interface (APACI) at configuration time; it didn't + automatically recognize the difference between an installed SSLeay and + an out-of-the-source-only SSLeay; it didn't provide integration into + the APACI installation process (<code>make install</code>); it used + numbers 0 to 2 instead of reasonable names for the argument of + <code>SSLVerifyClient</code> just because internally an + <code>enum</code> was used and for the provided + <code>%{version}c</code> construct of CustomLog it used the results + "2", "3" under SSLeay 0.8 while under SSLeay 0.9 the results were + "SSL2", "SSL3", etc. pp. + <p> + <li><em>mod_ssl adds new functionalities which were missing in + Apache-SSL</em>. A few selected points which give you an impression + follow: + <ul> + <li>mod_ssl provides a real dedicated SSL log file controlled by log + level and the additional features that messages logged at the + `error' level are automatically duplicated to the general Apache + error log file. And occuring system and SSLeay error messages are + automatically appended to mod_ssl messages. Additionally mod_ssl + annotates deep-level SSLeay messages with more high-level hints. + <li>mod_ssl provides a completely new and enhanced handling + of encrypted private key files. First the private keys are kept in + a permanent memory pool (as SSLeay already does internally), so + Apache now survives server restarts without falling down. Second + the pass phrase dialog is a lot more user friendly and advanced: + It uses a pass phrase reuse-algorithm to minimize the dialog, it + recognizes wrong pass phrases and allows retries (but with a + backoff time delay), etc. And additionally a minimal interface is + provided to plug-in an external program for providing the pass + phrase for special batch security situations. + <li>mod_ssl provides the <code>SSLCACertificateReqFile</code> + directive which can be used to configure a different (from + <code>SSLCACertificateFile</code>) set of CA Certificates for the + SSLv3 feature used by the clients to load CA Certificates from the + server for speeding up server authentication. + <li>mod_ssl replaced the ``gcache'' stuff of Apache-SSL (used for + caching SSL sessions) with a more robust DBM-based solution, + because the controlling of an external program cannot be done very + reliable from within Apache. Additionally a "mutex" is now used to + synchronize the inter-process access to this cache. + <li>mod_ssl provides support for the SSLeay+RSAref couple, i.e. + mod_ssl supports the building with RSAref. + <li>mod_ssl provides a new SSLRequire directive which can be used + to implement more granular access control based on arbitrary + complex boolean expression. + <li>mod_ssl adds support for HTTPS to the Apache Proxy Module + (mod_proxy). + <li>mod_ssl is the first Open Source version of an SSL + extension to Apache which supports the Win32 platform. + <li>etc.pp. + </ul> + </ul> + <p> + When you're still really interested in more hard-core details walk through + the entries in the <code>CHANGES</code> and <code>CHANGES.20</code> files + in the mod_ssl distribution. +<p> +<li><a name="ToC3"></a> + <a name="apssl-avoid"></a> + <strong id="faq">Ok, does this mean I should avoid using Apache-SSL from now on?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#apssl-avoid"><b>L</b></a>] + <p> + <strong>No</strong>, it just means that you <em>can</em> use mod_ssl. + Beside the well-known flaws Apache-SSL works great. Ben Laurie did and + still does a great job in maintaining it. The big difference is just that + Ben Laurie's goals are different from Ralf S. Engelschall's goals. So, as + long as you don't get bothered by inconsistencies and other flaws you + don't have to upgrade. Instead you should decide yourself if you already + feel comfortable or not. If yes, stay with Apache-SSL - if not, move to + mod_ssl or (even better) one of the commercial SSL solutions for Apache. + Or in other words: No solution is better than another in general. Which + one you should use depends mainly on your personal requirements. +<p> +<li><a name="ToC4"></a> + <a name="apssl-baseversion"></a> + <strong id="faq">On which Apache-SSL version is mod_ssl actually based?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#apssl-baseversion"><b>L</b></a>] + <p> + The mod_ssl package was initially created by porting the Apache-SSL 1.17 + stuff from Apache 1.2.6 to Apache 1.3b6 in April 1998. Because of + conflicts with Ben Laurie's development cycle it then was re-assembled + from scratch for Apache 1.3.0 by merging the old mod_ssl with the newer + Apache-SSL 1.18. From this point mod_ssl lived its own life and changes + with Apache-SSL releases were merged after they were released. In other + words: mod_ssl is based on the latest Apache-SSL and always will contain + all useful changes which will occur with Apache-SSL in the future. +<p> +<li><a name="ToC5"></a> + <a name="why200"></a> + <strong id="faq">Why is mod_ssl's version starting with 2.0.0?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#why200"><b>L</b></a>] + <p> + Because initially the mod_ssl project was intended as a contribution to + the Apache-SSL project from Ben Laurie. The idea was that mod_ssl formed + Apache-SSL 2.0.0. But after Ralf S. Engelschall and Ben Laurie couldn't + find a reasonable compromise in merging mod_ssl with Apache-SSL, the stuff + was released as a new package named ``mod_ssl''. But to still indicate + that it's some ``second generation'' stuff, the first mod_ssl version was + named 2.0.0. +<p> +<li><a name="ToC6"></a> + <a name="what-version"></a> + <strong id="faq">How do I know which mod_ssl version is for which Apache version?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#what-version"><b>L</b></a>] + <p> + That's trivial: mod_ssl uses version strings of the syntax + <em><mod_ssl-version></em>-<em><apache-version></em>, for + instance <code>2.2.0-1.3.4</code>. This directly indicates that it's + mod_ssl version 2.2.0 for Apache version 1.3.4. And this also means you + <em>only</em> can apply this mod_ssl version to exactly this Apache + version (unless you use the <code>--force</code> option to mod_ssl's + <code>configure</code> command ;-). +<p> +<li><a name="ToC7"></a> + <a name="y2k"></a> + <strong id="faq">Is mod_ssl Year 2000 compliant?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#y2k"><b>L</b></a>] + <p> + Yes, mod_ssl is Year 2000 compliant. + <p> + Because first mod_ssl internally never stores years as two digits. + Instead it always uses the ANSI C & POSIX numerical data type + <code>time_t</code> type, which on mostly all Unix platforms at the moment + is a <code>signed long</code> (usually 32-bits) representing seconds since + epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in + early January 2038 and not in the year 2000. Second, date and time + presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'') + are done with full year value instead of abbreviating to two digits. + <p> + Additionally according to a <a + href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000 + statement</a> from the Apache Group, the Apache webserver is Year 2000 + compliant, too. But whether SSLeay or the underlaying Operating System + (either a Unix or Win32 platform) is Year 2000 compliant is a different + question which cannot be answered here. +<p> +<li><a name="ToC8"></a> + <a name="wassenaar"></a> + <strong id="faq">What about mod_ssl and the Wassenaar Arrangement?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#wassenaar"><b>L</b></a>] + <p> + First, let us explain what <i>Wassenaar</i> and it's <i>Arrangement on + Export Controls for Conventional Arms and Dual-Use Goods and + Technologies</i> is: This is a international regime, established 1995, to + control trade in conventional arms and dual-use goods and technology. It + replaced the previous <i>CoCom</i> regime. 33 countries are signatories: + Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, + Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, + Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic + of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, + Switzerland, Turkey, Ukraine, United Kingdom and United States. For more + details look at <a + href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>. + <p> + In short: The aim of the Wassenaar Arrangement is to prevent the build up + of military capabilities that threaten regional and international security + and stability. The Wassenaar Arrangement controls the export of + cryptography as a dual-use good, i.e., one that has both military and + civilian applications. However, the Wassenaar Arrangement also provides an + exemption from export controls for mass-market software and free software. + <p> + In the current Wassenaar ``<i>List of Dual Use Goods and Technologies And + Munitions</i>'', under ``<i>GENERAL SOFTWARE NOTE</i>'' (GSN) it says + ``<i>The Lists do not control "software" which is either: 1. [...] 2. "in + the public domain".</i>'' And under ``<i>DEFINITIONS OF TERMS USED IN + THESE LISTS</i>'' one can find the definition: ``<i>"In the public + domain": This means "technology" or "software" which has been made + available without restrictions upon its further dissemination. N.B. + Copyright restrictions do not remove "technology" or "software" from being + "in the public domain".</i>'' + <p> + So, both mod_ssl and SSLeay are ``in the public domain'' for the purposes + of the Wassenaar Agreement and its ``<i>List of Dual Use Goods and + Technologies And Munitions List</i>''. + <p> + Additionally the Wassenaar Agreement itself has no direct consequence for + exporting cryptography software. What is actually allowed or forbidden to + be exported from the countries has still to be defined in the local laws + of each country. And at least according to official press releases from + the German BMWi (see <a + href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the + Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there + will be no forthcoming export restriction for free cryptography software + for their countries. Remember that mod_ssl is created in Germany and + distributed from Switzerland. + <p> + So, mod_ssl and SSLeay are not affected by the Wassenaar Agreement. +</ul> +<p> +<br> +<H2><a name="ToC9">About Configuration</a></H2> +<ul> +<p> +<li><a name="ToC10"></a> + <a name="https-parallel"></a> + <strong id="faq">I want to run HTTP and HTTPS on the same machine. Is that possible?</strong></strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#https-parallel"><b>L</b></a>] + <p> + Yes, there are two ways to do this: run two server instances, or run both + services from the same server instance. Unless there is a good reason to + run two (like using a different product for HTTP and HTTPS), it's usually + most simples to run a single instance where you enable SSL only for those + virtual hosts that need it. If you wish to run two server instances you + must make sure that they each only try to bind to their allowed ports + (normally port 80 for HTTP and 443 for HTTPS). +<p> +<li><a name="ToC11"></a> + <a name="https-port"></a> + <strong id="faq">I know that HTTP is on port 80, but where is HTTPS?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#https-port"><b>L</b></a>] + <p> + You can run HTTPS on any port, but the standards specify port 443, which + is where any HTTPS compliant browser will look by default. You can force + your browser to look on a different port by specifying it in the URL like + this (for port 666): <code>https://secure.server.dom:666/</code> +<p> +<li><a name="ToC12"></a> + <a name="https-test"></a> + <strong id="faq">How can I speak HTTPS manually for testing purposes?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#https-test"><b>L</b></a>] + <p> + While you usually just use + <p> + <code><b>$ telnet localhost 80</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + for simple testing the HTTP protocol of Apache, it's not such easy for + HTTPS because of the SSL protocol between TCP and HTTP. But with the + help of SSLeay's <code>s_client</code> program you can do a similar + check even for HTTPS: + <p> + <code><b>$ s_client -connect localhost:443 -state -debug</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + Before the actual HTTP response you receive detailed information about the + SSL handshake. For a more general command line client which directly + understands both the HTTP and HTTPS scheme, can perform GET and POST + methods, can use a proxy, supports byte ranges, etc. you should have a + look at nifty <a href="http://www.fts.frontec.se/~dast/curl/">cURL</a> + tool. With it you can directly check if your Apache is running fine on + Port 80 and 443 as following: + <p> + <code><b>$ curl http://localhost/</b></code><br> + <code><b>$ curl https://localhost/</b></code><br> +<p> +<li><a name="ToC13"></a> + <a name="hang"></a> + <strong id="faq">Why does my browser hang when I connect to my SSL-aware Apache server?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#hang"><b>L</b></a>] + <p> + Because you used an URL of the form ``<code>http://</code>'' instead of + ``<code>https:</code>''. Really! Also, if you see: ``<code>SSL_Accept + failed error:140760EB:SSL routines: SSL23_GET_CLIENT_HELLO:unknown + protocol</code>'' in your Apache error logfile, it's for the same reason. + This also happens the other way round, i.e. when you try to use + ``<code>https://</code>'' on a server that doesn't support SSL (on this + port). Make sure you are connecting to a virtual server that supports + SSL, which is probably the IP associated with your hostname, not localhost + (127.0.0.1). +<p> +<li><a name="ToC14"></a> + <a name="relative-links"></a> + <strong id="faq">How can I use relative hyperlinks to switch between HTTP and HTTPS?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#relative-links"><b>L</b></a>] + <p> + Usually you have to use fully-qualified hyperlinks because + you have to change the URL scheme. But with the help of some URL + manipulations through mod_rewrite you can achieve the same effect while + you still can use relative URLs: + <pre> + RewriteEngine on + RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L] + RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L] + </pre> + This rewrite ruleset lets you use hyperlinks of the form + <pre> + <a href="document.html:SSL"> + </pre> +</ul> +<p> +<br> +<H2><a name="ToC15">About Certificates</a></H2> +<ul> +<p> +<li><a name="ToC16"></a> + <a name="what-is"></a> + <strong id="faq">What are RSA Private Keys, CSRs and Certificates?</strong></strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#what-is"><b>L</b></a>] + <p> + The RSA private key file is a digital file that you can use to decrypt + messages sent to you. It has a public component which you distribute (via + your Certificate file) which allows people to encrypt those messages to + you. A Certificate Signing Request (CSR) is a digital file which contains + your public key and your name. You send the CSR to a Certifying Authority + (CA) to be converted into a real Certificate. A Certificate contains your + RSA public key, your name, the name of the CA, and is digitally signed by + your CA. Browsers that know the CA can verify the signature on that + Certificate, thereby obtaining your RSA public key. That enables them to + send messages which only you can decrypt. + See the <a href="ssl_intro.html">Introduction</a> chapter for a general + description of the SSL protocol. +<p> +<li><a name="ToC17"></a> + <a name="startup"></a> + <strong id="faq">Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#startup"><b>L</b></a>] + <p> + Yes, in general, starting Apache with a built-in mod_ssl is just like + starting an unencumbered Apache, except for the fact that when you have a + pass phrase on your SSL private key file. Then a startup dialog pops up + asking you to enter the pass phrase. + <p> + To type in the pass phrase manually when starting the server can be + problematic, for instance when starting the server from the system boot + scripts. As an alternative to this situation you can follow the steps + below under ``How can I get rid of the pass-phrase dialog at Apache + startup time?''. +<p> +<li><a name="ToC18"></a> + <a name="cert-dummy"></a> + <strong id="faq">How can I create a dummy SSL server Certificate for testing purposes?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#cert-dummy"><b>L</b></a>] + <p> + A Certificate does not have to be signed by a public CA. You can use your + private key to sign the Certificate which contains your public key. You + can install this Certificate into your server, and people using Netscape + Navigator (not MSIE) will be able to connect after clicking OK to a + warning dialogue. You can get MSIE to work, and your customers can + eliminate the dialogue, by installing that Certificate manually into their + browsers. + <p> + Just use the ``<code>make certificate</code>'' command at the top-level + directory of the Apache source tree right before installing Apache via + ``<code>make install</code>''. This creates a self-signed SSL Certificate + which expires after 30 days and isn't encrypted (which means you don't + need to enter a pass-phrase at Apache startup time). + <p> + BUT REMEMBER: YOU REALLY HAVE TO CREATE A REAL CERTIFICATE FOR THE LONG + RUN! HOW THIS IS DONE IS DESCRIBED IN THE NEXT ANSWER. +<p> +<li><a name="ToC19"></a> + <a name="cert-real"></a> + <strong id="faq">Ok, I've got my server installed and want to create a real SSL +server Certificate for it. How do I do it?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#cert-real"><b>L</b></a>] + <p> + Here is a step-by-step description: + <p> + <ol> + <li>Make sure SSLeay is really installed and in your <code>PATH</code>. + But some commands even work ok when you just run the + ``<code>ssleay</code>'' program from within the SSLeay source tree as + ``<code>./apps/ssleay</code>''. + <p> + <li>Create a RSA private key for your Apache server + (will be Triple-DES encrypted and PEM formatted): + <p> + <code><strong>$ ssleay genrsa -des3 -out server.key 1024</strong></code> + <p> + Please backup this <code>server.key</code> file and remember the + pass-phrase you had to enter at a secure location. + You can see the details of this RSA private key via the command: + <p> + <code><strong>$ ssleay rsa -noout -text -in server.key</strong></code> + <p> + And you could create a decrypted PEM version (not recommended) + of this RSA private key via: + <p> + <code><strong>$ ssleay rsa -in server.key -out server.key.unsecure</strong></code> + <p> + <li>Create a Certificate Signing Request (CSR) for the server RSA private + key (output will be PEM formatted): + <p> + <code><strong>$ ssleay req -new -days 365 -key server.key -out server.csr</strong></code> + <p> + You can see the details of this CSR via the command + <p> + <code><strong>$ ssleay req -noout -text -in server.csr</strong></code> + <p> + <li>You now have to send this Certificate Signing Request (CSR) to + a Certifying Authority (CA) for signing. The result is then a real + Certificate which can be used for Apache. Here you have to options: + First you can let the CSR sign by a commercial CA like Verisign or + Thawte. Then you usually have to post the CSR into a web form, pay for + the signing and await the signed Certificate you then can store into a + server.crt file. For more information about commercial CAs have a look + at the following locations: + <p> + <ul> + <li> Verisign<br> + <a href="http://digitalid.verisign.com/server/apacheNotice.htm"> + http://digitalid.verisign.com/server/apacheNotice.htm + </a> + <li> Thawte Consulting<br> + <a href="http://www.thawte.com/certs/server/request.html"> + http://www.thawte.com/certs/server/request.html + </a> + <li> CertiSign Certificadora Digital Ltda.<br> + <a href="http://www.certisign.com.br"> + http://www.certisign.com.br + </a> + <li> IKS GmbH<br> + <a href="http://www.iks-jena.de/produkte/ca/"> + http://www.iks-jena.de/produkte/ca/ + </a> + <li> Uptime Commerce Ltd.<br> + <a href="http://www.uptimecommerce.com"> + http://www.uptimecommerce.com + </a> + <li> BelSign NV/SA<br> + <a href="http://www.belsign.be"> + http://www.belsign.be + </a> + </ul> + <p> + Second you can use your own CA and now have to sign the CSR yourself by + this CA. Read the next answer in this FAQ on how to sign a CSR with + your CA yourself. + You can see the details of the received Certificate via the command: + <p> + <code><strong>$ ssleay x509 -noout -text -in server.crt</strong></code> + <p> + <li>Now you have two files: <code>server.key</code> and + <code>server.crt</code>. These now can be used as following inside your + Apache's <code>httpd.conf</code> file: + <pre> + SSLCertificateFile /path/to/this/server.crt + SSLCertificateKeyFile /path/to/this/server.key + </pre> + The <code>server.csr</code> file is no longer needed. + </ol> +<p> +<li><a name="ToC20"></a> + <a name="cert-ownca"></a> + <strong id="faq">How can I create and use my own Certificate Authority (CA)?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#cert-ownca"><b>L</b></a>] + <p> + The short answer is to use the <code>CA.sh</code> script provided by SSLeay. + The long and manual answer is this: + <p> + <ol> + <li> Create a RSA private key for your CA + (will be Triple-DES encrypted and PEM formatted): + <p> + <code><strong>$ ssleay genrsa -des3 -out ca.key 1024</strong></code> + <p> + Please backup this <code>ca.key</code> file and remember the + pass-phrase you currently entered at a secure location. + You can see the details of this RSA private key via the command + <p> + <code><strong>$ ssleay rsa -noout -text -in ca.key</strong></code> + <p> + And you can create a decrypted PEM version (not recommended) of this + private key via: + <p> + <code><strong>$ ssleay rsa -in ca.key -out ca.key.unsecure</strong></code> + <p> + <li>Create a self-signed CA Certificate (X509 structure) + for the RSA key of the CA (output will be PEM formatted): + <p> + <code><strong>$ ssleay req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code> + <p> + You can see the details of this Certificate via the command: + <p> + <code><strong>$ ssleay x509 -noout -text -in ca.crt</strong></code> + <p> + <li>Prepare a script for signing which is needed because + the ``<code>ssleay ca</code>'' command has some strange requirements + and the default SSLeay config doesn't allow one easily to use + ``<code>ssleay ca</code>'' directly. So a script named + <code>sign.sh</code> is distributed with the mod_ssl distribution + (subdir <code>pkg.contrib/</code>). Use this script for signing. + <p> + <li>Now you can use this CA to sign CSR's in order to create real + SSL Certificates for use inside an Apache webserver: + <p> + <code><strong>$ ./sign.sh server.csr</strong></code> + <p> + This signs the CSR and results in a <code>server.crt</code> file. + </ol> +<p> +<li><a name="ToC21"></a> + <a name="change-passphrase"></a> + <strong id="faq">How can I change the pass-phrase on my private key file?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#change-passphrase"><b>L</b></a>] + <p> + You simply have to read it with the old pass-phrase and write it again + by specifying the new pass-phrase. You can accomplish this with the following + commands: + <p> + <code><strong>$ ssleay rsa -des3 -in server.key -out server.key.new</strong></code><br> + <code><strong>$ mv server.key.new server.key</strong></code><br> + <p> + Here you're asked two times for a PEM pass-phrase. At the first + prompt enter the old pass-phrase and at the second prompt + enter the new pass-phrase. +<p> +<li><a name="ToC22"></a> + <a name="remove-passphrase"></a> + <strong id="faq">How can I get rid of the pass-phrase dialog at Apache startup time?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#remove-passphrase"><b>L</b></a>] + <p> + The reason why this dialog pops up at startup and every re-start + is that the RSA private key inside your server.key file is stored in + encrypted format for security reasons. The pass-phrase is needed to be + able to read and parse this file. When you can be sure that your server is + secure enough you perform two steps: + <p> + <ol> + <li>Remove the encryption from the RSA private key (while + preserving the original file): + <p> + <code><strong>$ cp server.key server.key.org</strong></code><br> + <code><strong>$ ssleay rsa -in server.key.org -out server.key</strong></code> + <p> + <li>Make sure the server.key file is now only readable by root: + <p> + <code><strong>$ chmod 400 server.key</strong></code> + </ol> + <p> + Now <code>server.key</code> will contain an unencrypted copy of the key. + If you point your server at this file it will not prompt you for a + pass-phrase. HOWEVER, if anyone gets this key they will be able to + impersonate you on the net. PLEASE make sure that the permissions on that + file are really such that only root or the web server user can read it + (preferably get your web server to start as root but run as another + server, and have the key readable only by root). +<p> +<li><a name="ToC23"></a> + <a name="verify-key"></a> + <strong id="faq">How do I verify that a private key matches its Certificate?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#verify-key"><b>L</b></a>] + <p> + The private key contains a series of numbers. Two of those numbers form + the "public key", the others are part of your "private key". The "public + key" bits are also embedded in your Certificate (we get them from your + CSR). To check that the public key in your cert matches the public + portion of your private key, you need to view the cert and the key and + compare the numbers. To view the Certificate and the key run the + commands: + <p> + <code><strong>$ ssleay x509 -noout -text -in server.crt</strong></code><br> + <code><strong>$ ssleay rsa -noout -text -in server.key</strong></code> + <p> + The `modulus' and the `public exponent' portions in the key and the + Certificate must match. But since the public exponent is usually 65537 + and it's bothering comparing long modulus you can use the following + approach: + <p> + <code><strong>$ ssleay x509 -noout -modulus -in server.crt | ssleay md5</strong></code><br> + <code><strong>$ ssleay rsa -noout -modulus -in server.key | ssleay md5</strong></code> + <p> + And then compare these really shorter numbers. With overwhelming + probability they will differ if the keys are different. BTW, if I want to + check to which key or certificate a particular CSR belongs you can compute + <p> + <code><strong>$ ssleay req -noout -modulus -in server.csr | ssleay md5</strong></code> +<p> +<li><a name="ToC24"></a> + <a name="keysize"></a> + <strong id="faq">Why does my 2048-bit private key not work?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#keysize"><b>L</b></a>] + <p> + The private key sizes for SSL must be either 512 or 1024 for compatibility + with certain web browsers. A keysize of 1024 bits is recommended because + keys larger than 1024 bits are incompatible with some versions of Netscape + Navigator and Microsoft Internet Explorer, and with other browsers that + use RSA's BSAFE cryptography toolkit. +<p> +<li><a name="ToC25"></a> + <a name="hash-symlinks"></a> + <strong id="faq">Why is client authentication broken after upgrading from +SSLeay version 0.8 to 0.9?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#hash-symlinks"><b>L</b></a>] + <p> + The CA certificates under the path you configured with + <code>SSLCACertificatePath</code> are found by SSLeay through hash + symlinks. These hash values are generated by the `<code>ssleay x509 -noout + -hash</code>' command. But the algorithm used to calculate the hash for a + certificate has changed between SSLeay 0.8 and 0.9. So you have to remove + all old hash symlinks and re-create new ones after upgrading. Use the + <code>Makefile</code> mod_ssl placed into this directory. +</ul> +<p> +<br> +<H2><a name="ToC26">About SSL Protocol</a></H2> +<ul> +<p> +<li><a name="ToC27"></a> + <a name="load"></a> + <strong id="faq">Why has my webserver a higher load now that I run SSL there?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#load"><b>L</b></a>] + <p> + Because SSL uses strong cryptographic encryption and this needs a lot of + number crunching. And because when you request a webpage via HTTPS even + the images are transfered encrypted. So, when you have a lot of HTTPS + traffic the load increases. +<p> +<li><a name="ToC28"></a> + <a name="ciphers"></a> + <strong id="faq">What SSL Ciphers are supported by mod_ssl?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#ciphers"><b>L</b></a>] + <p> + Usually just all SSL ciphers which are supported by the + version of SSLeay in use (can depend on the way you built + SSLeay). Typically this at least includes the following: + <p> + <ul> + <li>RC4 with MD5 + <li>RC4 with MD5 (export version restricted to 40-bit key) + <li>RC2 with MD5 + <li>RC2 with MD5 (export version restricted to 40-bit key) + <li>IDEA with MD5 + <li>DES with MD5 + <li>Triple-DES with MD5 + </ul> + <p> + To determine the actual list of supported ciphers you can + run the following command: + <p> + <code><strong>$ ssleay ciphers -v</strong></code><br> +<p> +<li><a name="ToC29"></a> + <a name="vhosts"></a> + <strong id="faq">Why can't I use SSL with name-based/non-IP-based virtual hosts?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#vhosts"><b>L</b></a>] + <p> + The reason is very technical. Actually it's some sort of a chicken and + egg problem: The SSL protocol layer stays below the HTTP protocol layer + and encapsulates HTTP. When an SSL connection (HTTPS) is established + Apache/mod_ssl has to negotiate the SSL protocol parameters with the + client. For this mod_ssl has to consult the configuration of the virtual + server (for instance it has to look for the cipher suite, the server + certificate, etc.). But in order to dispatch to the correct virtual server + Apache has to know the <code>Host</code> HTTP header field. For this the + HTTP request header has to be read. This cannot be done before the SSL + handshake is finished. But the information is already needed at the SSL + handshake phase. Bingo! +<p> +<li><a name="ToC30"></a> + <a name="lock-icon"></a> + <strong id="faq">When I use Basic Authentication over HTTPS the lock icon in Netscape browsers +still show the unlocked state when the dialog pops up. Does this mean the +username/password is still transmitted unencrypted?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#lock-icon"><b>L</b></a>] + <p> + No, the username/password is already transmitted encrypted. The icon in + Netscape browsers is just not really synchronized with the SSL/TLS layer + (it toggles to the locked state when the first part of the actual webpage + data is transferred which is not quite correct) and this way confuses + people. The Basic Authentication facility is part of the HTTP layer and + this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data + communication takes place in HTTPS the SSL/TLS layer has already done the + handshake phase and switched to encrypted communication. So, don't get + confused by this icon. +</ul> +<p> +<br> +<H2><a name="ToC31">About Support</a></H2> +<ul> +<p> +<li><a name="ToC32"></a> + <a name="resources"></a> + <strong id="faq">What information resources are available in case of mod_ssl problems?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#resources"><b>L</b></a>] + <p> +The following information resources are available. +In case of problems you should search here first. +<p> +<ol> +<li><em>Answers in the User Manual's F.A.Q. List (this)</em><br> + <a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html"> + http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html</a><br> + First look inside the F.A.Q. (this text), perhaps your problem is such + popular that it was already answered a lot of times in the past. +<p> +<li><em>Postings from the sw-mod-ssl Support Mailing List</em> + <a href="http://www.engelschall.com/sw/mod_ssl/news/list.html"> + http://www.engelschall.com/sw/mod_ssl/news/list.html</a><br> + Second search for your problem in one of the existing archives of the + sw-mod-ssl mailing list. Perhaps your problem popped up at least once for + another user, too. +<p> +<li><em>Problem Reports in the Bug Database</em> + <a href="http://www.engelschall.com/sw/mod_ssl/bugdb/"> + http://www.engelschall.com/sw/mod_ssl/bugdb/</a><br> + Third look inside the mod_ssl Bug Database. Perhaps + someone else already has reported the problem. +</ol> +<p> +<li><a name="ToC33"></a> + <a name="contact"></a> + <strong id="faq">What support contacts are available in case of mod_ssl problems?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#contact"><b>L</b></a>] + <p> +The following lists all support possibilities for mod_ssl, in order of +preference, i.e. start in this order and do not pick the support possibility +you just like most, please. +<p> +<ol> +<li><em>Write a Problem Report into the Bug Database</em><br> + <a href="http://www.engelschall.com/sw/mod_ssl/bugdb/"> + http://www.engelschall.com/sw/mod_ssl/bugdb/</a><br> + This is the preferred way of submitting your problem report, because this + way it gets filed into the bug database (it cannot be lost) <em>and</em> + send to the sw-mod-ssl mailing list (others see the current problems and + learn from answers). +<p> +<li><em>Write a Problem Report to the sw-mod-ssl Support Mailing List</em><br> + <a href="mailto:sw-mod-ssl@engelschall.com"> + sw-mod-ssl @ engelschall.com</a><br> + This is the second way of submitting your problem report. You have to + subscribe to the list first, but then you can easily discuss your problem + with both the author and the whole mod_ssl user community. +<p> +<li><em>Write a Problem Report to the author</em><br> + <a href="mailto:rse@engelschall.com"> + rse @ engelschall.com</a><br> + This is the last way of submitting your problem report. Please avoid this + in your own interest because the author is really a very busy men. Your + mail will always be filed to one of his various mail-folders and is + usually not processed as fast as a posting on sw-mod-ssl. +</ol> +<p> +<li><a name="ToC34"></a> + <a name="report-details"></a> + <strong id="faq">What information and details I've to provide to +the author when writing a bug report?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#report-details"><b>L</b></a>] + <p> +You have to at least always provide the following information: +<p> +<ul> +<li><em>Apache, mod_ssl and SSLeay version information</em><br> + The mod_ssl version you should really know. It's for instance the version + number in the distribution tarball. The Apache version can be determined + by running ``<code>httpd -v</code>''. The SSLeay version can be + determined by running ``<code>ssleay version</code>''. Alternatively when + you have Lynx installed you can run the command ``<code>lynx -mime_header + http://localhost/ | grep Server</code>'' to determine all information in a + single step. +<p> +<li><em>The details on how you built and installed Apache+mod_ssl+SSLeay</em><br> + For this you can provide a logfile of your terminal session which shows + the configuration and install steps. Alternatively you can at least + provide the author with the APACI `<code>configure</code>'' command line + you used (assuming you used APACI, of course). +<p> +<li><em>In case of core dumps please include a Backtrace</em><br> + In case your Apache+mod_ssl+SSLeay should really dumped core please attach + a stack-frame ``backtrace'' (see the next question on how to get it). + Without this information the reason for your core dump cannot be found. + So you have to provide the backtrace, please. +<p> +<li><em>A detailed description of your problem</em><br> + Don't laugh, I'm totally serious. I already got a lot of problem reports + where the people not really said what's the actual problem is. So, in your + own interest (you want the problem be solved, don't you?) include as much + details as possible, please. But start with the essentials first, of + course. +</ul> +<p> +<li><a name="ToC35"></a> + <a name="report-backtrace"></a> + <strong id="faq">Ok, I got a core dump but how do I get a backtrace to find out the reason for it?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#report-backtrace"><b>L</b></a>] + <p> +Follow the following steps: +<p> +<ol> +<li>Make sure you have debugging symbols available in at least + Apache and mod_ssl. On platforms where you use GCC/GDB you have to build + Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On + other platforms at least ``<code>OPTIM="-g"</code>'' is needed. +<p> +<li>Startup the server and try to produce the core-dump. For this you perhaps + want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to + make sure that the core-dump file can be written. You then should get a + <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you + don't get this, try to run your server under an UID != 0 (root), because + some kernels don't write (for security reasons) core-dumps for + root-processes. Additionally you can run ``<code>/path/to/httpd -X</code>'' + manually to force Apache not not fork. +<p> +<li>Analyze the core-dump. For this run ``<code>gdb /path/to/httpd + /tmp/httpd.core</code>'' or a similar command has to run. In GDB you then + just have to enter the ``<code>bt</code>'' command and, voila, you get the + backtrace. For other debuggers consult your local debugger manual. Send + this backtrace to the author. +</ol> +</ul> + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_howto.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">HowTo</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_glossary.html" + onMouseOver="ro_imgOver('ro_img_next_bot', 'next page'); return true" + onMouseOut="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">Glossary</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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.wml new file mode 100644 index 00000000000..73c66bfb4ff --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_faq.wml @@ -0,0 +1,1012 @@ + +#use "ssl_template.inc" title="F.A.Q." tag=faq num=6 + +<page_prev name="HowTo" url="ssl_howto.html"> +<page_next name="Glossary" url="ssl_glossary.html"> + +#use wml::std::toc style=nbsp + +<quotation width=200 author="Claude Levi-Strauss"> +``The wise man doesn't give the right answers, +he poses the right questions.'' +</quotation> + +<p> +<table cellspacing=0 cellpadding=0 border=0> +<tr valign=bottom> +<td> + +<big T>his chapter is a collection of frequently asked questions (FAQ) and +corresponding answers following the popular USENET tradition. Most of these +questions occured on the Newsgroup <a +href="news:comp.infosystems.www.servers.unix"> +<code>comp.infosystems.www.servers.unix</code></a> or the mod_ssl Support +Mailing List <a href="mailto:sw-mod-ssl@engelschall.com"> +<code>sw-mod-ssl@engelschall.com</code></a>. They are collected at this place +to avoid answering the same questions over and over. + +<p> +Please read this chapter at least once when installing mod_ssl or at least +search for your problem here before submitting a problem report to the +author. + +</td> +<td> + +</td> +<td> + +<div align=right> +<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff" width=300> +<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> +<toc> +</font> +</td> +</tr> +</table> +</div> + +</td> +</tr> +</table> + +# container tag for layouting a question +<define-container faq> +<preserve ref> +<preserve toc> +<set-var %attributes> +<p> +<li><toc_h3 <get-var toc>></toc_h3> + <a name="<get-var ref>"></a> + <strong id="faq">%body</strong>\ + + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html#<get-var ref>"><b>L</b></a>] + <p> +<restore toc> +<restore ref> +</define-container> + + +<h2>About the module</h2> + +<ul> + +<faq ref="apssl-diff" toc="Apache-SSL vs. mod_ssl: difference?"> +What are the differences between mod_ssl and Apache-SSL, from where it is derived? +</faq> + + This cannot be answered in short, because there are too much changes (see + the <code>CHANGES</code> and <code>CHANGES.20</code> files in the mod_ssl + distribution for detailed information). Most of them are internal changes, + cleanups and re-organizations of the source code. But the user visible + changes are mainly the following: + <p> + <ul> + <li><em>mod_ssl provides a complete documentation</em> (this User Manual) + where all configuration directives, environment variables, and other + things are documented while Apache-SSL had no such documentation + although it existed for over three years when mod_ssl was split from + it (in April 1998). Additionally mod_ssl provides answers to often + occuring frequently asked questions (this list) in the + Apache/SSL/SSLeay area. For instance mod_ssl gives detailed hints + about how to setup a CA, how to create real a server Certificate, etc. + And the mod_ssl User Manual provides a compact introduction to the + complex SSL area itself. Because here are the typical hurdles located + every user stumbles over. + <p> + <li><em>mod_ssl comes with clean and documented source code</em> with the + intent that only this way the user is able to re-view it for + backdoors, security holes, etc. This is considered important for + security-related software. It was always incomprehensible to the + author of mod_ssl how Apache-SSL could exist for over three years + while both the source code and the source patches were provided in an + undocumented and partly unreadable format. For the mod_ssl package + the source codes follows the Apache coding style, is logically + ordered to follow the API phases and even the patches to the + Apache source tree are annotated with descriptions to give the + user a chance to re-view and understand them. + <p> + <li><em>mod_ssl uses a generic Extended API</em> to achieve + its functionality. This means instead of patching in + SSL/crypto-related code into the Apache kernel a clean and well + separated Extended API is patched in. This way the SSL and + cryptography code is <em>only</em> present inside the SSL module + itself (i.e. inside the <code>src/modules/ssl/</code> subtree only). + The benefit from this is a clean separation and API-conforming SSL + solution (which means for instance no direct SSL-references from the + kernel, no kludges and hacks to get called, etc). + <p> + <li><em>mod_ssl supports Dynamic Shared Object (DSO) building</em> + as a direct consequence from using the Extended API. In short DSO + support means maximum flexibility under run-time, i.e. you don't have + to decide under compile-time whether to build or not to build SSL into + the Apache httpd executable. Instead you can just load mod_ssl through + mod_so's <code>LoadModule</code> directive <em>on demand</em>. This + is especially interesting for two cases: Vendor package maintainers + receive the power they need for creating flexible packages and power + users receive the ability to run more than one Apache (non-SSL-aware + and SSL-aware) instance from a single Apache installation while still + saving RAM. + <p> + <li><em>mod_ssl is ported to the Win32 platform</em>, + as it's the case for Apache and SSLeay. This way mod_ssl follows the + evolution of these packages and provides the always requested support + also for this nasty platform. As for the Unix/DSO case under Win32 + mod_ssl is well-integrated into Apache through a stand-alone DLL which + can be loaded through mod_so's <code>LoadModule</code> directive. + <p> + <li><em>mod_ssl can be really easily applied to the Apache source tree</em> because + it provides a full-featured and automated configuration environment + for this task while Apache-SSL forced the user to fiddle with the + <code>patch</code> and <code>cp</code> tools theirself. Just + because security is not for amateurs hasn't to mean that user + friendliness is not important. So it's a must to assist the user + in applying the SSL-stuff to vanilla Apache sources. For this + mod_ssl integrates also very-well into the new Apache 1.3 + Autoconf-style Interface (APACI). Additionally mod_ssl's + configuration mechanism supports the usage of RSAref, arbitrary + locations for SSLeay, etc. + <p> + <li><em>mod_ssl fixes a lot of bugs and inconsistencies</em> which + existed in Apache-SSL. For Apache experts here are a few impressions: + Apache-SSL wrote directly to <code>stderr</code> instead of the Apache + error logfile; it messed up it's error messages with the SSLeay error + messages; it directly patched the <code>SERVER_BASEVERSION</code> + define instead of using the Apache 1.3 conforming + <code>ap_add_version_component</code> function; it used the unsafe + <code>sprintf</code> function instead of the robust + <code>ap_snprintf</code>; it incorrectly spawned and killed the + <code>gcache</code> auxiliary program and it totally failed to pass the + ``<code>gcc -Wall -Wshadow -Wpointer-arith -Wcast-align + -Wmissing-prototypes -Wmissing-declarations -Wnested-externs + -Winline</code>'' test (while Apache already passes it) because of + unclean code. + <p> + Additionally Apache-SSL didn't provide a way to easily apply it to + the Apache source tree (semi-manual editing and patching was + required); it didn't seamlessly integrate into the new Apache 1.3 + Autoconf-style Interface (APACI) at configuration time; it didn't + automatically recognize the difference between an installed SSLeay and + an out-of-the-source-only SSLeay; it didn't provide integration into + the APACI installation process (<code>make install</code>); it used + numbers 0 to 2 instead of reasonable names for the argument of + <code>SSLVerifyClient</code> just because internally an + <code>enum</code> was used and for the provided + <code>%{version}c</code> construct of CustomLog it used the results + "2", "3" under SSLeay 0.8 while under SSLeay 0.9 the results were + "SSL2", "SSL3", etc. pp. + <p> + <li><em>mod_ssl adds new functionalities which were missing in + Apache-SSL</em>. A few selected points which give you an impression + follow: + <ul> + <li>mod_ssl provides a real dedicated SSL log file controlled by log + level and the additional features that messages logged at the + `error' level are automatically duplicated to the general Apache + error log file. And occuring system and SSLeay error messages are + automatically appended to mod_ssl messages. Additionally mod_ssl + annotates deep-level SSLeay messages with more high-level hints. + <li>mod_ssl provides a completely new and enhanced handling + of encrypted private key files. First the private keys are kept in + a permanent memory pool (as SSLeay already does internally), so + Apache now survives server restarts without falling down. Second + the pass phrase dialog is a lot more user friendly and advanced: + It uses a pass phrase reuse-algorithm to minimize the dialog, it + recognizes wrong pass phrases and allows retries (but with a + backoff time delay), etc. And additionally a minimal interface is + provided to plug-in an external program for providing the pass + phrase for special batch security situations. + <li>mod_ssl provides the <code>SSLCACertificateReqFile</code> + directive which can be used to configure a different (from + <code>SSLCACertificateFile</code>) set of CA Certificates for the + SSLv3 feature used by the clients to load CA Certificates from the + server for speeding up server authentication. + <li>mod_ssl replaced the ``gcache'' stuff of Apache-SSL (used for + caching SSL sessions) with a more robust DBM-based solution, + because the controlling of an external program cannot be done very + reliable from within Apache. Additionally a "mutex" is now used to + synchronize the inter-process access to this cache. + <li>mod_ssl provides support for the SSLeay+RSAref couple, i.e. + mod_ssl supports the building with RSAref. + <li>mod_ssl provides a new SSLRequire directive which can be used + to implement more granular access control based on arbitrary + complex boolean expression. + <li>mod_ssl adds support for HTTPS to the Apache Proxy Module + (mod_proxy). + <li>mod_ssl is the first Open Source version of an SSL + extension to Apache which supports the Win32 platform. + <li>etc.pp. + </ul> + </ul> + <p> + When you're still really interested in more hard-core details walk through + the entries in the <code>CHANGES</code> and <code>CHANGES.20</code> files + in the mod_ssl distribution. + +<faq ref="apssl-avoid" toc="Should Apache-SSL be avoided?"> +Ok, does this mean I should avoid using Apache-SSL from now on? +</faq> + + <strong>No</strong>, it just means that you <em>can</em> use mod_ssl. + Beside the well-known flaws Apache-SSL works great. Ben Laurie did and + still does a great job in maintaining it. The big difference is just that + Ben Laurie's goals are different from Ralf S. Engelschall's goals. So, as + long as you don't get bothered by inconsistencies and other flaws you + don't have to upgrade. Instead you should decide yourself if you already + feel comfortable or not. If yes, stay with Apache-SSL - if not, move to + mod_ssl or (even better) one of the commercial SSL solutions for Apache. + Or in other words: No solution is better than another in general. Which + one you should use depends mainly on your personal requirements. + +<faq ref="apssl-baseversion" toc="Which Apache-SSL version is the base?"> +On which Apache-SSL version is mod_ssl actually based? +</faq> + + The mod_ssl package was initially created by porting the Apache-SSL 1.17 + stuff from Apache 1.2.6 to Apache 1.3b6 in April 1998. Because of + conflicts with Ben Laurie's development cycle it then was re-assembled + from scratch for Apache 1.3.0 by merging the old mod_ssl with the newer + Apache-SSL 1.18. From this point mod_ssl lived its own life and changes + with Apache-SSL releases were merged after they were released. In other + words: mod_ssl is based on the latest Apache-SSL and always will contain + all useful changes which will occur with Apache-SSL in the future. + +<faq ref="why200" toc="Why starting with version 2.0.0?"> +Why is mod_ssl's version starting with 2.0.0? +</faq> + + Because initially the mod_ssl project was intended as a contribution to + the Apache-SSL project from Ben Laurie. The idea was that mod_ssl formed + Apache-SSL 2.0.0. But after Ralf S. Engelschall and Ben Laurie couldn't + find a reasonable compromise in merging mod_ssl with Apache-SSL, the stuff + was released as a new package named ``mod_ssl''. But to still indicate + that it's some ``second generation'' stuff, the first mod_ssl version was + named 2.0.0. + +<faq ref="what-version" toc="mod_ssl/Apache versions?"> +How do I know which mod_ssl version is for which Apache version? +</faq> + + That's trivial: mod_ssl uses version strings of the syntax + <em><mod_ssl-version></em>-<em><apache-version></em>, for + instance <code>2.2.0-1.3.4</code>. This directly indicates that it's + mod_ssl version 2.2.0 for Apache version 1.3.4. And this also means you + <em>only</em> can apply this mod_ssl version to exactly this Apache + version (unless you use the <code>--force</code> option to mod_ssl's + <code>configure</code> command ;-). + +<faq ref="y2k" toc="mod_ssl and Year 2000?"> +Is mod_ssl Year 2000 compliant? +</faq> + + Yes, mod_ssl is Year 2000 compliant. + + <p> + Because first mod_ssl internally never stores years as two digits. + Instead it always uses the ANSI C & POSIX numerical data type + <code>time_t</code> type, which on mostly all Unix platforms at the moment + is a <code>signed long</code> (usually 32-bits) representing seconds since + epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in + early January 2038 and not in the year 2000. Second, date and time + presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'') + are done with full year value instead of abbreviating to two digits. + + <p> + Additionally according to a <a + href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000 + statement</a> from the Apache Group, the Apache webserver is Year 2000 + compliant, too. But whether SSLeay or the underlaying Operating System + (either a Unix or Win32 platform) is Year 2000 compliant is a different + question which cannot be answered here. + +<faq ref="wassenaar" toc="mod_ssl and Wassenaar Arrangement?"> +What about mod_ssl and the Wassenaar Arrangement? +</faq> + + First, let us explain what <i>Wassenaar</i> and it's <i>Arrangement on + Export Controls for Conventional Arms and Dual-Use Goods and + Technologies</i> is: This is a international regime, established 1995, to + control trade in conventional arms and dual-use goods and technology. It + replaced the previous <i>CoCom</i> regime. 33 countries are signatories: + Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, + Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, + Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic + of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, + Switzerland, Turkey, Ukraine, United Kingdom and United States. For more + details look at <a + href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>. + + <p> + In short: The aim of the Wassenaar Arrangement is to prevent the build up + of military capabilities that threaten regional and international security + and stability. The Wassenaar Arrangement controls the export of + cryptography as a dual-use good, i.e., one that has both military and + civilian applications. However, the Wassenaar Arrangement also provides an + exemption from export controls for mass-market software and free software. + + <p> + In the current Wassenaar ``<i>List of Dual Use Goods and Technologies And + Munitions</i>'', under ``<i>GENERAL SOFTWARE NOTE</i>'' (GSN) it says + ``<i>The Lists do not control "software" which is either: 1. [...] 2. "in + the public domain".</i>'' And under ``<i>DEFINITIONS OF TERMS USED IN + THESE LISTS</i>'' one can find the definition: ``<i>"In the public + domain": This means "technology" or "software" which has been made + available without restrictions upon its further dissemination. N.B. + Copyright restrictions do not remove "technology" or "software" from being + "in the public domain".</i>'' + + <p> + So, both mod_ssl and SSLeay are ``in the public domain'' for the purposes + of the Wassenaar Agreement and its ``<i>List of Dual Use Goods and + Technologies And Munitions List</i>''. + + <p> + Additionally the Wassenaar Agreement itself has no direct consequence for + exporting cryptography software. What is actually allowed or forbidden to + be exported from the countries has still to be defined in the local laws + of each country. And at least according to official press releases from + the German BMWi (see <a + href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the + Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there + will be no forthcoming export restriction for free cryptography software + for their countries. Remember that mod_ssl is created in Germany and + distributed from Switzerland. + + <p> + So, mod_ssl and SSLeay are not affected by the Wassenaar Agreement. + +</ul> + +<p> +<br> +<h2>About Configuration</h2> + +<ul> + +<faq ref="https-parallel" toc="HTTP and HTTPS on same machine?"> +I want to run HTTP and HTTPS on the same machine. Is that possible?</strong> +</faq> + + Yes, there are two ways to do this: run two server instances, or run both + services from the same server instance. Unless there is a good reason to + run two (like using a different product for HTTP and HTTPS), it's usually + most simples to run a single instance where you enable SSL only for those + virtual hosts that need it. If you wish to run two server instances you + must make sure that they each only try to bind to their allowed ports + (normally port 80 for HTTP and 443 for HTTPS). + +<faq ref="https-port" toc="Where is the HTTPS port?"> +I know that HTTP is on port 80, but where is HTTPS? +</faq> + + You can run HTTPS on any port, but the standards specify port 443, which + is where any HTTPS compliant browser will look by default. You can force + your browser to look on a different port by specifying it in the URL like + this (for port 666): <code>https://secure.server.dom:666/</code> + +<faq ref="https-test" toc="How to test HTTPS manually?"> +How can I speak HTTPS manually for testing purposes? +</faq> + + While you usually just use + <p> + <code><b>$ telnet localhost 80</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + for simple testing the HTTP protocol of Apache, it's not such easy for + HTTPS because of the SSL protocol between TCP and HTTP. But with the + help of SSLeay's <code>s_client</code> program you can do a similar + check even for HTTPS: + <p> + <code><b>$ s_client -connect localhost:443 -state -debug</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + Before the actual HTTP response you receive detailed information about the + SSL handshake. For a more general command line client which directly + understands both the HTTP and HTTPS scheme, can perform GET and POST + methods, can use a proxy, supports byte ranges, etc. you should have a + look at nifty <a href="http://www.fts.frontec.se/~dast/curl/">cURL</a> + tool. With it you can directly check if your Apache is running fine on + Port 80 and 443 as following: + <p> + <code><b>$ curl http://localhost/</b></code><br> + <code><b>$ curl https://localhost/</b></code><br> + +<faq ref="hang" toc="Why does my browser hang?"> +Why does my browser hang when I connect to my SSL-aware Apache server? +</faq> + + Because you used an URL of the form ``<code>http://</code>'' instead of + ``<code>https:</code>''. Really! Also, if you see: ``<code>SSL_Accept + failed error:140760EB:SSL routines: SSL23_GET_CLIENT_HELLO:unknown + protocol</code>'' in your Apache error logfile, it's for the same reason. + This also happens the other way round, i.e. when you try to use + ``<code>https://</code>'' on a server that doesn't support SSL (on this + port). Make sure you are connecting to a virtual server that supports + SSL, which is probably the IP associated with your hostname, not localhost + (127.0.0.1). + +<faq ref="relative-links" toc="How to switch with relative hyperlinks?"> +How can I use relative hyperlinks to switch between HTTP and HTTPS? +</faq> + + Usually you have to use fully-qualified hyperlinks because + you have to change the URL scheme. But with the help of some URL + manipulations through mod_rewrite you can achieve the same effect while + you still can use relative URLs: + + <pre> + RewriteEngine on + RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L] + RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L] + </pre> + + This rewrite ruleset lets you use hyperlinks of the form + + <pre> + <a href="document.html:SSL"> + </pre> + +</ul> + +<p> +<br> +<h2>About Certificates</h2> + +<ul> + +<faq ref="what-is" toc="What are Keys, CSRs and Certs?"> +What are RSA Private Keys, CSRs and Certificates?</strong> +</faq> + + The RSA private key file is a digital file that you can use to decrypt + messages sent to you. It has a public component which you distribute (via + your Certificate file) which allows people to encrypt those messages to + you. A Certificate Signing Request (CSR) is a digital file which contains + your public key and your name. You send the CSR to a Certifying Authority + (CA) to be converted into a real Certificate. A Certificate contains your + RSA public key, your name, the name of the CA, and is digitally signed by + your CA. Browsers that know the CA can verify the signature on that + Certificate, thereby obtaining your RSA public key. That enables them to + send messages which only you can decrypt. + See the <a href="ssl_intro.html">Introduction</a> chapter for a general + description of the SSL protocol. + +<faq ref="startup" toc="Difference on startup?"> +Seems like there is a difference on startup between the original Apache and an SSL-aware Apache? +</faq> + + Yes, in general, starting Apache with a built-in mod_ssl is just like + starting an unencumbered Apache, except for the fact that when you have a + pass phrase on your SSL private key file. Then a startup dialog pops up + asking you to enter the pass phrase. + <p> + To type in the pass phrase manually when starting the server can be + problematic, for instance when starting the server from the system boot + scripts. As an alternative to this situation you can follow the steps + below under ``How can I get rid of the pass-phrase dialog at Apache + startup time?''. + +<faq ref="cert-dummy" toc="How to create a dummy cert?"> +How can I create a dummy SSL server Certificate for testing purposes? +</faq> + + A Certificate does not have to be signed by a public CA. You can use your + private key to sign the Certificate which contains your public key. You + can install this Certificate into your server, and people using Netscape + Navigator (not MSIE) will be able to connect after clicking OK to a + warning dialogue. You can get MSIE to work, and your customers can + eliminate the dialogue, by installing that Certificate manually into their + browsers. + <p> + Just use the ``<code>make certificate</code>'' command at the top-level + directory of the Apache source tree right before installing Apache via + ``<code>make install</code>''. This creates a self-signed SSL Certificate + which expires after 30 days and isn't encrypted (which means you don't + need to enter a pass-phrase at Apache startup time). + <p> + BUT REMEMBER: YOU REALLY HAVE TO CREATE A REAL CERTIFICATE FOR THE LONG + RUN! HOW THIS IS DONE IS DESCRIBED IN THE NEXT ANSWER. + +<faq ref="cert-real" toc="How to create a real cert?"> +Ok, I've got my server installed and want to create a real SSL +server Certificate for it. How do I do it? +</faq> + + Here is a step-by-step description: + <p> + <ol> + <li>Make sure SSLeay is really installed and in your <code>PATH</code>. + But some commands even work ok when you just run the + ``<code>ssleay</code>'' program from within the SSLeay source tree as + ``<code>./apps/ssleay</code>''. + <p> + <li>Create a RSA private key for your Apache server + (will be Triple-DES encrypted and PEM formatted): + + <p> + <code><strong>$ ssleay genrsa -des3 -out server.key 1024</strong></code> + + <p> + Please backup this <code>server.key</code> file and remember the + pass-phrase you had to enter at a secure location. + You can see the details of this RSA private key via the command: + + <p> + <code><strong>$ ssleay rsa -noout -text -in server.key</strong></code> + + <p> + And you could create a decrypted PEM version (not recommended) + of this RSA private key via: + + <p> + <code><strong>$ ssleay rsa -in server.key -out server.key.unsecure</strong></code> + + <p> + <li>Create a Certificate Signing Request (CSR) for the server RSA private + key (output will be PEM formatted): + + <p> + <code><strong>$ ssleay req -new -days 365 -key server.key -out server.csr</strong></code> + + <p> + You can see the details of this CSR via the command + + <p> + <code><strong>$ ssleay req -noout -text -in server.csr</strong></code> + + <p> + <li>You now have to send this Certificate Signing Request (CSR) to + a Certifying Authority (CA) for signing. The result is then a real + Certificate which can be used for Apache. Here you have to options: + + First you can let the CSR sign by a commercial CA like Verisign or + Thawte. Then you usually have to post the CSR into a web form, pay for + the signing and await the signed Certificate you then can store into a + server.crt file. For more information about commercial CAs have a look + at the following locations: + + <p> + <ul> + <li> Verisign<br> + <a href="http://digitalid.verisign.com/server/apacheNotice.htm"> + http://digitalid.verisign.com/server/apacheNotice.htm + </a> + <li> Thawte Consulting<br> + <a href="http://www.thawte.com/certs/server/request.html"> + http://www.thawte.com/certs/server/request.html + </a> + <li> CertiSign Certificadora Digital Ltda.<br> + <a href="http://www.certisign.com.br"> + http://www.certisign.com.br + </a> + <li> IKS GmbH<br> + <a href="http://www.iks-jena.de/produkte/ca/"> + http://www.iks-jena.de/produkte/ca/ + </a> + <li> Uptime Commerce Ltd.<br> + <a href="http://www.uptimecommerce.com"> + http://www.uptimecommerce.com + </a> + <li> BelSign NV/SA<br> + <a href="http://www.belsign.be"> + http://www.belsign.be + </a> + </ul> + + <p> + Second you can use your own CA and now have to sign the CSR yourself by + this CA. Read the next answer in this FAQ on how to sign a CSR with + your CA yourself. + + You can see the details of the received Certificate via the command: + + <p> + <code><strong>$ ssleay x509 -noout -text -in server.crt</strong></code> + + <p> + <li>Now you have two files: <code>server.key</code> and + <code>server.crt</code>. These now can be used as following inside your + Apache's <code>httpd.conf</code> file: + + <pre> + SSLCertificateFile /path/to/this/server.crt + SSLCertificateKeyFile /path/to/this/server.key + </pre> + + The <code>server.csr</code> file is no longer needed. + </ol> + +<faq ref="cert-ownca" toc="How to create my own CA?"> +How can I create and use my own Certificate Authority (CA)? +</faq> + + The short answer is to use the <code>CA.sh</code> script provided by SSLeay. + The long and manual answer is this: + + <p> + <ol> + <li> Create a RSA private key for your CA + (will be Triple-DES encrypted and PEM formatted): + + <p> + <code><strong>$ ssleay genrsa -des3 -out ca.key 1024</strong></code> + + <p> + Please backup this <code>ca.key</code> file and remember the + pass-phrase you currently entered at a secure location. + You can see the details of this RSA private key via the command + + <p> + <code><strong>$ ssleay rsa -noout -text -in ca.key</strong></code> + + <p> + And you can create a decrypted PEM version (not recommended) of this + private key via: + + <p> + <code><strong>$ ssleay rsa -in ca.key -out ca.key.unsecure</strong></code> + + <p> + <li>Create a self-signed CA Certificate (X509 structure) + for the RSA key of the CA (output will be PEM formatted): + + <p> + <code><strong>$ ssleay req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code> + + <p> + You can see the details of this Certificate via the command: + + <p> + <code><strong>$ ssleay x509 -noout -text -in ca.crt</strong></code> + + <p> + <li>Prepare a script for signing which is needed because + the ``<code>ssleay ca</code>'' command has some strange requirements + and the default SSLeay config doesn't allow one easily to use + ``<code>ssleay ca</code>'' directly. So a script named + <code>sign.sh</code> is distributed with the mod_ssl distribution + (subdir <code>pkg.contrib/</code>). Use this script for signing. + + <p> + <li>Now you can use this CA to sign CSR's in order to create real + SSL Certificates for use inside an Apache webserver: + + <p> + <code><strong>$ ./sign.sh server.csr</strong></code> + + <p> + This signs the CSR and results in a <code>server.crt</code> file. + </ol> + +<faq ref="change-passphrase" toc="How to change a pass phrase?"> +How can I change the pass-phrase on my private key file? +</faq> + + You simply have to read it with the old pass-phrase and write it again + by specifying the new pass-phrase. You can accomplish this with the following + commands: + + <p> + <code><strong>$ ssleay rsa -des3 -in server.key -out server.key.new</strong></code><br> + <code><strong>$ mv server.key.new server.key</strong></code><br> + + <p> + Here you're asked two times for a PEM pass-phrase. At the first + prompt enter the old pass-phrase and at the second prompt + enter the new pass-phrase. + +<faq ref="remove-passphrase" toc="How to remove a pass phrase?"> +How can I get rid of the pass-phrase dialog at Apache startup time? +</faq> + + The reason why this dialog pops up at startup and every re-start + is that the RSA private key inside your server.key file is stored in + encrypted format for security reasons. The pass-phrase is needed to be + able to read and parse this file. When you can be sure that your server is + secure enough you perform two steps: + + <p> + <ol> + <li>Remove the encryption from the RSA private key (while + preserving the original file): + + <p> + <code><strong>$ cp server.key server.key.org</strong></code><br> + <code><strong>$ ssleay rsa -in server.key.org -out server.key</strong></code> + + <p> + <li>Make sure the server.key file is now only readable by root: + + <p> + <code><strong>$ chmod 400 server.key</strong></code> + </ol> + + <p> + Now <code>server.key</code> will contain an unencrypted copy of the key. + If you point your server at this file it will not prompt you for a + pass-phrase. HOWEVER, if anyone gets this key they will be able to + impersonate you on the net. PLEASE make sure that the permissions on that + file are really such that only root or the web server user can read it + (preferably get your web server to start as root but run as another + server, and have the key readable only by root). + +<faq ref="verify-key" toc="How to verify a key/cert pair?"> +How do I verify that a private key matches its Certificate? +</faq> + + The private key contains a series of numbers. Two of those numbers form + the "public key", the others are part of your "private key". The "public + key" bits are also embedded in your Certificate (we get them from your + CSR). To check that the public key in your cert matches the public + portion of your private key, you need to view the cert and the key and + compare the numbers. To view the Certificate and the key run the + commands: + + <p> + <code><strong>$ ssleay x509 -noout -text -in server.crt</strong></code><br> + <code><strong>$ ssleay rsa -noout -text -in server.key</strong></code> + + <p> + The `modulus' and the `public exponent' portions in the key and the + Certificate must match. But since the public exponent is usually 65537 + and it's bothering comparing long modulus you can use the following + approach: + + <p> + <code><strong>$ ssleay x509 -noout -modulus -in server.crt | ssleay md5</strong></code><br> + <code><strong>$ ssleay rsa -noout -modulus -in server.key | ssleay md5</strong></code> + + <p> + And then compare these really shorter numbers. With overwhelming + probability they will differ if the keys are different. BTW, if I want to + check to which key or certificate a particular CSR belongs you can compute + + <p> + <code><strong>$ ssleay req -noout -modulus -in server.csr | ssleay md5</strong></code> + +<faq ref="keysize" toc="Why does a 2048-bit key not work?"> +Why does my 2048-bit private key not work? +</faq> + + The private key sizes for SSL must be either 512 or 1024 for compatibility + with certain web browsers. A keysize of 1024 bits is recommended because + keys larger than 1024 bits are incompatible with some versions of Netscape + Navigator and Microsoft Internet Explorer, and with other browsers that + use RSA's BSAFE cryptography toolkit. + +<faq ref="hash-symlinks" toc="Why is client auth broken?"> +Why is client authentication broken after upgrading from +SSLeay version 0.8 to 0.9? +</faq> + + The CA certificates under the path you configured with + <code>SSLCACertificatePath</code> are found by SSLeay through hash + symlinks. These hash values are generated by the `<code>ssleay x509 -noout + -hash</code>' command. But the algorithm used to calculate the hash for a + certificate has changed between SSLeay 0.8 and 0.9. So you have to remove + all old hash symlinks and re-create new ones after upgrading. Use the + <code>Makefile</code> mod_ssl placed into this directory. + +</ul> + +<p> +<br> +<h2>About SSL Protocol</h2> + +<ul> + +<faq ref="load" toc="Why has the server a higher load?"> +Why has my webserver a higher load now that I run SSL there? +</faq> + + Because SSL uses strong cryptographic encryption and this needs a lot of + number crunching. And because when you request a webpage via HTTPS even + the images are transfered encrypted. So, when you have a lot of HTTPS + traffic the load increases. + +<faq ref="ciphers" toc="Which ciphers are supported?"> +What SSL Ciphers are supported by mod_ssl? +</faq> + + Usually just all SSL ciphers which are supported by the + version of SSLeay in use (can depend on the way you built + SSLeay). Typically this at least includes the following: + <p> + <ul> + <li>RC4 with MD5 + <li>RC4 with MD5 (export version restricted to 40-bit key) + <li>RC2 with MD5 + <li>RC2 with MD5 (export version restricted to 40-bit key) + <li>IDEA with MD5 + <li>DES with MD5 + <li>Triple-DES with MD5 + </ul> + <p> + To determine the actual list of supported ciphers you can + run the following command: + <p> + <code><strong>$ ssleay ciphers -v</strong></code><br> + +<faq ref="vhosts" toc="HTTPS and name-based vhosts"> +Why can't I use SSL with name-based/non-IP-based virtual hosts? +</faq> + + The reason is very technical. Actually it's some sort of a chicken and + egg problem: The SSL protocol layer stays below the HTTP protocol layer + and encapsulates HTTP. When an SSL connection (HTTPS) is established + Apache/mod_ssl has to negotiate the SSL protocol parameters with the + client. For this mod_ssl has to consult the configuration of the virtual + server (for instance it has to look for the cipher suite, the server + certificate, etc.). But in order to dispatch to the correct virtual server + Apache has to know the <code>Host</code> HTTP header field. For this the + HTTP request header has to be read. This cannot be done before the SSL + handshake is finished. But the information is already needed at the SSL + handshake phase. Bingo! + +<faq ref="lock-icon" toc="The lock icon in Netscape locks very late"> +When I use Basic Authentication over HTTPS the lock icon in Netscape browsers +still show the unlocked state when the dialog pops up. Does this mean the +username/password is still transmitted unencrypted? +</faq> + + No, the username/password is already transmitted encrypted. The icon in + Netscape browsers is just not really synchronized with the SSL/TLS layer + (it toggles to the locked state when the first part of the actual webpage + data is transferred which is not quite correct) and this way confuses + people. The Basic Authentication facility is part of the HTTP layer and + this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data + communication takes place in HTTPS the SSL/TLS layer has already done the + handshake phase and switched to encrypted communication. So, don't get + confused by this icon. + +</ul> + +<p> +<br> +<h2>About Support</h2> + +<ul> + +<faq ref="resources" toc="Resources in case of problems?"> +What information resources are available in case of mod_ssl problems? +</faq> + +The following information resources are available. +In case of problems you should search here first. + +<p> +<ol> +<li><em>Answers in the User Manual's F.A.Q. List (this)</em><br> + <a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html"> + http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_faq.html</a><br> + First look inside the F.A.Q. (this text), perhaps your problem is such + popular that it was already answered a lot of times in the past. +<p> +<li><em>Postings from the sw-mod-ssl Support Mailing List</em> + <a href="http://www.engelschall.com/sw/mod_ssl/news/list.html"> + http://www.engelschall.com/sw/mod_ssl/news/list.html</a><br> + Second search for your problem in one of the existing archives of the + sw-mod-ssl mailing list. Perhaps your problem popped up at least once for + another user, too. +<p> +<li><em>Problem Reports in the Bug Database</em> + <a href="http://www.engelschall.com/sw/mod_ssl/bugdb/"> + http://www.engelschall.com/sw/mod_ssl/bugdb/</a><br> + Third look inside the mod_ssl Bug Database. Perhaps + someone else already has reported the problem. +</ol> + +<faq ref="contact" toc="Support in case of problems?"> +What support contacts are available in case of mod_ssl problems? +</faq> + +The following lists all support possibilities for mod_ssl, in order of +preference, i.e. start in this order and do not pick the support possibility +you just like most, please. + +<p> +<ol> +<li><em>Write a Problem Report into the Bug Database</em><br> + <a href="http://www.engelschall.com/sw/mod_ssl/bugdb/"> + http://www.engelschall.com/sw/mod_ssl/bugdb/</a><br> + This is the preferred way of submitting your problem report, because this + way it gets filed into the bug database (it cannot be lost) <em>and</em> + send to the sw-mod-ssl mailing list (others see the current problems and + learn from answers). +<p> +<li><em>Write a Problem Report to the sw-mod-ssl Support Mailing List</em><br> + <a href="mailto:sw-mod-ssl@engelschall.com"> + sw-mod-ssl @ engelschall.com</a><br> + This is the second way of submitting your problem report. You have to + subscribe to the list first, but then you can easily discuss your problem + with both the author and the whole mod_ssl user community. +<p> +<li><em>Write a Problem Report to the author</em><br> + <a href="mailto:rse@engelschall.com"> + rse @ engelschall.com</a><br> + This is the last way of submitting your problem report. Please avoid this + in your own interest because the author is really a very busy men. Your + mail will always be filed to one of his various mail-folders and is + usually not processed as fast as a posting on sw-mod-ssl. +</ol> + +<faq ref="report-details" toc="How to write a problem report?"> +What information and details I've to provide to +the author when writing a bug report? +</faq> + +You have to at least always provide the following information: + +<p> +<ul> +<li><em>Apache, mod_ssl and SSLeay version information</em><br> + The mod_ssl version you should really know. It's for instance the version + number in the distribution tarball. The Apache version can be determined + by running ``<code>httpd -v</code>''. The SSLeay version can be + determined by running ``<code>ssleay version</code>''. Alternatively when + you have Lynx installed you can run the command ``<code>lynx -mime_header + http://localhost/ | grep Server</code>'' to determine all information in a + single step. +<p> +<li><em>The details on how you built and installed Apache+mod_ssl+SSLeay</em><br> + For this you can provide a logfile of your terminal session which shows + the configuration and install steps. Alternatively you can at least + provide the author with the APACI `<code>configure</code>'' command line + you used (assuming you used APACI, of course). + +<p> +<li><em>In case of core dumps please include a Backtrace</em><br> + In case your Apache+mod_ssl+SSLeay should really dumped core please attach + a stack-frame ``backtrace'' (see the next question on how to get it). + Without this information the reason for your core dump cannot be found. + So you have to provide the backtrace, please. +<p> +<li><em>A detailed description of your problem</em><br> + Don't laugh, I'm totally serious. I already got a lot of problem reports + where the people not really said what's the actual problem is. So, in your + own interest (you want the problem be solved, don't you?) include as much + details as possible, please. But start with the essentials first, of + course. +</ul> + +<faq ref="report-backtrace" toc="How to get a backtrace?"> +Ok, I got a core dump but how do I get a backtrace to find out the reason for it? +</faq> + +Follow the following steps: + +<p> +<ol> +<li>Make sure you have debugging symbols available in at least + Apache and mod_ssl. On platforms where you use GCC/GDB you have to build + Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On + other platforms at least ``<code>OPTIM="-g"</code>'' is needed. +<p> +<li>Startup the server and try to produce the core-dump. For this you perhaps + want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to + make sure that the core-dump file can be written. You then should get a + <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you + don't get this, try to run your server under an UID != 0 (root), because + some kernels don't write (for security reasons) core-dumps for + root-processes. Additionally you can run ``<code>/path/to/httpd -X</code>'' + manually to force Apache not not fork. +<p> +<li>Analyze the core-dump. For this run ``<code>gdb /path/to/httpd + /tmp/httpd.core</code>'' or a similar command has to run. In GDB you then + just have to enter the ``<code>bt</code>'' command and, voila, you get the + backtrace. For other debuggers consult your local debugger manual. Send + this backtrace to the author. +</ol> + +</ul> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.html new file mode 100644 index 00000000000..16edfa0fd75 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.html @@ -0,0 +1,415 @@ +<html> +<head> +<title>mod_ssl: Glossary</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-7.gif" alt="7" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_faq.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">F.A.Q. List</font> + </td> + <td valign="top" align="right" width="250"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-gloss.gif" alt="Glossary" width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="300"> +<tr> +<td> +<em>``I know you believe you understand what you think I said, but I am not sure you +realize that what you heard is not what I meant.''</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Unknown +</font> +</td> +</tr> +</table> +</div> +<dl> +<dt><DIV id="term">Authentication</div> +<dd>The positive identification of a network entity such as a server, a + client, or a user. In SSL context the server and client + <em>Certificate</em> verification process. +<p> +<dt><DIV id="term">Access Control</div> +<dd>The restriction of access to network realms. In Apache context + usually the restriction of access to certain <em>URLs</em>. +<p> +<dt><DIV id="term">Algorithm</div> +<dd>An unambiguous formula or set of rules for solving a problem in a finite + number of steps. Algorithms for encryption are usually called <em>Ciphers</em>. +<p> +<dt><DIV id="term">Certificate</div> +<dd>A data record used for authenticating network entities such + as a server or a client. A certificate contains X.509 information pieces + about its owner (called the subject) and the signing <em>Certificate + Authority</em> (called the issuer), plus the owner's public key and the + signature made by the CA. Network entities verify these signatures using + CA certificates. +<p> +<dt><DIV id="term">Certification Authority (CA)</div> +<dd>A trusted third party whose purpose is to sign certificates for network + entities it has authenticated using secure means. Other network entities + can check the signature to verify that a CA has authenticated the bearer + of a certificate. +<p> +<dt><DIV id="term">Certificate Signing Request (CSR)</div> +<dd>An unsigned certificate for submission to a <em>Certification Authority</em>, + which signs it with the <em>Private Key</em> of their CA <em>Certificate</em>. Once + the CSR is signed, it becomes a real certificate. +<p> +<dt><DIV id="term">Cipher</div> +<dd>An algorithm or system for data encryption. Examples are DES, IDEA, RC4, etc. +<p> +<dt><DIV id="term">Ciphertext</div> +<dd>The result after a <em>Plaintext</em> passed a <em>Cipher</em>. +<p> +<dt><DIV id="term">Configuration Directive</div> +<dd>A configuration command that controls one or more aspects of a program's + behavior. In Apache context these are all the command names in the first + column of the configuration files. +<p> +<dt><DIV id="term">CONNECT</div> +<dd>A HTTP command for proxying raw data channels over HTTP. It can be used to + encapsulate other protocols, such as the SSL protocol. +<p> +<dt><DIV id="term">Digital Signature</div> +<dd>An encrypted text block that validates a certificate or other file. A + <em>Certification Authority</em> creates a signature by generating a + hash of the <em>Public Key</em> embedded in a <em>Certificate</em>, then + encrypting the hash with its own <em>Private Key</em>. Only the CA's + public key can decrypt the signature, verifying that the CA has + authenticated the network entity that owns the <em>Certificate</em>. +<p> +<dt><DIV id="term">Export-Crippled</div> +<dd>Diminished in cryptographic strength (and security) in order to comply + with the United States' Export Administration Regulations (EAR). + Export-crippled cryptographic software is limited to a small key size, + resulting in <em>Ciphertext</em> which usually can be decrypted by brute + force. +<p> +<dt><DIV id="term">Fully-Qualified Domain-Name (FQDN)</div> +<dd>The unique name of a network entity, consisting of a hostname and a domain + name that can resolve to an IP address. For example, <code>www</code> is a + hostname, <code>whatever.com</code> is a domain name, and + <code>www.whatever.com</code> is a fully-qualified domain name. +<p> +<dt><DIV id="term">HyperText Transfer Protocol (HTTP)</div> +<dd>The HyperText Transport Protocol is the standard transmission protocol used + on the World Wide Web. +<p> +<dt><DIV id="term">HTTPS</div> +<dd>The HyperText Transport Protocol (Secure), the standard encrypted + communication mechanism on the World Wide Web. This is actually just HTTP + over SSL. +<p> +<dt><DIV id="term">Message Digest</div> +<dd>A hash of a message, which can be used to verify that the contents of + the message have not been altered in transit. +<p> +<dt><DIV id="term">Pass Phrase</div> +<dd>The word or phrase that protects private key files. + It prevents unauthorized users from encrypting them. Usually it's just + the secret encryption/decryption key used for <em>Ciphers</em>. +<p> +<dt><DIV id="term">Plaintext</div> +<dd>The unencrypted text. +<p> +<dt><DIV id="term">Private Key</div> +<dd>The secret key in a <em>Public Key Cryptography</em> system, used to + decrypt incoming messages and sign outgoing ones. +<p> +<dt><DIV id="term">Public Key</div> +<dd>The publically available key in a <em>Public Key Cryptography</em> system, used to + encrypt messages bound for its owner and to decrypt signatures made by its + owner. +<p> +<dt><DIV id="term">Public Key Cryptography</div> +<dd>The study and application of asymmetric encryption systems, which use one + key for encryption and another for decryption. A corresponding pair of + such keys constitutes a key pair. Also called Asymmetric Crypography. +<p> +<dt><DIV id="term">Secure Sockets Layer (SSL)</div> +<dd>A protocol created by Netscape Communications Corporation for + general communication authentication and encryption over TCP/IP networks. + The most popular usage is <em>HTTPS</em>, i.e. the HyperText Transfer + Protocol (HTTP) over SSL. +<p> +<dt><DIV id="term">Session</div> +<dd>The context information of an SSL communication. +<p> +<dt><DIV id="term">SSLeay</div> +<dd>The SSL/TLS implementation library developed by Eric A. Young <eay@cryptsoft.com>. +<p> +<dt><DIV id="term">Symmetric Cryptography</div> +<dd>The study and application of <em>Ciphers</em> that use a single secret key + for both encryption and decryption operations. +<p> +<dt><DIV id="term">Transport Layer Security (TLS)</div> +<dd>The successor protocol to SSL, created by the Internet Engineering Task + Force (IETF) for general communication authentication and encryption over + TCP/IP networks. TLS version 1 and is nearly identical with SSL version 3. +<p> +<dt><DIV id="term">Uniform Resource Locator (URL)</div> +<dd>The formal identifier to locate various resources on the World Wide Web. + The most popular URL scheme is <code>http</code>. SSL uses the + scheme <code>https</code> +<p> +<dt><DIV id="term">X.509</div> +<dd>An authentication certificate scheme recommended by the International + Telecommunication Union (ITU-T) which is used for SSL/TLS authentication. +</dl> + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_faq.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">F.A.Q. List</font> + </td> + <td valign="top" align="right" width="250"> + </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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.wml new file mode 100644 index 00000000000..65eef504770 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_glossary.wml @@ -0,0 +1,146 @@ + +#use "ssl_template.inc" title="Glossary" tag=gloss num=7 + +<page_prev name="F.A.Q. List" url="ssl_faq.html"> + +<quotation width=300 author="Unknown"> +``I know you believe you understand what you think I said, but I am not sure you +realize that what you heard is not what I meant.'' +</quotation> + +<dl> + +<dt><div id="term">Authentication</div> +<dd>The positive identification of a network entity such as a server, a + client, or a user. In SSL context the server and client + <em>Certificate</em> verification process. +<p> +<dt><div id="term">Access Control</div> +<dd>The restriction of access to network realms. In Apache context + usually the restriction of access to certain <em>URLs</em>. +<p> +<dt><div id="term">Algorithm</div> +<dd>An unambiguous formula or set of rules for solving a problem in a finite + number of steps. Algorithms for encryption are usually called <em>Ciphers</em>. +<p> +<dt><div id="term">Certificate</div> +<dd>A data record used for authenticating network entities such + as a server or a client. A certificate contains X.509 information pieces + about its owner (called the subject) and the signing <em>Certificate + Authority</em> (called the issuer), plus the owner's public key and the + signature made by the CA. Network entities verify these signatures using + CA certificates. +<p> +<dt><div id="term">Certification Authority (CA)</div> +<dd>A trusted third party whose purpose is to sign certificates for network + entities it has authenticated using secure means. Other network entities + can check the signature to verify that a CA has authenticated the bearer + of a certificate. +<p> +<dt><div id="term">Certificate Signing Request (CSR)</div> +<dd>An unsigned certificate for submission to a <em>Certification Authority</em>, + which signs it with the <em>Private Key</em> of their CA <em>Certificate</em>. Once + the CSR is signed, it becomes a real certificate. +<p> +<dt><div id="term">Cipher</div> +<dd>An algorithm or system for data encryption. Examples are DES, IDEA, RC4, etc. +<p> +<dt><div id="term">Ciphertext</div> +<dd>The result after a <em>Plaintext</em> passed a <em>Cipher</em>. +<p> +<dt><div id="term">Configuration Directive</div> +<dd>A configuration command that controls one or more aspects of a program's + behavior. In Apache context these are all the command names in the first + column of the configuration files. +<p> +<dt><div id="term">CONNECT</div> +<dd>A HTTP command for proxying raw data channels over HTTP. It can be used to + encapsulate other protocols, such as the SSL protocol. +<p> +<dt><div id="term">Digital Signature</div> +<dd>An encrypted text block that validates a certificate or other file. A + <em>Certification Authority</em> creates a signature by generating a + hash of the <em>Public Key</em> embedded in a <em>Certificate</em>, then + encrypting the hash with its own <em>Private Key</em>. Only the CA's + public key can decrypt the signature, verifying that the CA has + authenticated the network entity that owns the <em>Certificate</em>. +<p> +<dt><div id="term">Export-Crippled</div> +<dd>Diminished in cryptographic strength (and security) in order to comply + with the United States' Export Administration Regulations (EAR). + Export-crippled cryptographic software is limited to a small key size, + resulting in <em>Ciphertext</em> which usually can be decrypted by brute + force. +<p> +<dt><div id="term">Fully-Qualified Domain-Name (FQDN)</div> +<dd>The unique name of a network entity, consisting of a hostname and a domain + name that can resolve to an IP address. For example, <code>www</code> is a + hostname, <code>whatever.com</code> is a domain name, and + <code>www.whatever.com</code> is a fully-qualified domain name. +<p> +<dt><div id="term">HyperText Transfer Protocol (HTTP)</div> +<dd>The HyperText Transport Protocol is the standard transmission protocol used + on the World Wide Web. +<p> +<dt><div id="term">HTTPS</div> +<dd>The HyperText Transport Protocol (Secure), the standard encrypted + communication mechanism on the World Wide Web. This is actually just HTTP + over SSL. +<p> +<dt><div id="term">Message Digest</div> +<dd>A hash of a message, which can be used to verify that the contents of + the message have not been altered in transit. +<p> +<dt><div id="term">Pass Phrase</div> +<dd>The word or phrase that protects private key files. + It prevents unauthorized users from encrypting them. Usually it's just + the secret encryption/decryption key used for <em>Ciphers</em>. +<p> +<dt><div id="term">Plaintext</div> +<dd>The unencrypted text. +<p> +<dt><div id="term">Private Key</div> +<dd>The secret key in a <em>Public Key Cryptography</em> system, used to + decrypt incoming messages and sign outgoing ones. +<p> +<dt><div id="term">Public Key</div> +<dd>The publically available key in a <em>Public Key Cryptography</em> system, used to + encrypt messages bound for its owner and to decrypt signatures made by its + owner. +<p> +<dt><div id="term">Public Key Cryptography</div> +<dd>The study and application of asymmetric encryption systems, which use one + key for encryption and another for decryption. A corresponding pair of + such keys constitutes a key pair. Also called Asymmetric Crypography. +<p> +<dt><div id="term">Secure Sockets Layer (SSL)</div> +<dd>A protocol created by Netscape Communications Corporation for + general communication authentication and encryption over TCP/IP networks. + The most popular usage is <em>HTTPS</em>, i.e. the HyperText Transfer + Protocol (HTTP) over SSL. +<p> +<dt><div id="term">Session</div> +<dd>The context information of an SSL communication. +<p> +<dt><div id="term">SSLeay</div> +<dd>The SSL/TLS implementation library developed by Eric A. Young <eay@cryptsoft.com>. +<p> +<dt><div id="term">Symmetric Cryptography</div> +<dd>The study and application of <em>Ciphers</em> that use a single secret key + for both encryption and decryption operations. +<p> +<dt><div id="term">Transport Layer Security (TLS)</div> +<dd>The successor protocol to SSL, created by the Internet Engineering Task + Force (IETF) for general communication authentication and encryption over + TCP/IP networks. TLS version 1 and is nearly identical with SSL version 3. +<p> +<dt><div id="term">Uniform Resource Locator (URL)</div> +<dd>The formal identifier to locate various resources on the World Wide Web. + The most popular URL scheme is <code>http</code>. SSL uses the + scheme <code>https</code> +<p> +<dt><div id="term">X.509</div> +<dd>An authentication certificate scheme recommended by the International + Telecommunication Union (ITU-T) which is used for SSL/TLS authentication. +</dl> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.gfont000.gif Binary files differnew file mode 100644 index 00000000000..3131a672bf9 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.html new file mode 100644 index 00000000000..ccdaefffac5 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.html @@ -0,0 +1,818 @@ +<html> +<head> +<title>mod_ssl: HowTo</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-5.gif" alt="5" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_compat.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">Compatibility</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_faq.html" + onMouseOver="ro_imgOver('ro_img_next_top', 'next page'); return true" + onMouseOut="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">F.A.Q. List</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-howto.gif" alt="HowTo" width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="200"> +<tr> +<td> +<em>``The solution of this problem is trivial + and is left as an exercise for the reader.''</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Standard textbook cookie +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> +<img src="ssl_howto.gfont000.gif" alt="H" width="40" height="34" border="0" align="left"> +ow to solve particular security constraints for an SSL-aware webserver +is not always obvious because of the coherences between SSL, HTTP and Apache's +way of processing requests. This chapter gives instructions on how to solve +such typical situations. Treat is as a first step to find out the final +solution, but always try to understand the stuff before you use it. Nothing is +worse than using a security solution without knowing it's restrictions and +coherences. +</td> +<td> + +</td> +<td> +<DIV align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" width="300"> +<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>Cipher Suites and Enforced Strong Security</strong></a><br> + <a href="#ToC2"><strong>SSLv2 only server</strong></a><br> + <a href="#ToC3"><strong>strong encryption only server</strong></a><br> + <a href="#ToC4"><strong>server gated cryptography</strong></a><br> + <a href="#ToC5"><strong>stronger per-directory requirements</strong></a><br> + <a href="#ToC6"><strong>Client Authentication and Access Control</strong></a><br> + <a href="#ToC7"><strong>simple certificate-based client authentication</strong></a><br> + <a href="#ToC8"><strong>selective certificate-based client authentication</strong></a><br> + <a href="#ToC9"><strong>particular certificate-based client authentication</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<H2><a name="ToC1">Cipher Suites and Enforced Strong Security</a></H2> +<ul> +<p> +<li><a name="ToC2"></a> + <a name="cipher-sslv2"></a> + <strong id="howto">How can I create a real SSLv2-only server?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#cipher-sslv2"><b>L</b></a>] + <p> +The following creates an SSL server which speaks only the SSLv2 protocol and +it's ciphers. +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +SSLProtocol -all +SSLv2 +SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC3"></a> + <a name="cipher-strong"></a> + <strong id="howto">How can I create an SSL server which accepts strong encryption only?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#cipher-strong"><b>L</b></a>] + <p> +The following enables only the seven strongest ciphers: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +SSLProtocol all +SSLCipherSuite HIGH:MEDIUM +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC4"></a> + <a name="cipher-sgc"></a> + <strong id="howto">How can I create an SSL server which accepts strong encryption only, +but allows export browsers to upgrade to stronger encryption?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#cipher-sgc"><b>L</b></a>] + <p> +This facility is called Server Gated Cryptography (SGC) and details you can +find in the <code>README.GlobalID</code> document in the mod_ssl distribution. +In short: The server has a Global ID server certificate, signed by a special +CA certificate from Verisign which enables strong encryption in export +browsers. This works as following: The browser connects with an export cipher, +the server sends it's Global ID certificate, the browser verifies it and +subsequently upgrades the cipher suite before any HTTP communication takes +place. The question now is: How can we allow this upgrade, but enforce strong +encryption. Or in other words: Browser either have to initially connect with +strong encryption or have to upgrade to strong encryption, but are not allowed +to keep the export ciphers. The following does the trick: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +# allow all ciphers for the inital handshake, +# so export browsers can upgrade via SGC facility +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP +<Directory /usr/local/apache/htdocs> +# but finally deny all browsers which haven't upgraded +SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128 +</Directory> +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC5"></a> + <a name="cipher-perdir"></a> + <strong id="howto">How can I create an SSL server which accepts all types of ciphers in general, +but requires a strong ciphers for access to a particular URL?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#cipher-perdir"><b>L</b></a>] + <p> +Obviously you cannot just use a server-wide <code>SSLCipherSuite</code> which +restricts the ciphers to the strong variants. But mod_ssl allows you to +reconfigure the cipher suite in per-directory context and automatically forces +a renegotiation of the SSL parameters to meet the new configuration. So, the +solution is: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +# be liberal in general +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP +<Location /strong/area> +# but https://hostname/string/area/ and below requires strong ciphers +SSLCipherSuite HIGH:MEDIUM +</Location> +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +</ul> +<H2><a name="ToC6">Client Authentication and Access Control</a></H2> +<ul> +<p> +<li><a name="ToC7"></a> + <a name="auth-simple"></a> + <strong id="howto">How can I authenticate clients based on certificates when I know all my +clients?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#auth-simple"><b>L</b></a>] + <p> +When you know your user community (i.e. a closed user group situation), as +it's the case for instance in an Intranet, you can use plain certificate +authentication. All you have to do is to create client certificates signed by +your own CA certificate <code>ca.crt</code> and then verifiy the clients +against this certificate. +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +# require a client certificate which has to be directly +# signed by our CA certificate in ca.crt +SSLVerifyClient require +SSLVerifyDepth 1 +SSLCACertificateFile conf/ssl.crt/ca.crt +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC8"></a> + <a name="auth-selective"></a> + <strong id="howto">How can I authenticate my clients for a particular URL based on certificates +but still allow arbitrary clients to access the remaining parts of the server?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#auth-selective"><b>L</b></a>] + <p> +For this we again use the per-directory reconfiguration feature of mod_ssl: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +SSLVerifyClient none +SSLCACertificateFile conf/ssl.crt/ca.crt +<Location /secure/area> +SSLVerifyClient require +SSLVerifyDepth 1 +</Location> +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC9"></a> + <a name="auth-particular"></a> + <strong id="howto">How can I authenticate only particular clients for a some URLs based +on certificates but still allow arbitrary clients to access the remaining +parts of the server?</strong> + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#auth-particular"><b>L</b></a>] + <p> +The key is to check for various ingredients of the client certficate. Usually +this means to check the whole or part of the Distinguished Name (DN) of the +Subject. For this two methods exists: The <code>mod_auth</code> based variant +and the <code>SSLRequire</code> variant. The first method is good when the +clients are of totally different type, i.e. when their DNs have no common +fields (usually the organisation, etc.). In this case you've to establish a +password database containing <em>all</em> clients. The second method is better +when your clients are all part of a common hierarchy which is encoded into the +DN. Then you can match them more easily. +<p> +The first method: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">/usr/local/apache/conf/httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +AuthType Basic +AuthUserFile /usr/local/apache/conf/httpd.passwd +require valid-user +</Directory> +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">/usr/local/apache/conf/httpd.passwd</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +/C=DE/L=Munich/O=Snake Oild, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA +/C=US/L=S.F./O=Snake Oild, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA +/C=US/L=L.A./O=Snake Oild, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +The second method: +<p> +<table border="0" cellpadding="0" cellspacing="0"> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"> </td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4"> + <tr> + <td><pre> +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." and \ + %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} +</Directory> +</pre></td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +</ul> + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_compat.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">Compatibility</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_faq.html" + onMouseOver="ro_imgOver('ro_img_next_bot', 'next page'); return true" + onMouseOut="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">F.A.Q. List</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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.wml new file mode 100644 index 00000000000..b850ec0b1d2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_howto.wml @@ -0,0 +1,267 @@ + +#use "ssl_template.inc" title="HowTo" tag=howto num=5 + +<page_prev name="Compatibility" url="ssl_compat.html"> +<page_next name="F.A.Q. List" url="ssl_faq.html"> + +#use wml::std::toc style=nbsp + +<quotation width=200 author="Standard textbook cookie"> +``The solution of this problem is trivial + and is left as an exercise for the reader.'' +</quotation> + +<p> +<table cellspacing=0 cellpadding=0 border=0> +<tr valign=bottom> +<td> + +<big H>ow to solve particular security constraints for an SSL-aware webserver +is not always obvious because of the coherences between SSL, HTTP and Apache's +way of processing requests. This chapter gives instructions on how to solve +such typical situations. Treat is as a first step to find out the final +solution, but always try to understand the stuff before you use it. Nothing is +worse than using a security solution without knowing it's restrictions and +coherences. + +</td> +<td> + +</td> +<td> + +<div align=right> +<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff" width=300> +<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> +<toc> +</font> +</td> +</tr> +</table> +</div> + +</td> +</tr> +</table> + +# container tag for layouting a question +<define-container howto> +<preserve ref> +<preserve toc> +<set-var %attributes> +<p> +<li><toc_h3 <get-var toc>></toc_h3> + <a name="<get-var ref>"></a> + <strong id="howto">%body</strong>\ + + [<a href="http://www.engelschall.com/sw/mod_ssl/docs/2.2/ssl_howto.html#<get-var ref>"><b>L</b></a>] + <p> +<restore toc> +<restore ref> +</define-container> + +<define-container config> +<preserve file> +<set-var %attributes> +<ifeq "<get-var file>" "" <set-var file="httpd.conf">> +<box header="<font face=\"Arial,Helvetica\" color=\"#999999\"><get-var file></font>" + bdwidth=1 bdcolor="#cccccc" bgcolor="#ffffff" fgcolor="#000000"> +<pre> +%body +</pre> +</box>\ +<restore file> +</define-container> + +<h2>Cipher Suites and Enforced Strong Security</h2> + +<ul> + +<howto ref="cipher-sslv2" toc="SSLv2 only server"> +How can I create a real SSLv2-only server? +</howto> + +The following creates an SSL server which speaks only the SSLv2 protocol and +it's ciphers. + +<p> +<config> +SSLProtocol -all +SSLv2 +SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP +</config> + +<howto ref="cipher-strong" toc="strong encryption only server"> +How can I create an SSL server which accepts strong encryption only? +</howto> + +The following enables only the seven strongest ciphers: + +<p> +<config> +SSLProtocol all +SSLCipherSuite HIGH:MEDIUM +</config> + +<howto ref="cipher-sgc" toc="server gated cryptography"> +How can I create an SSL server which accepts strong encryption only, +but allows export browsers to upgrade to stronger encryption? +</howto> + +This facility is called Server Gated Cryptography (SGC) and details you can +find in the <code>README.GlobalID</code> document in the mod_ssl distribution. +In short: The server has a Global ID server certificate, signed by a special +CA certificate from Verisign which enables strong encryption in export +browsers. This works as following: The browser connects with an export cipher, +the server sends it's Global ID certificate, the browser verifies it and +subsequently upgrades the cipher suite before any HTTP communication takes +place. The question now is: How can we allow this upgrade, but enforce strong +encryption. Or in other words: Browser either have to initially connect with +strong encryption or have to upgrade to strong encryption, but are not allowed +to keep the export ciphers. The following does the trick: + +<p> +<config> +\# allow all ciphers for the inital handshake, +\# so export browsers can upgrade via SGC facility +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP +<Directory /usr/local/apache/htdocs> +\# but finally deny all browsers which haven't upgraded +SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128 +</Directory> +</config> + +<howto ref="cipher-perdir" toc="stronger per-directory requirements"> +How can I create an SSL server which accepts all types of ciphers in general, +but requires a strong ciphers for access to a particular URL? +</howto> + +Obviously you cannot just use a server-wide <code>SSLCipherSuite</code> which +restricts the ciphers to the strong variants. But mod_ssl allows you to +reconfigure the cipher suite in per-directory context and automatically forces +a renegotiation of the SSL parameters to meet the new configuration. So, the +solution is: + +<p> +<config> +\# be liberal in general +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP +<Location /strong/area> +\# but https://hostname/string/area/ and below requires strong ciphers +SSLCipherSuite HIGH:MEDIUM +</Location> +</config> + +</ul> + +<h2>Client Authentication and Access Control</h2> + +<ul> + +<howto ref="auth-simple" toc="simple certificate-based client authentication"> +How can I authenticate clients based on certificates when I know all my +clients? +</howto> + +When you know your user community (i.e. a closed user group situation), as +it's the case for instance in an Intranet, you can use plain certificate +authentication. All you have to do is to create client certificates signed by +your own CA certificate <code>ca.crt</code> and then verifiy the clients +against this certificate. + +<p> +<config> +\# require a client certificate which has to be directly +\# signed by our CA certificate in ca.crt +SSLVerifyClient require +SSLVerifyDepth 1 +SSLCACertificateFile conf/ssl.crt/ca.crt +</config> + +<howto ref="auth-selective" toc="selective certificate-based client authentication"> +How can I authenticate my clients for a particular URL based on certificates +but still allow arbitrary clients to access the remaining parts of the server? +</howto> + +For this we again use the per-directory reconfiguration feature of mod_ssl: + +<p> +<config> +SSLVerifyClient none +SSLCACertificateFile conf/ssl.crt/ca.crt +<Location /secure/area> +SSLVerifyClient require +SSLVerifyDepth 1 +</Location> +</config> + +<howto ref="auth-particular" toc="particular certificate-based client authentication"> +How can I authenticate only particular clients for a some URLs based +on certificates but still allow arbitrary clients to access the remaining +parts of the server? +</howto> + +The key is to check for various ingredients of the client certficate. Usually +this means to check the whole or part of the Distinguished Name (DN) of the +Subject. For this two methods exists: The <code>mod_auth</code> based variant +and the <code>SSLRequire</code> variant. The first method is good when the +clients are of totally different type, i.e. when their DNs have no common +fields (usually the organisation, etc.). In this case you've to establish a +password database containing <em>all</em> clients. The second method is better +when your clients are all part of a common hierarchy which is encoded into the +DN. Then you can match them more easily. + +<p> +The first method: + +<p> +<config file="/usr/local/apache/conf/httpd.conf"> +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +AuthType Basic +AuthUserFile /usr/local/apache/conf/httpd.passwd +require valid-user +</Directory> +</config> + +<p> +<config file="/usr/local/apache/conf/httpd.passwd"> +/C=DE/L=Munich/O=Snake Oild, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA +/C=US/L=S.F./O=Snake Oild, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA +/C=US/L=L.A./O=Snake Oild, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA +</config> + +<p> +The second method: + +<p> +<config> +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." and \\ + %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} +</Directory> +</config> + +</ul> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.gfont000.gif Binary files differnew file mode 100644 index 00000000000..bcc618870d1 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.html new file mode 100644 index 00000000000..42a60ac2f78 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.html @@ -0,0 +1,931 @@ +<html> +<head> +<title>mod_ssl: Introduction</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-2.gif" alt="2" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_overview.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">Overview</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_reference.html" + onMouseOver="ro_imgOver('ro_img_next_top', 'next page'); return true" + onMouseOut="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">Reference</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-intro.gif" alt="Introduction" width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="400"> +<tr> +<td> +<em>``The nice thing about standards is that there are so many to choose from. +And if you really don't like all the standards you just have to wait another +year until the one arises you are looking for.''</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +A. Tannenbaum, ``Introduction to Computer Networks'' +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> +<img src="ssl_intro.gfont000.gif" alt="A" width="37" height="35" border="0" align="left"> +s an introduction this chapter is aimed at readers who are familiar +with the Web, HTTP, and Apache, but are not security experts. It is not +intended to be a definitive guide to the SSL protocol, nor does it discuss +specific techniques for managing certificates in an organization, or the +important legal issues of patents and import and export restrictions. Rather, +it is intended to provide a common background to mod_ssl users by pulling +together various concepts, definitions, and examples as a starting point for +further exploration. +<p> +The presented content is mainly derived, with permission by the author, from +the article <a +href="http://www.ultranet.com/~fhirsch/Papers/wwwj/index.html"><em>Introducing SSL +and Certificates using SSLeay</em></a> from <a +href="http://www.ultranet.com/~fhirsch/">Frederick J. Hirsch</a>, of The Open +Group Research Institute, which was published in <a +href="http://www.ora.com/catalog/wjsum97/"><em>Web Security: A Matter of +Trust</em></a>, World Wide Web Journal, Volume 2, Issue 3, Summer 1997. +Please send any postive feedback to <a +href="mailto:fjh@alum.mit.edu">Frederick Hirsch</a> (the original +article author) and all negative feedback to <a +href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> (the mod_ssl +author). +</td> +<td> + +</td> +<td> +<DIV align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff"> +<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>Cryptographic Techniques</strong></a><br> + <a href="#ToC2"><strong>Cryptographic Algorithms</strong></a><br> + <a href="#ToC3"><strong>Message Digests</strong></a><br> + <a href="#ToC4"><strong>Digital Signatures</strong></a><br> + <a href="#ToC5"><strong>Certificates</strong></a><br> + <a href="#ToC6"><strong>Certificate Contents</strong></a><br> + <a href="#ToC7"><strong>Certificate Authorities</strong></a><br> + <a href="#ToC8"><strong>Certificate Chains</strong></a><br> + <a href="#ToC9"><strong>Creating a Root-Level CA</strong></a><br> + <a href="#ToC10"><strong>Certificate Management</strong></a><br> + <a href="#ToC11"><strong>Secure Sockets Layer (SSL)</strong></a><br> + <a href="#ToC12"><strong>Session Establishment</strong></a><br> + <a href="#ToC13"><strong>Key Exchange Method</strong></a><br> + <a href="#ToC14"><strong>Cipher for Data Transfer</strong></a><br> + <a href="#ToC15"><strong>Digest Function</strong></a><br> + <a href="#ToC16"><strong>Handshake Sequence Protocol</strong></a><br> + <a href="#ToC17"><strong>Data Transfer</strong></a><br> + <a href="#ToC18"><strong>Securing HTTP Communication</strong></a><br> + <a href="#ToC19"><strong>References</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<H2><a name="ToC1">Cryptographic Techniques</a></H2> +Understanding SSL requires an understanding of cryptographic algorithms, +message digest functions (aka. one-way or hash functions), and digital +signatures. These techniques are the subject of entire books (see for instance +[<a href="#AC96">AC96</a>]) and provide the basis for privacy, integrity, and +authentication. +<H3><a name="ToC2">Cryptographic Algorithms</a></H3> +Suppose Alice wants to send a message to her bank to transfer some money. +Alice would like the message to be private, since it will include information +such as her account number and transfer amount. One solution is to use a +cryptographic algorithm, a technique that would transform her message into an +encrypted form, unreadable except by those it is intended for. Once in this +form, the message may only be interpreted through the use of a secret key. +Without the key the message is useless: good cryptographic algorithms make it +so difficult for intruders to decode the original text that it isn't worth +their effort. +<p> +There are two categories of cryptographic algorithms: +conventional and public key. +<ul> +<li><em>Conventional cryptography</em>, also known as symmetric +cryptography, requires the sender and receiver to share a key: a secret +piece of information that may be used to encrypt or decrypt a message. +If this key is secret, then nobody other than the sender or receiver may +read the message. If Alice and the bank know a secret key, then they +may send each other private messages. The task of privately choosing a key +before communicating, however, can be problematic. +<p> +<li><em>Public key cryptography</em>, also known as asymmetric cryptography, +solves the key exchange problem by defining an algorithm which uses two keys, +each of which may be used to encrypt a message. If one key is used to encrypt +a message then the other must be used to decrypt it. This makes it possible +to receive secure messages by simply publishing one key (the public key) and +keeping the other secret (the private key). +<p> +Anyone may encrypt a message using the public key, but only the owner of the +private key will be able to read it. In this way, Alice may send private +messages to the owner of a key-pair (the bank), by encrypting it using their +public key. Only the bank will be able to decrypt it. +</ul> +<H3><a name="ToC3">Message Digests</a></H3> +Although Alice may encrypt her message to make it private, there is still a +concern that someone might modify her original message message or substitute +it with a different one, in order to transfer the money to themselves, for +instance. One way of guaranteeing the integrity of Alice's message is to +create a concise summary of her message and send this to the bank as well. +Upon receipt of the message, the bank creates its own summary and compares it +with the one Alice sent. If they agree then the message was received intact. +<p> +A summary such as this is called a <em>message digest</em>, <em>one-way +function</em> or <em>hash function</em>. Message digests are used to create +short, fixed-length representations of longer, variable-length messages. +Digest algorithms are designed to produce unique digests for different +messages. Message digests are designed to make it too difficult to determine +the message from the digest, and also impossible to find two different +messages which create the same digest -- thus eliminating the possibility of +substituting one message for another while maintaining the same digest. +<p> +Another challenge that Alice faces is finding a way to send the digest to the +bank securely; when this is achieved, the integrity of the associated message +is assured. One way to to this is to include the digest in a digital +signature. +<H3><a name="ToC4">Digital Signatures</a></H3> +When Alice sends a message to the bank, the bank needs to ensure that the +message is really from her, so an intruder does not request a transaction +involving her account. A <em>digital signature</em>, created by Alice and +included with the message, serves this purpose. +<p> +Digital signatures are created by encrypting a digest of the message, +and other information (such as a sequence number) with the sender's +private key. Though anyone may <em>decrypt</em> the signature using the public +key, only the signer knows the private key. This means that only they may +have signed it. Including the digest in the signature means the signature is +only good for that message; it also ensures the integrity of the message since +no one can change the digest and still sign it. +<p> +To guard against interception and reuse of the signature by an intruder at a +later date, the signature contains a unique sequence number. This protects +the bank from a fraudulent claim from Alice that she did not send the message +-- only she could have signed it (non-repudiation). +<H2><a name="ToC5">Certificates</a></H2> +Although Alice could have sent a private message to the bank, signed it, and +ensured the integrity of the message, she still needs to be sure that she is +really communicating with the bank. This means that she needs to be sure that +the public key she is using corresponds to the bank's private key. Similarly, +the bank also needs to verify that the message signature really corresponds to +Alice's signature. +<p> +If each party has a certificate which validates the other's identity, confirms +the public key, and is signed by a trusted agency, then they both will be +assured that they are communicating with whom they think they are. Such a +trusted agency is called a <em>Certificate Authority</em>, and certificates are +used for authentication. +<H3><a name="ToC6">Certificate Contents</a></H3> +A certificate associates a public key with the real identity of an individual, +server, or other entity, known as the subject. As shown in <a +href="#table1">Table 1</a>, information about the subject includes identifying +information (the distinguished name), and the public key. It also includes +the identification and signature of the Certificate Authority that issued the +certificate, and the period of time during which the certificate is valid. It +may have additional information (or extensions) as well as administrative +information for the Certificate Authority's use, such as a serial number. +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 1: Certificate Information</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table> +<tr valign="top"><td><b>Subject:</b></td> +<td>Distinguished Name, Public Key</td></tr> +<tr valign="top"><td><b>Issuer:</b></td> +<td>Distinguished Name, Signature</td></tr> +<tr><td><b>Period of Validity:</b></td> +<td>Not Before Date, Not After Date</td></tr> +<tr><td><b>Administrative Information:</b></td> +<td>Version, Serial Number</td></TR> +<tr><td><b>Extended Information:</b></td> +<td>Basic Contraints, Netscape Flags, etc.</td></TR> +</table></td> +</tr></table> +</td></tr></table> +</div> +<p> +A distinguished name is used to provide an identity in a specific context -- +for instance, an individual might have a personal certificate as well as one +for their identity as an employee. Distinguished names are defined by the +X.509 standard [<a href="#X509">X509</A>], which defines the fields, field +names, and abbreviations used to refer to the fields +(see <a href="#table2">Table 2</a>). +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 2: Distinguished Name Information</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table> +<tr valign="top"><td><b>DN Field:</b></td><td><b>Abbrev.:</b></td><td><b>Description:</b></td> +<td><b>Example:</b></td> +</t> +<tr valign="top"><td>Common Name</td><td>CN</td> +<td>Name being certified</td><td>CN=Joe Average</td></tr> +<tr valign="top"><td>Organization or Company</td><td>O</td> +<td>Name is associated with this<br>organization</td><td>O=Snake Oil, Ltd.</td></tr> +<tr valign="top"><td>Organizational Unit</td><td>OU</td> +<td>Name is associated with this <br>organization unit, such as a department</td><td>OU=Research Institute</td></tr> +<tr valign="top"><td>City/Locality</td><td>L</td> +<td>Name is located in this City</td><td>L=Snake City</td></tr> +<tr valign="top"><td>State/Province</td><td>ST</td> +<td>Name is located in this State/Province</td><td>ST=Desert</td></tr> +<tr valign="top"><td>Country</td><td>C</td> +<td>Name is located in this Country (ISO code)</td><td>C=XZ</td></tr> +</table></td> +</tr></table> +</td></tr></table> +</div> +<p> +A Certificate Authority may define a policy specifying which distinguished +field names are optional, and which are required. It may also place +requirements upon the field contents, as may users of certificates. As an +example, a Netscape browser requires that the Common Name for a certificate +representing a server has a name which matches a wildcard pattern for the +domain name of that server, such as <code>*.snakeoil.com</code>. +<p> +The binary format of a certificate is defined using the ASN.1 notation [ <a +href="#X208">X208</a>] [<a href="#PKCS">PKCS</a>]. This notation defines how to +specify the contents, and encoding rules define how this information is +translated into binary form. The binary encoding of the certificate is +defined using Distinguished Encoding Rules (DER), which are based on the more +general Basic Encoding Rules (BER). For those transmissions which cannot +handle binary, the binary form may be translated into an ASCII form by using +Base64 encoding [<a href="#MIME">MIME</a>]. This encoded version is called PEM +encoded (the name comes from "Privacy Enhanced Mail"), when placed between +begin and end delimiter lines as illustrated in <a href="#table3">Table 3</a>. +<p> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 3: Example of a PEM-encoded certificate (snakeoil.crt)</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table cellspacing="0" cellpadding="0"><tr><td> +<DIV class="code"><pre> +-----BEGIN CERTIFICATE----- +MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx +FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG +A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv +cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz +bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL +MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h +a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl +cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN +AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB +gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b +vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa +lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV +HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB +gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt +2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7 +dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ== +-----END CERTIFICATE-----</pre></div> +</td></tr></table></td> +</tr></table> +</td></tr></table> +</div> +<H3><a name="ToC7">Certificate Authorities</a></H3> +By first verifying the information in a certificate request before granting +the certificate, the Certificate Authority assures the identity of the private +key owner of a key-pair. For instance, if Alice requests a personal +certificate, the Certificate Authority must first make sure that Alice really +is the person the certificate request claims. +<H4><a name="ToC8">Certificate Chains</a></H4> +A Certificate Authority may also issue a certificate for another Certificate +Authority. When examining a certificate, Alice may need to examine the +certificate of the issuer, for each parent Certificate Authority, until +reaching one which she has confidence in. She may decide to trust only +certificates with a limited chain of issuers, to reduce her risk of a "bad" +certificate in the chain. +<H4><a name="ToC9">Creating a Root-Level CA</a></H4> +As noted earlier, each certificate requires an issuer to assert the validity +of the identity of the certificate subject, up to the top-level Certificate +Authority (CA). This presents a problem: Since this is who vouches for the +certificate of the top-level authority, which has no issuer? +In this unique case, the certificate is "self-signed", so the issuer of the +certificate is the same as the subject. As a result, one must exercise extra +care in trusting a self-signed certificate. The wide publication of a public +key by the root authority reduces the risk in trusting this key -- it would be +obvious if someone else publicized a key claiming to be the authority. +Browsers are preconfigured to trust well-known certificate authorities. +<p> +A number of companies, such as <a href="http://www.thawte.com/">Thawte</a> and +<a href="http://www.verisign.com/">VeriSign</a> have established themselves as +Certificate Authorities. These companies provide the following services: +<ul> +<li>Verifying certificate requests +<li>Processing certificate requests +<li>Issuing and managing certificates +</ul> +<p> +It is also possible to create your own Certificate Authority. Although risky +in the Internet environment, it may be useful within an Intranet where the +organization can easily verify the identities of individuals and servers. +<H4><a name="ToC10">Certificate Management</a></H4> +Establishing a Certificate Authority is a responsibility which requires a +solid administrative, technical, and management framework. +Certificate Authorities not only issue certificates, they also manage them -- +that is, they determine how long certificates are valid, they renew them, and +they keep lists of certificates that have already been issued but are no +longer valid (Certificate Revocation Lists, or CRLs). +Say Alice is entitled to a certificate as an employee of a company. Say too, +that the certificate needs to be revoked when Alice leaves the company. Since +certificates are objects that get passed around, it is impossible to tell from +the certificate alone that it has been revoked. +When examining certificates for validity, therefore, it is necessary to +contact the issuing Certificate Authority to check CRLs -- this is not usually +an automated part of the process. +<p> +<div align="center"><B>Note:</B></div> +If you use a Certificate Authority that is not configured into browsers by +default, it is necessary to load the Certificate Authority certificate into +the browser, enabling the browser to validate server certificates signed by +that Certificate Authority. Doing so may be dangerous, since once loaded, the +browser will accept all certificates signed by that Certificate Authority. +<H2><a name="ToC11">Secure Sockets Layer (SSL)</a></H2> +The Secure Sockets Layer protocol is a protocol layer which may be placed +between a reliable connection-oriented network layer protocol (e.g. TCP/IP) +and the application protocol layer (e.g. HTTP). SSL provides for secure +communication between client and server by allowing mutual authentication, the +use of digital signatures for integrity, and encryption for privacy. +<p> +The protocol is designed to support a range of choices for specific algorithms +used for cryptography, digests, and signatures. This allows algorithm +selection for specific servers to be made based on legal, export or other +concerns, and also enables the protocol to take advantage of new algorithms. +Choices are negotiated between client and server at the start of establishing +a protocol session. +<p> +<div align="center"> +<a name="table4"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Table 4: Versions of the SSL protocol</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table> +<tr valign="top"> +<td><b>Version:</b></td> +<td><b>Source:</b></td> +<td><b>Description:</b></td> +<td><b>Browser Support:</b></td> +</tr> +<tr valign="top"> +<td>SSL v2.0</td> +<td>Vendor Standard (from Netscape Corp.) [<a href="#SSL2">SSL2</a>]</td> +<td>First SSL protocol for which implementations exists</td> +<td>- NS Navigator 1.x/2.x<br> + - MS IE 3.x<br> + - Lynx/2.8+SSLeay +</td> +</tr> +<tr valign="top"> +<td>SSL v3.0</td> +<td>Expired Internet Draft (from Netscape Corp.) [<a href="#SSL3">SSL3</a>]</td> +<td>Revisions to prevent specific security attacks, add non-RSA ciphers, and support for certificate chains</td> +<td>- NS Navigator 2.x/3.x/4.x<br> + - MS IE 3.x/4.x<br> + - Lynx/2.8+SSLeay +</td> +</tr> +<tr valign="top"> +<td>TLS v1.0</td> +<td>Proposed Internet Standard (from IETF) [<a href="#TLS1">TLS1</a>]</td> +<td>Revision of SSL 3.0 to update the MAC layer to HMAC, add block padding for + block ciphers, message order standardization and more alert messages. +</td> +<td>- Lynx/2.8+SSLeay</td> +</table></td> +</tr></table> +</td></tr></table> +</div> +<p> +There are a number of versions of the SSL protocol, as shown in <a +href="#table4">Table 4</a>. As noted there, one of the benefits in SSL 3.0 is +that it adds support of certificate chain loading. This feature allows a +server to pass a server certificate along with issuer certificates to the +browser. Chain loading also permits the browser to validate the server +certificate, even if Certificate Authority certificates are not installed for +the intermediate issuers, since they are included in the certificate chain. +SSL 3.0 is the basis for the Transport Layer Security [<A +HREF="#TLS1">TLS</A>] protocol standard, currently in development by the +Internet Engineering Task Force (IETF). +<H3><a name="ToC12">Session Establishment</a></H3> +The SSL session is established by following a <I>handshake sequence</I> +between client and server, as shown in <a href="#figure1">Figure 1</a>. This +sequence may vary, depending on whether the server is configured to provide a +server certificate or request a client certificate. Though cases exist where +additional handshake steps are required for management of cipher information, +this article summarizes one common scenario: see the SSL specification for the +full range of possibilities. +<p> +<div align="center"><b>Note</b></div> +Once an SSL session has been established it may be reused, thus avoiding the +performance penalty of repeating the many steps needed to start a session. +For this the server assigns each SSL session a unique session identifier which +is cached in the server and which the client can use on forthcoming +connections to reduce the handshake (until the session identifer expires in +the cache of the server). +<p> +<div align="center"> +<a name="figure1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Figure 1: Simplified SSL Handshake Sequence</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><img src="ssl_intro_fig1.gif" alt="" width="423" height="327"></td> +</tr></table> +</td></tr></table> +</div> +<p> +The elements of the handshake sequence, as used by the client and server, are +listed below: +<ol> +<li>Negotiate the Cipher Suite to be used during data transfer +<li>Establish and share a session key between client and server +<li>Optionally authenticate the server to the client +<li>Optionally authenticate the client to the server +</ol> +<p> +The first step, Cipher Suite Negotiation, allows the client and server to +choose a Cipher Suite supportable by both of them. The SSL3.0 protocol +specification defines 31 Cipher Suites. A Cipher Suite is defined by the +following components: +<ul> +<li>Key Exchange Method +<li>Cipher for Data Transfer +<li>Message Digest for creating the Message Authentication Code (MAC) +</ul> +These three elements are described in the sections that follow. +<H3><a name="ToC13">Key Exchange Method</a></H3> +The key exchange method defines how the shared secret symmetric cryptography +key used for application data transfer will be agreed upon by client and +server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of +key exchange algorithms including the RSA key exchange when certificates are +used, and Diffie-Hellman key exchange for exchanging keys without certificates +and without prior communication between client and server. +<p> +One variable in the choice of key exchange methods is digital signatures -- +whether or not to use them, and if so, what kind of signatures to use. +Signing with a private key provides assurance against a +man-in-the-middle-attack during the information exchange used in generating +the shared key [<a href="#AC96">AC96</a>, p516]. +<H3><a name="ToC14">Cipher for Data Transfer</a></H3> +SSL uses the conventional cryptography algorithm (symmetric cryptography) +described earlier for encrypting messages in a session. There are nine +choices, including the choice to perform no encryption: +<ul> +<li>No encryption +<li>Stream Ciphers + <ul> + <li>RC4 with 40-bit keys + <li>RC4 with 128-bit keys + </ul> +<li>CBC Block Ciphers + <ul> + <li>RC2 with 40 bit key + <li>DES with 40 bit key + <li>DES with 54 bit key + <li>Triple-DES with 168 bit key + <li>Idea (128 bit key) + <li>Fortezza (96 bit key) + </ul> +</ul> +Here "CBC" refers to Cipher Block Chaining, which means that a portion of the +previously encrypted cipher text is used in the encryption of the current +block. "DES" refers to the Data Encryption Standard [<a href="#AC96">AC96</a>, +ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" +is one of the best and cryptographically strongest available algorithms, and +"RC2" is a proprietary algorithm from RSA DSI [<a href="#AC96">AC96</a>, +ch13]. +<H3><a name="ToC15">Digest Function</a></H3> +The choice of digest function determines how a digest is created from a record +unit. SSL supports the following: +<ul> +<li>No digest (Null choice) +<li>MD5, a 128-bit hash +<li>Secure Hash Algorithm (SHA-1), a 160-bit hash +</ul> +The message digest is used to create a Message Authentication Code (MAC) which +is encrypted with the message to provide integrity and to prevent against +replay attacks. +<H3><a name="ToC16">Handshake Sequence Protocol</a></H3> +The handshake sequence uses three protocols: +<ul> +<li>The <em>SSL Handshake Protocol</em> + for performing the client and server SSL session establishment. +<li>The <em>SSL Change Cipher Spec Protocol</em> for actually establishing agreement + on the Cipher Suite for the session. +<li>The <em>SSL Alert Protocol</em> for + conveying SSL error messages between client and server. +</ul> +These protocols, as well as application protocol data, are encapsulated in the +<em>SSL Record Protocol</em>, as shown in <a href="#figure2">Figure 2</a>. An +encapsulated protocol is transferred as data by the lower layer protocol, +which does not examine the data. The encapsulated protocol has no knowledge of +the underlying protocol. +<p> +<div align="center"> +<a name="figure2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Figure 2: SSL Protocol Stack</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><img src="ssl_intro_fig2.gif" alt="" width="428" height="217"></td> +</tr></table> +</td></tr></table> +</div> +<p> +The encapsulation of SSL control protocols by the record protocol means that +if an active session is renegotiated the control protocols will be transmitted +securely. If there were no session before, then the Null cipher suite is +used, which means there is no encryption and messages have no integrity +digests until the session has been established. +<H3><a name="ToC17">Data Transfer</a></H3> +The SSL Record Protocol, shown in <a href="#figure3">Figure 3</a>, is used to +transfer application and SSL Control data between the client and server, +possibly fragmenting this data into smaller units, or combining multiple +higher level protocol data messages into single units. It may compress, attach +digest signatures, and encrypt these units before transmitting them using the +underlying reliable transport protocol (Note: currently all major SSL +implementations lack support for compression). +<p> +<div align="center"> +<a name="figure3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Figure 3: SSL Record Protocol</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><img src="ssl_intro_fig3.gif" alt="" width="423" height="323"></td> +</tr></table> +</td></tr></table> +</div> +<H3><a name="ToC18">Securing HTTP Communication</a></H3> +One common use of SSL is to secure Web HTTP communication between a browser +and a webserver. This case does not preclude the use of non-secured HTTP. The +secure version is mainly plain HTTP over SSL (named HTTPS), but with one major +difference: it uses the URL scheme <code>https</code> rather than +<code>http</code> and a different server port (by default 443). This mainly +is what mod_ssl provides to you for the Apache webserver... +<H2><a name="ToC19">References</a></H2> +<ul> +<p> +<li><a name="AC96"></a> +[AC96] Bruce Schneier, <em>Applied Cryptography</em>, 2nd Edition, Wiley, + 1996. See <a href="http://www.counterpane.com/">http://www.counterpane.com/</a> for + various other materials by Bruce Schneier. +<p> +<li><a name="X208"></a> +[X208] ITU-T Recommendation X.208, <em>Specification of Abstract Syntax Notation + One (ASN.1)</em>, 1988. See for instance <a + href="ftp://ftp.neda.com/pub/itu/x.series/x208.ps"> + ftp://ftp.neda.com/pub/itu/x.series/x208.ps</a>. +<p> +<li><a name="X509"></a> +[X509] ITU-T Recommendation X.509, <em>The Directory - Authentication + Framework</em>, 1988. See for instance <a + href="ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc"> + ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc</a>. +<p> +<li><a name="PKCS"></a> +[PKCS] Kaliski, Burton S., Jr., <em>An Overview of the PKCS Standards</em>, An RSA + Laboratories Technical Note, revised November 1, 1993. + See <a href="http://www.rsa.com/rsalabs/pubs/PKCS/"> + http://www.rsa.com/rsalabs/pubs/PKCS/</a>. +<p> +<li><a name="MIME"></a> +[MIME] N. Freed, N. Borenstein, <em>ultipurpose Internet Mail Extensions + (MIME) Part One: Format of Internet Message Bodies</em>, RFC2045. + See for instance <a href="ftp://ftp.isi.edu/in-notes/rfc2045.txt"> + ftp://ftp.isi.edu/in-notes/rfc2045.txt</a>. +<p> +<li><a name="SSL2"></a> +[SSL2] Kipp E.B. Hickman, <em>The SSL Protocol</em>, 1995. + See <a href="http://www.netscape.com/eng/security/SSL_2.html"> + http://www.netscape.com/eng/security/SSL_2.html</a>. +<p> +<li><a name="SSL3"></a> +[SSL3] Alan O. Freier, Philip Karlton, Paul C. Kocher, <em>The SSL Protocol + Version 3.0</em>, 1996. See <a + href="http://www.netscape.com/eng/ssl3/draft302.txt"> + http://www.netscape.com/eng/ssl3/draft302.txt</a>. +<p> +<li><a name="TLS1"></a> +[TLS1] Tim Dierks, Christopher Allen, <em>The TLS Protocol Version 1.0</em>, + 1997. See <a + href="ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt"> + ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt</a>. +</ul> + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="ssl_overview.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">Overview</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_reference.html" + onMouseOver="ro_imgOver('ro_img_next_bot', 'next page'); return true" + onMouseOut="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">Reference</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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.wml new file mode 100644 index 00000000000..b41545b90ab --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro.wml @@ -0,0 +1,644 @@ + +#use "ssl_template.inc" title="Introduction" tag=intro num=2 + +<page_prev name="Overview" url="ssl_overview.html"> +<page_next name="Reference" url="ssl_reference.html"> + +#use wml::std::toc style=nbsp + +<quotation width=400 + author="A. Tannenbaum, ``Introduction to Computer Networks''"> +``The nice thing about standards is that there are so many to choose from. +And if you really don't like all the standards you just have to wait another +year until the one arises you are looking for.'' +</quotation> + +<p> +<table cellspacing=0 cellpadding=0 border=0> +<tr valign=bottom> +<td> + +<big A>s an introduction this chapter is aimed at readers who are familiar +with the Web, HTTP, and Apache, but are not security experts. It is not +intended to be a definitive guide to the SSL protocol, nor does it discuss +specific techniques for managing certificates in an organization, or the +important legal issues of patents and import and export restrictions. Rather, +it is intended to provide a common background to mod_ssl users by pulling +together various concepts, definitions, and examples as a starting point for +further exploration. + +<p> +The presented content is mainly derived, with permission by the author, from +the article <a +href="http://www.ultranet.com/~fhirsch/Papers/wwwj/index.html"><em>Introducing SSL +and Certificates using SSLeay</em></a> from <a +href="http://www.ultranet.com/~fhirsch/">Frederick J. Hirsch</a>, of The Open +Group Research Institute, which was published in <a +href="http://www.ora.com/catalog/wjsum97/"><em>Web Security: A Matter of +Trust</em></a>, World Wide Web Journal, Volume 2, Issue 3, Summer 1997. +Please send any postive feedback to <a +href="mailto:fjh@alum.mit.edu">Frederick Hirsch</a> (the original +article author) and all negative feedback to <a +href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> (the mod_ssl +author). + +</td> +<td> + +</td> +<td> + +<div align=right> +<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff"> +<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> +<toc> +</font> +</td> +</tr> +</table> +</div> + +</td> +</tr> +</table> + +<h2>Cryptographic Techniques</h2> + +Understanding SSL requires an understanding of cryptographic algorithms, +message digest functions (aka. one-way or hash functions), and digital +signatures. These techniques are the subject of entire books (see for instance +[<a href="#AC96">AC96</a>]) and provide the basis for privacy, integrity, and +authentication. + +<h3>Cryptographic Algorithms</h3> + +Suppose Alice wants to send a message to her bank to transfer some money. +Alice would like the message to be private, since it will include information +such as her account number and transfer amount. One solution is to use a +cryptographic algorithm, a technique that would transform her message into an +encrypted form, unreadable except by those it is intended for. Once in this +form, the message may only be interpreted through the use of a secret key. +Without the key the message is useless: good cryptographic algorithms make it +so difficult for intruders to decode the original text that it isn't worth +their effort. + +<p> +There are two categories of cryptographic algorithms: +conventional and public key. + +<ul> +<li><em>Conventional cryptography</em>, also known as symmetric +cryptography, requires the sender and receiver to share a key: a secret +piece of information that may be used to encrypt or decrypt a message. +If this key is secret, then nobody other than the sender or receiver may +read the message. If Alice and the bank know a secret key, then they +may send each other private messages. The task of privately choosing a key +before communicating, however, can be problematic. + +<p> +<li><em>Public key cryptography</em>, also known as asymmetric cryptography, +solves the key exchange problem by defining an algorithm which uses two keys, +each of which may be used to encrypt a message. If one key is used to encrypt +a message then the other must be used to decrypt it. This makes it possible +to receive secure messages by simply publishing one key (the public key) and +keeping the other secret (the private key). + +<p> +Anyone may encrypt a message using the public key, but only the owner of the +private key will be able to read it. In this way, Alice may send private +messages to the owner of a key-pair (the bank), by encrypting it using their +public key. Only the bank will be able to decrypt it. +</ul> + +<h3>Message Digests</h3> + +Although Alice may encrypt her message to make it private, there is still a +concern that someone might modify her original message message or substitute +it with a different one, in order to transfer the money to themselves, for +instance. One way of guaranteeing the integrity of Alice's message is to +create a concise summary of her message and send this to the bank as well. +Upon receipt of the message, the bank creates its own summary and compares it +with the one Alice sent. If they agree then the message was received intact. + +<p> +A summary such as this is called a <em>message digest</em>, <em>one-way +function</em> or <em>hash function</em>. Message digests are used to create +short, fixed-length representations of longer, variable-length messages. +Digest algorithms are designed to produce unique digests for different +messages. Message digests are designed to make it too difficult to determine +the message from the digest, and also impossible to find two different +messages which create the same digest -- thus eliminating the possibility of +substituting one message for another while maintaining the same digest. + +<p> +Another challenge that Alice faces is finding a way to send the digest to the +bank securely; when this is achieved, the integrity of the associated message +is assured. One way to to this is to include the digest in a digital +signature. + +<h3>Digital Signatures</h3> + +When Alice sends a message to the bank, the bank needs to ensure that the +message is really from her, so an intruder does not request a transaction +involving her account. A <em>digital signature</em>, created by Alice and +included with the message, serves this purpose. + +<p> +Digital signatures are created by encrypting a digest of the message, +and other information (such as a sequence number) with the sender's +private key. Though anyone may <em>decrypt</em> the signature using the public +key, only the signer knows the private key. This means that only they may +have signed it. Including the digest in the signature means the signature is +only good for that message; it also ensures the integrity of the message since +no one can change the digest and still sign it. + +<p> +To guard against interception and reuse of the signature by an intruder at a +later date, the signature contains a unique sequence number. This protects +the bank from a fraudulent claim from Alice that she did not send the message +-- only she could have signed it (non-repudiation). + +<h2>Certificates</h2> + +Although Alice could have sent a private message to the bank, signed it, and +ensured the integrity of the message, she still needs to be sure that she is +really communicating with the bank. This means that she needs to be sure that +the public key she is using corresponds to the bank's private key. Similarly, +the bank also needs to verify that the message signature really corresponds to +Alice's signature. + +<p> +If each party has a certificate which validates the other's identity, confirms +the public key, and is signed by a trusted agency, then they both will be +assured that they are communicating with whom they think they are. Such a +trusted agency is called a <em>Certificate Authority</em>, and certificates are +used for authentication. + +<h3>Certificate Contents</h3> + +A certificate associates a public key with the real identity of an individual, +server, or other entity, known as the subject. As shown in <a +href="#table1">Table 1</a>, information about the subject includes identifying +information (the distinguished name), and the public key. It also includes +the identification and signature of the Certificate Authority that issued the +certificate, and the period of time during which the certificate is valid. It +may have additional information (or extensions) as well as administrative +information for the Certificate Authority's use, such as a serial number. + +<p> +<float name="table1" caption="Table 1: Certificate Information"> +<table> +<tr valign=top><td><b>Subject:</b></td> +<td>Distinguished Name, Public Key</td></tr> +<tr valign=top><td><b>Issuer:</b></td> +<td>Distinguished Name, Signature</td></tr> +<tr><td><b>Period of Validity:</b></td> +<td>Not Before Date, Not After Date</td></tr> +<tr><td><b>Administrative Information:</b></td> +<td>Version, Serial Number</td></TR> +<tr><td><b>Extended Information:</b></td> +<td>Basic Contraints, Netscape Flags, etc.</td></TR> +</table> +</float> + +<p> +A distinguished name is used to provide an identity in a specific context -- +for instance, an individual might have a personal certificate as well as one +for their identity as an employee. Distinguished names are defined by the +X.509 standard [<a href="#X509">X509</A>], which defines the fields, field +names, and abbreviations used to refer to the fields +(see <a href="#table2">Table 2</a>). + +<p> +<float name="table2" caption="Table 2: Distinguished Name Information"> +<table> +<tr valign=top><td><b>DN Field:</b></td><td><b>Abbrev.:</b></td><td><b>Description:</b></td> +<td><b>Example:</b></td> +</t> +<tr valign=top><td>Common Name</td><td>CN</td> +<td>Name being certified</td><td>CN=Joe Average</td></tr> +<tr valign=top><td>Organization or Company</td><td>O</td> +<td>Name is associated with this<br>organization</td><td>O=Snake Oil, Ltd.</td></tr> +<tr valign=top><td>Organizational Unit</td><td>OU</td> +<td>Name is associated with this <br>organization unit, such as a department</td><td>OU=Research Institute</td></tr> +<tr valign=top><td>City/Locality</td><td>L</td> +<td>Name is located in this City</td><td>L=Snake City</td></tr> +<tr valign=top><td>State/Province</td><td>ST</td> +<td>Name is located in this State/Province</td><td>ST=Desert</td></tr> +<tr valign=top><td>Country</td><td>C</td> +<td>Name is located in this Country (ISO code)</td><td>C=XZ</td></tr> +</table> +</float> + +<p> +A Certificate Authority may define a policy specifying which distinguished +field names are optional, and which are required. It may also place +requirements upon the field contents, as may users of certificates. As an +example, a Netscape browser requires that the Common Name for a certificate +representing a server has a name which matches a wildcard pattern for the +domain name of that server, such as <code>*.snakeoil.com</code>. + +<p> +The binary format of a certificate is defined using the ASN.1 notation [ <a +href="#X208">X208</a>] [<a href="#PKCS">PKCS</a>]. This notation defines how to +specify the contents, and encoding rules define how this information is +translated into binary form. The binary encoding of the certificate is +defined using Distinguished Encoding Rules (DER), which are based on the more +general Basic Encoding Rules (BER). For those transmissions which cannot +handle binary, the binary form may be translated into an ASCII form by using +Base64 encoding [<a href="#MIME">MIME</a>]. This encoded version is called PEM +encoded (the name comes from "Privacy Enhanced Mail"), when placed between +begin and end delimiter lines as illustrated in <a href="#table3">Table 3</a>. + +<p> +<float name="table3" caption="Table 3: Example of a PEM-encoded certificate (snakeoil.crt)"> +<table cellspacing=0 cellpadding=0><tr><td> +<div class="code"><pre> +-----BEGIN CERTIFICATE----- +MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx +FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG +A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv +cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz +bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL +MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h +a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl +cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN +AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB +gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b +vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa +lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV +HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB +gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt +2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7 +dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ== +-----END CERTIFICATE-----</pre></div> +</td></tr></table> +</float> + +<h3>Certificate Authorities</h3> + +By first verifying the information in a certificate request before granting +the certificate, the Certificate Authority assures the identity of the private +key owner of a key-pair. For instance, if Alice requests a personal +certificate, the Certificate Authority must first make sure that Alice really +is the person the certificate request claims. + +<h4>Certificate Chains</h4> + +A Certificate Authority may also issue a certificate for another Certificate +Authority. When examining a certificate, Alice may need to examine the +certificate of the issuer, for each parent Certificate Authority, until +reaching one which she has confidence in. She may decide to trust only +certificates with a limited chain of issuers, to reduce her risk of a "bad" +certificate in the chain. + +<h4>Creating a Root-Level CA</h4> + +As noted earlier, each certificate requires an issuer to assert the validity +of the identity of the certificate subject, up to the top-level Certificate +Authority (CA). This presents a problem: Since this is who vouches for the +certificate of the top-level authority, which has no issuer? + +In this unique case, the certificate is "self-signed", so the issuer of the +certificate is the same as the subject. As a result, one must exercise extra +care in trusting a self-signed certificate. The wide publication of a public +key by the root authority reduces the risk in trusting this key -- it would be +obvious if someone else publicized a key claiming to be the authority. +Browsers are preconfigured to trust well-known certificate authorities. + +<p> +A number of companies, such as <a href="http://www.thawte.com/">Thawte</a> and +<a href="http://www.verisign.com/">VeriSign</a> have established themselves as +Certificate Authorities. These companies provide the following services: + +<ul> +<li>Verifying certificate requests +<li>Processing certificate requests +<li>Issuing and managing certificates +</ul> + +<p> +It is also possible to create your own Certificate Authority. Although risky +in the Internet environment, it may be useful within an Intranet where the +organization can easily verify the identities of individuals and servers. + +<h4>Certificate Management</h4> + +Establishing a Certificate Authority is a responsibility which requires a +solid administrative, technical, and management framework. + +Certificate Authorities not only issue certificates, they also manage them -- +that is, they determine how long certificates are valid, they renew them, and +they keep lists of certificates that have already been issued but are no +longer valid (Certificate Revocation Lists, or CRLs). + +Say Alice is entitled to a certificate as an employee of a company. Say too, +that the certificate needs to be revoked when Alice leaves the company. Since +certificates are objects that get passed around, it is impossible to tell from +the certificate alone that it has been revoked. + +When examining certificates for validity, therefore, it is necessary to +contact the issuing Certificate Authority to check CRLs -- this is not usually +an automated part of the process. + +<p> +<center><B>Note:</B></center> +If you use a Certificate Authority that is not configured into browsers by +default, it is necessary to load the Certificate Authority certificate into +the browser, enabling the browser to validate server certificates signed by +that Certificate Authority. Doing so may be dangerous, since once loaded, the +browser will accept all certificates signed by that Certificate Authority. + +<h2>Secure Sockets Layer (SSL)</h2> + +The Secure Sockets Layer protocol is a protocol layer which may be placed +between a reliable connection-oriented network layer protocol (e.g. TCP/IP) +and the application protocol layer (e.g. HTTP). SSL provides for secure +communication between client and server by allowing mutual authentication, the +use of digital signatures for integrity, and encryption for privacy. + +<p> +The protocol is designed to support a range of choices for specific algorithms +used for cryptography, digests, and signatures. This allows algorithm +selection for specific servers to be made based on legal, export or other +concerns, and also enables the protocol to take advantage of new algorithms. +Choices are negotiated between client and server at the start of establishing +a protocol session. + +<p> +<float name="table4" caption="Table 4: Versions of the SSL protocol"> +<table> +<tr valign=top> +<td><b>Version:</b></td> +<td><b>Source:</b></td> +<td><b>Description:</b></td> +<td><b>Browser Support:</b></td> +</tr> +<tr valign=top> +<td>SSL v2.0</td> +<td>Vendor Standard (from Netscape Corp.) [<a href="#SSL2">SSL2</a>]</td> +<td>First SSL protocol for which implementations exists</td> +<td>- NS Navigator 1.x/2.x<br> + - MS IE 3.x<br> + - Lynx/2.8+SSLeay +</td> +</tr> +<tr valign=top> +<td>SSL v3.0</td> +<td>Expired Internet Draft (from Netscape Corp.) [<a href="#SSL3">SSL3</a>]</td> +<td>Revisions to prevent specific security attacks, add non-RSA ciphers, and support for certificate chains</td> +<td>- NS Navigator 2.x/3.x/4.x<br> + - MS IE 3.x/4.x<br> + - Lynx/2.8+SSLeay +</td> +</tr> +<tr valign=top> +<td>TLS v1.0</td> +<td>Proposed Internet Standard (from IETF) [<a href="#TLS1">TLS1</a>]</td> +<td>Revision of SSL 3.0 to update the MAC layer to HMAC, add block padding for + block ciphers, message order standardization and more alert messages. +</td> +<td>- Lynx/2.8+SSLeay</td> +</table> +</float> + +<p> +There are a number of versions of the SSL protocol, as shown in <a +href="#table4">Table 4</a>. As noted there, one of the benefits in SSL 3.0 is +that it adds support of certificate chain loading. This feature allows a +server to pass a server certificate along with issuer certificates to the +browser. Chain loading also permits the browser to validate the server +certificate, even if Certificate Authority certificates are not installed for +the intermediate issuers, since they are included in the certificate chain. +SSL 3.0 is the basis for the Transport Layer Security [<A +HREF="#TLS1">TLS</A>] protocol standard, currently in development by the +Internet Engineering Task Force (IETF). + +<h3>Session Establishment</h3> + +The SSL session is established by following a <I>handshake sequence</I> +between client and server, as shown in <a href="#figure1">Figure 1</a>. This +sequence may vary, depending on whether the server is configured to provide a +server certificate or request a client certificate. Though cases exist where +additional handshake steps are required for management of cipher information, +this article summarizes one common scenario: see the SSL specification for the +full range of possibilities. + +<p> +<center><b>Note</b></center> +Once an SSL session has been established it may be reused, thus avoiding the +performance penalty of repeating the many steps needed to start a session. +For this the server assigns each SSL session a unique session identifier which +is cached in the server and which the client can use on forthcoming +connections to reduce the handshake (until the session identifer expires in +the cache of the server). + +<p> +<float name="figure1" caption="Figure 1: Simplified SSL Handshake Sequence"> +<img src="ssl_intro_fig1.gif" alt=""> +</float> + +<p> +The elements of the handshake sequence, as used by the client and server, are +listed below: + +<ol> +<li>Negotiate the Cipher Suite to be used during data transfer +<li>Establish and share a session key between client and server +<li>Optionally authenticate the server to the client +<li>Optionally authenticate the client to the server +</ol> + +<p> +The first step, Cipher Suite Negotiation, allows the client and server to +choose a Cipher Suite supportable by both of them. The SSL3.0 protocol +specification defines 31 Cipher Suites. A Cipher Suite is defined by the +following components: + +<ul> +<li>Key Exchange Method +<li>Cipher for Data Transfer +<li>Message Digest for creating the Message Authentication Code (MAC) +</ul> + +These three elements are described in the sections that follow. + +<h3>Key Exchange Method</h3> + +The key exchange method defines how the shared secret symmetric cryptography +key used for application data transfer will be agreed upon by client and +server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of +key exchange algorithms including the RSA key exchange when certificates are +used, and Diffie-Hellman key exchange for exchanging keys without certificates +and without prior communication between client and server. + +<p> +One variable in the choice of key exchange methods is digital signatures -- +whether or not to use them, and if so, what kind of signatures to use. +Signing with a private key provides assurance against a +man-in-the-middle-attack during the information exchange used in generating +the shared key [<a href="#AC96">AC96</a>, p516]. + +<h3>Cipher for Data Transfer</h3> + +SSL uses the conventional cryptography algorithm (symmetric cryptography) +described earlier for encrypting messages in a session. There are nine +choices, including the choice to perform no encryption: + +<ul> +<li>No encryption +<li>Stream Ciphers + <ul> + <li>RC4 with 40-bit keys + <li>RC4 with 128-bit keys + </ul> +<li>CBC Block Ciphers + <ul> + <li>RC2 with 40 bit key + <li>DES with 40 bit key + <li>DES with 54 bit key + <li>Triple-DES with 168 bit key + <li>Idea (128 bit key) + <li>Fortezza (96 bit key) + </ul> +</ul> + +Here "CBC" refers to Cipher Block Chaining, which means that a portion of the +previously encrypted cipher text is used in the encryption of the current +block. "DES" refers to the Data Encryption Standard [<a href="#AC96">AC96</a>, +ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" +is one of the best and cryptographically strongest available algorithms, and +"RC2" is a proprietary algorithm from RSA DSI [<a href="#AC96">AC96</a>, +ch13]. + +<h3>Digest Function</h3> + +The choice of digest function determines how a digest is created from a record +unit. SSL supports the following: + +<ul> +<li>No digest (Null choice) +<li>MD5, a 128-bit hash +<li>Secure Hash Algorithm (SHA-1), a 160-bit hash +</ul> + +The message digest is used to create a Message Authentication Code (MAC) which +is encrypted with the message to provide integrity and to prevent against +replay attacks. + +<h3>Handshake Sequence Protocol</h3> + +The handshake sequence uses three protocols: + +<ul> +<li>The <em>SSL Handshake Protocol</em> + for performing the client and server SSL session establishment. +<li>The <em>SSL Change Cipher Spec Protocol</em> for actually establishing agreement + on the Cipher Suite for the session. +<li>The <em>SSL Alert Protocol</em> for + conveying SSL error messages between client and server. +</ul> + +These protocols, as well as application protocol data, are encapsulated in the +<em>SSL Record Protocol</em>, as shown in <a href="#figure2">Figure 2</a>. An +encapsulated protocol is transferred as data by the lower layer protocol, +which does not examine the data. The encapsulated protocol has no knowledge of +the underlying protocol. + +<p> +<float name="figure2" caption="Figure 2: SSL Protocol Stack"> +<img src="ssl_intro_fig2.gif" alt=""> +</float> + +<p> +The encapsulation of SSL control protocols by the record protocol means that +if an active session is renegotiated the control protocols will be transmitted +securely. If there were no session before, then the Null cipher suite is +used, which means there is no encryption and messages have no integrity +digests until the session has been established. + +<h3>Data Transfer</h3> + +The SSL Record Protocol, shown in <a href="#figure3">Figure 3</a>, is used to +transfer application and SSL Control data between the client and server, +possibly fragmenting this data into smaller units, or combining multiple +higher level protocol data messages into single units. It may compress, attach +digest signatures, and encrypt these units before transmitting them using the +underlying reliable transport protocol (Note: currently all major SSL +implementations lack support for compression). + +<p> +<float name="figure3" caption="Figure 3: SSL Record Protocol"> +<img src="ssl_intro_fig3.gif" alt=""> +</float> + +<h3>Securing HTTP Communication</h3> + +One common use of SSL is to secure Web HTTP communication between a browser +and a webserver. This case does not preclude the use of non-secured HTTP. The +secure version is mainly plain HTTP over SSL (named HTTPS), but with one major +difference: it uses the URL scheme <code>https</code> rather than +<code>http</code> and a different server port (by default 443). This mainly +is what mod_ssl provides to you for the Apache webserver... + +<h2>References</h2> + +<ul> + +<p> +<li><a name="AC96"></a> +[AC96] Bruce Schneier, <em>Applied Cryptography</em>, 2nd Edition, Wiley, + 1996. See <a href="http://www.counterpane.com/">http://www.counterpane.com/</a> for + various other materials by Bruce Schneier. +<p> +<li><a name="X208"></a> +[X208] ITU-T Recommendation X.208, <em>Specification of Abstract Syntax Notation + One (ASN.1)</em>, 1988. See for instance <a + href="ftp://ftp.neda.com/pub/itu/x.series/x208.ps"> + ftp://ftp.neda.com/pub/itu/x.series/x208.ps</a>. +<p> +<li><a name="X509"></a> +[X509] ITU-T Recommendation X.509, <em>The Directory - Authentication + Framework</em>, 1988. See for instance <a + href="ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc"> + ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc</a>. +<p> +<li><a name="PKCS"></a> +[PKCS] Kaliski, Burton S., Jr., <em>An Overview of the PKCS Standards</em>, An RSA + Laboratories Technical Note, revised November 1, 1993. + See <a href="http://www.rsa.com/rsalabs/pubs/PKCS/"> + http://www.rsa.com/rsalabs/pubs/PKCS/</a>. +<p> +<li><a name="MIME"></a> +[MIME] N. Freed, N. Borenstein, <em>ultipurpose Internet Mail Extensions + (MIME) Part One: Format of Internet Message Bodies</em>, RFC2045. + See for instance <a href="ftp://ftp.isi.edu/in-notes/rfc2045.txt"> + ftp://ftp.isi.edu/in-notes/rfc2045.txt</a>. +<p> +<li><a name="SSL2"></a> +[SSL2] Kipp E.B. Hickman, <em>The SSL Protocol</em>, 1995. + See <a href="http://www.netscape.com/eng/security/SSL_2.html"> + http://www.netscape.com/eng/security/SSL_2.html</a>. +<p> +<li><a name="SSL3"></a> +[SSL3] Alan O. Freier, Philip Karlton, Paul C. Kocher, <em>The SSL Protocol + Version 3.0</em>, 1996. See <a + href="http://www.netscape.com/eng/ssl3/draft302.txt"> + http://www.netscape.com/eng/ssl3/draft302.txt</a>. +<p> +<li><a name="TLS1"></a> +[TLS1] Tim Dierks, Christopher Allen, <em>The TLS Protocol Version 1.0</em>, + 1997. See <a + href="ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt"> + ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt</a>. +</ul> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig1.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig1.gif Binary files differnew file mode 100644 index 00000000000..3c209864f19 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig1.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig2.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig2.gif Binary files differnew file mode 100644 index 00000000000..26b295a67b0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig2.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig3.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig3.gif Binary files differnew file mode 100644 index 00000000000..00a975b5a4e --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_intro_fig3.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.gfont000.gif Binary files differnew file mode 100644 index 00000000000..7fb5db91b00 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.html new file mode 100644 index 00000000000..deae6966c54 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.html @@ -0,0 +1,509 @@ +<html> +<head> +<title>mod_ssl: Preface</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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-1.gif" alt="1" 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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="index.html" + onMouseOver="ro_imgOver('ro_img_prev_top', 'previous page'); return true" + onMouseOut="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">Cover</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_intro.html" + onMouseOver="ro_imgOver('ro_img_next_top', 'next page'); return true" + onMouseOut="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">Introduction</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-over.gif" alt="Preface" width="456" height="60"> + </td> + </tr> + </table> +<DIV align="right"> +<table cellspacing="0" cellpadding="0" width="300"> +<tr> +<td> +<em>``Ralf Engelschall has released an +excellent module that integrates +Apache and SSLeay.''</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Tim J. Hudson, SSLeay co-author +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> +<img src="ssl_overview.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> +his module provides strong cryptography for the <A +HREF="http://www.apache.org/">Apache</A> (v1.3) webserver via the <A +HREF="http://www.netscape.com/newsref/std/SSL.html">Secure Socket Layer</A> +(SSL v2/v3) and <A HREF="http://www.consensus.com/ietf-tls/">Transport Layer +Security</A> (TLS v1) protocols by the help of the excellent SSL/TLS +implementation library <A HREF="http://www.ssleay.org/">SSLeay</A> from <A +HREF="mailto:eay@cryptsoft.com">Eric A. Young</A> and <A +HREF="mailto:tjh@cryptsoft.com">Tim Hudson</A>. +</td> +<td> + +</td> +<td> +<DIV align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff"> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Global Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> +<b> +<a href="ssl_overview.html">Chapter 1: Preface</a><br> +<a href="ssl_intro.html">Chapter 2: Introduction</a><br> +<a href="ssl_reference.html">Chapter 3: Reference</a><br> +<a href="ssl_compat.html">Chapter 4: Compatibility</a><br> +<a href="ssl_howto.html">Chapter 5: HowTo</a><br> +<a href="ssl_faq.html">Chapter 6: F.A.Q. List</a><br> +<a href="ssl_glossary.html">Chapter 7: Glossary</a><br> +</b> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<p> +The <A HREF="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</A> package was +created in April 1998 by <A HREF="mailto:rse@engelschall.com">Ralf S. +Engelschall</A> and was originally derived from the <A +HREF="http://www.apache-ssl.org/">Apache-SSL</A> package developed by <A +HREF="mailto:ben@algroup.co.uk">Ben Laurie</A>. It stays under a BSD-style +license which is equivalent to the license used by <A +HREF="http://www.apache.org/">The Apache Group</a> for the Apache webserver +itself. This means, in short, that you are free to use it both for commercial +and non-commercial purposes as long as you retain the authors' copyright +notices and give the proper credit. +<h2>Legalese</h2> +Although the above conditions also apply to Apache and SSLeay in general (both +are freely available and useable software packages), you should be aware that +especially the cryptographic algorithms used inside SSLeay stay under +certain patents and perhaps import/export/use restrictions in some countries +of the world. So whether you can actually use the combination +Apache+mod_ssl+SSLeay in your country depends mainly on your local state laws. +The authors of neither Apache nor mod_ssl nor SSLeay are liable for any +violations you make here. +<p> +If you're not sure what law details apply to your country you're strongly +advises to first determine them by consulting an attorney before using this +module. A lot of hints you can find in the <a +href="http://cwis.kub.nl/~frw/people/koops/lawsurvy.htm">International Law +Crypto Survey</a> which is a really comprehensive resource on this topic. At +least two countries with heavy cryptography restrictions are well known: +In the Unisted States (USA) first it's not allowed to (re-)export mod_ssl +or SSLeay and second it's not allowed to use Apache+mod_ssl+SSLeay (because of +patent issues on the RSA and RC4 algorithms) unless SSLeay is built with RSA +DSI's RSAref package and used for non-commercial purposes only. And inside +France it's not allowed to use any cryptography at all when keys with more +than 40 bits are used. +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" cellspacing="0" cellpadding="10" border="0"> +<tr> +<td><font face="Arial,Helvetica"> +This software package uses strong cryptography, so while it is created, +maintained and distributed from Germany and Switzerland (where it is legal to +do this), it falls under certain export/import and/or use restrictions in some +other parts of the world. +<p> +PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY +SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING TECHNICAL +DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. +SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR COUNTRY, RE-DISTRIBUTE IT FROM +THERE OR EVEN JUST EMAIL TECHNICAL SUGGESTIONS OR EVEN SOURCE PATCHES TO THE +AUTHOR OR OTHER PEOPLE YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO +ANY EXPORT/IMPORT AND/OR USE LAWS WHICH APPLY TO YOU. THE AUTHOR OF MOD_SSL +IS NOT LIABLE FOR ANY VIOLATIONS YOU MAKE HERE. SO BE CAREFULLY YOURSELF, IT +IS YOUR RESPONSIBILITY. +</font> +<p> +<font face="Arial,Helvetica"> +CREDIT INFORMATION: +This product includes software developed by Ben Laurie for use in the +Apache-SSL HTTP server project, software developed by Larry Wall and David +MacKenzie for use in the GNU project of the FSF and software developed by Dr. +Stephen N. Henson as a companion to SSLeay. +</font></td> +</tr> +</table> +</td> +</tr> +</table> +<h2>Module Architecture</h2> +The mod_ssl package consists of the SSL module (part 1 in <a +href="#figure1">Figure 1</a>) and a set of source patches for Apache adding the +Extended API (EAPI) (part 2 in <a href="#figure1">Figure 1</a>) which is an +essential prerequisite in order to use mod_ssl. In other words: you can only +use the mod_ssl module when Apache's core code contains the Extended API. But +because when applying mod_ssl to the Apache source tree the Extended API is +also automatically added you usually don't have to think about this. It's +mainly important for package vendors who want to build separate packages for +Apache and mod_ssl. For more details on how to apply mod_ssl to the Apache +source tree please follow the <code>INSTALL</code> file in the mod_ssl +distribution. +<p> +<div align="center"> +<a name="figure1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0"> +<caption align="bottom" id="sf">Figure 1: Module Architecture</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><img src="ssl_overview_fig1.gif" alt="" width="382" height="281"></td> +</tr></table> +</td></tr></table> +</div> +<h2>Module Building</h2> +The SSL module (mod_ssl) resides under the <CODE>src/modules/ssl/</CODE> +subdirectory inside the Apache source tree and is a regular Apache module. This +means that you can configure, build and install it like any other Apache module. +Usually this is done by using the APACI command +<blockquote> +<pre> +$ cd apache_1.3.x/ +$ SSL_BASE=/path/to/ssleay ./configure ... --enable-module=ssl +</pre> +</blockquote> +or by manually editing the <code>SSL_BASE</code> variable, +uncommenting the corresponding <code>AddModule</code> directive inside the +<code>src/Configuration</code> file and using the command +<blockquote> +<pre> +$ cd apache_1.3.x/src +$ ./Configure +</pre> +</blockquote> +for configuring. Additionally you can enable the <a +href="http://www.apache.org/docs/dso.html">Dynamic Shared Object</a> (DSO) +support for mod_ssl by either adding the <code>--enable-shared=ssl</code> +option to the APACI configure command line or by replacing the +<blockquote> +<pre> +AddModule ssl_module modules/ssl/libssl.a +</pre> +</blockquote> +line in <code>src/Configuration</code> with +<blockquote> +<pre> +SharedModule ssl_module modules/ssl/libssl.so +</pre> +</blockquote> +Building mod_ssl as a DSO is especially interesting to achieve more run-time +flexibility, i.e. you can decide whether to use SSL or not at run-time instead +of build-time. But notice that building mod_ssl as a DSO requires that your +OS/compiler supports building DSOs in the first place, and additionally that +they support linking of a DSO against a static library (SSLeay/libdb). Not all +platform support this. + <p> + <br> + <table> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<a href="index.html" + onMouseOver="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" + onMouseOut="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">Cover</font> + </td> + <td valign="top" align="right" width="250"> +<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> +<a href="ssl_intro.html" + onMouseOver="ro_imgOver('ro_img_next_bot', 'next page'); return true" + onMouseOut="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">Introduction</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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.wml new file mode 100644 index 00000000000..85c0c682287 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview.wml @@ -0,0 +1,201 @@ + +#use "ssl_template.inc" title="Preface" tag=over num=1 + +<page_prev name="Cover" url="index.html"> +<page_next name="Introduction" url="ssl_intro.html"> + +<quotation width=300 + author="Tim J. Hudson, SSLeay co-author"> +``Ralf Engelschall has released an +excellent module that integrates +Apache and SSLeay.'' +</quotation> + +<p> +<table cellspacing=0 cellpadding=0 border=0> +<tr valign=bottom> +<td> + +<big T>his module provides strong cryptography for the <A +HREF="http://www.apache.org/">Apache</A> (v1.3) webserver via the <A +HREF="http://www.netscape.com/newsref/std/SSL.html">Secure Socket Layer</A> +(SSL v2/v3) and <A HREF="http://www.consensus.com/ietf-tls/">Transport Layer +Security</A> (TLS v1) protocols by the help of the excellent SSL/TLS +implementation library <A HREF="http://www.ssleay.org/">SSLeay</A> from <A +HREF="mailto:eay@cryptsoft.com">Eric A. Young</A> and <A +HREF="mailto:tjh@cryptsoft.com">Tim Hudson</A>. + +</td> +<td> + +</td> +<td> + +<div align=right> +<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff"> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Global Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size=-1> +<b> + +<a href="ssl_overview.html">Chapter 1: Preface</a><br> +<a href="ssl_intro.html">Chapter 2: Introduction</a><br> +<a href="ssl_reference.html">Chapter 3: Reference</a><br> +<a href="ssl_compat.html">Chapter 4: Compatibility</a><br> +<a href="ssl_howto.html">Chapter 5: HowTo</a><br> +<a href="ssl_faq.html">Chapter 6: F.A.Q. List</a><br> +<a href="ssl_glossary.html">Chapter 7: Glossary</a><br> + +</b> +</font> +</td> +</tr> +</table> +</div> + +</td> +</tr> +</table> + +<p> +The <A HREF="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</A> package was +created in April 1998 by <A HREF="mailto:rse@engelschall.com">Ralf S. +Engelschall</A> and was originally derived from the <A +HREF="http://www.apache-ssl.org/">Apache-SSL</A> package developed by <A +HREF="mailto:ben@algroup.co.uk">Ben Laurie</A>. It stays under a BSD-style +license which is equivalent to the license used by <A +HREF="http://www.apache.org/">The Apache Group</a> for the Apache webserver +itself. This means, in short, that you are free to use it both for commercial +and non-commercial purposes as long as you retain the authors' copyright +notices and give the proper credit. + +<h2>Legalese</h2> + +Although the above conditions also apply to Apache and SSLeay in general (both +are freely available and useable software packages), you should be aware that +especially the cryptographic algorithms used inside SSLeay stay under +certain patents and perhaps import/export/use restrictions in some countries +of the world. So whether you can actually use the combination +Apache+mod_ssl+SSLeay in your country depends mainly on your local state laws. +The authors of neither Apache nor mod_ssl nor SSLeay are liable for any +violations you make here. + +<p> +If you're not sure what law details apply to your country you're strongly +advises to first determine them by consulting an attorney before using this +module. A lot of hints you can find in the <a +href="http://cwis.kub.nl/~frw/people/koops/lawsurvy.htm">International Law +Crypto Survey</a> which is a really comprehensive resource on this topic. At +least two countries with heavy cryptography restrictions are well known: +In the Unisted States (USA) first it's not allowed to (re-)export mod_ssl +or SSLeay and second it's not allowed to use Apache+mod_ssl+SSLeay (because of +patent issues on the RSA and RC4 algorithms) unless SSLeay is built with RSA +DSI's RSAref package and used for non-commercial purposes only. And inside +France it's not allowed to use any cryptography at all when keys with more +than 40 bits are used. + +<p> +<box bdcolor="#cccccc" bdwidth=1 bdspace=10 bgcolor=white> +<font face="Arial,Helvetica"> +This software package uses strong cryptography, so while it is created, +maintained and distributed from Germany and Switzerland (where it is legal to +do this), it falls under certain export/import and/or use restrictions in some +other parts of the world. +<p> +PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY +SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING TECHNICAL +DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. +SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR COUNTRY, RE-DISTRIBUTE IT FROM +THERE OR EVEN JUST EMAIL TECHNICAL SUGGESTIONS OR EVEN SOURCE PATCHES TO THE +AUTHOR OR OTHER PEOPLE YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO +ANY EXPORT/IMPORT AND/OR USE LAWS WHICH APPLY TO YOU. THE AUTHOR OF MOD_SSL +IS NOT LIABLE FOR ANY VIOLATIONS YOU MAKE HERE. SO BE CAREFULLY YOURSELF, IT +IS YOUR RESPONSIBILITY. +</font> +<p> +<font face="Arial,Helvetica"> +CREDIT INFORMATION: +This product includes software developed by Ben Laurie for use in the +Apache-SSL HTTP server project, software developed by Larry Wall and David +MacKenzie for use in the GNU project of the FSF and software developed by Dr. +Stephen N. Henson as a companion to SSLeay. +</font> +</box> + +<h2>Module Architecture</h2> + +The mod_ssl package consists of the SSL module (part 1 in <a +href="#figure1">Figure 1</a>) and a set of source patches for Apache adding the +Extended API (EAPI) (part 2 in <a href="#figure1">Figure 1</a>) which is an +essential prerequisite in order to use mod_ssl. In other words: you can only +use the mod_ssl module when Apache's core code contains the Extended API. But +because when applying mod_ssl to the Apache source tree the Extended API is +also automatically added you usually don't have to think about this. It's +mainly important for package vendors who want to build separate packages for +Apache and mod_ssl. For more details on how to apply mod_ssl to the Apache +source tree please follow the <code>INSTALL</code> file in the mod_ssl +distribution. + +<p> +<float name="figure1" caption="Figure 1: Module Architecture"> +<img src="ssl_overview_fig1.gif" alt=""> +</float> + +<h2>Module Building</h2> + +The SSL module (mod_ssl) resides under the <CODE>src/modules/ssl/</CODE> +subdirectory inside the Apache source tree and is a regular Apache module. This +means that you can configure, build and install it like any other Apache module. +Usually this is done by using the APACI command + +<blockquote> +<pre> +$ cd apache_1.3.x/ +$ SSL_BASE=/path/to/ssleay ./configure ... --enable-module=ssl +</pre> +</blockquote> + +or by manually editing the <code>SSL_BASE</code> variable, +uncommenting the corresponding <code>AddModule</code> directive inside the +<code>src/Configuration</code> file and using the command + +<blockquote> +<pre> +$ cd apache_1.3.x/src +$ ./Configure +</pre> +</blockquote> + +for configuring. Additionally you can enable the <a +href="http://www.apache.org/docs/dso.html">Dynamic Shared Object</a> (DSO) +support for mod_ssl by either adding the <code>--enable-shared=ssl</code> +option to the APACI configure command line or by replacing the + +<blockquote> +<pre> +AddModule ssl_module modules/ssl/libssl.a +</pre> +</blockquote> + +line in <code>src/Configuration</code> with + +<blockquote> +<pre> +SharedModule ssl_module modules/ssl/libssl.so +</pre> +</blockquote> + +Building mod_ssl as a DSO is especially interesting to achieve more run-time +flexibility, i.e. you can decide whether to use SSL or not at run-time instead +of build-time. But notice that building mod_ssl as a DSO requires that your +OS/compiler supports building DSOs in the first place, and additionally that +they support linking of a DSO against a static library (SSLeay/libdb). Not all +platform support this. + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview_fig1.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview_fig1.gif Binary files differnew file mode 100644 index 00000000000..80e0e4fff03 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_overview_fig1.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.gfont000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.gfont000.gif Binary files differnew file mode 100644 index 00000000000..7fb5db91b00 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.gfont000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.html b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.html new file mode 100644 index 00000000000..5f2b4507c4b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.html @@ -0,0 +1,2195 @@ +<html> +<head> +<title>mod_ssl: Reference</title> + +<!-- + Copyright (c) 1998-1999 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.engelschall.com/sw/mod_ssl/)." + + 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.engelschall.com/sw/mod_ssl/)." + + 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> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0"> +<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"> + <tr> + <td> + <table width="600"> + <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"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<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" +><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"> +<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> +<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" +><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"> +<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"> +<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"> +<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>SSLCACertificatePath</strong></a><br> + <a href="#ToC13"><strong>SSLCACertificateFile</strong></a><br> + <a href="#ToC14"><strong>SSLVerifyClient</strong></a><br> + <a href="#ToC15"><strong>SSLVerifyDepth</strong></a><br> + <a href="#ToC16"><strong>SSLLog</strong></a><br> + <a href="#ToC17"><strong>SSLLogLevel</strong></a><br> + <a href="#ToC18"><strong>SSLOptions</strong></a><br> + <a href="#ToC19"><strong>SSLRequireSSL</strong></a><br> + <a href="#ToC20"><strong>SSLRequire</strong></a><br> +<a href="#ToC21"><strong>Additional Features</strong></a><br> + <a href="#ToC22"><strong>Environment Variables</strong></a><br> + <a href="#ToC23"><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 occur mostly +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 the configuration +directives it provides. 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 an argument of + ``<code>servername:portnumber</code>'' for which 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 one could think about it. mod_ssl just defines the + interface: an executable program which provides the Pass Phrase on + <code>stdout</code>. Nothing more or less! So, when 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 too 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 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. Notice: 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 care about conflicts yourself. +<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 underlaying 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 SSLeay 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. When + <em>bytes</em> is not specified the whole file forms the entropy. 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> +<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 it's <code>stdout</code> contents + form the entropy. When <em>bytes</em> is not specified the whole 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 at + the connection context slows down the server too dramatically, of course. + So usually you should avoid using external programs at this context. +</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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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. Because for requests to the same server process (via HTTP +keep-alive) SSLeay already caches the SSL session information locally. But +because modern clients request inlined images and other data via parallel +requests (usually up to four parallel requests are common) those requests 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 SSLeay memory caches of the server processes. The little more amount + of I/O on the server results in a visible request speedup for your + clients. So it's recommended to use this storage. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data +</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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 SSLeay 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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. Per 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 useable 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 it's 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 + mostly 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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 SSLeay 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"> +<caption align="bottom" id="sf">Table 1: SSLeay Cipher Specification Tags</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<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>EXP</code></td> <td>all export ciphers</td> </tr> +<tr id="H"><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> +<tr id="D"><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> +<tr id="H"><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> +<tr id="D"><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> +<tr id="H"><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> +<tr id="D"><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> +<tr id="D"><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> +<tr id="H"><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, 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>ssleay 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> +$ ssleay 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"> +<caption align="bottom" id="sf">Table 2: Particular SSL Ciphers</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 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. +<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"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 RSA 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 dissuade from this practice. +Instead it is recommended to separate the Certificate and the Private Key. If +the contained Private Key is encrypted, the Pass Phrase dialog is forced at +startup time. +<p> +Example: +<blockquote> +<pre> +SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +</pre> +</blockquote> +<!-- SSLCACertificatePath -------------------------------------------> +<p> +<br> +<a name="SSLCACertificatePath"></a> +<H2><a name="ToC12">SSLCACertificatePath</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 have not only to place the Certificate files +there. Additionally you 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="ToC13">SSLCACertificateFile</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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> +<!-- SSLVerifyClient -------------------------------------------------> +<p> +<br> +<a name="SSLVerifyClient"></a> +<H2><a name="ToC14">SSLVerifyClient</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 has not to be (successfully) verifyable. +</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="ToC15">SSLVerifyDepth</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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="ToC16">SSLLog</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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="ToC17">SSLLogLevel</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 tace 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="ToC18">SSLOptions</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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>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 + actually generated variables. +<p> +<li><code>ExportCertData</code> + <p> + When this option is enabled, two additional CGI/SSI environment variables + are created: <code>SSL_CLIENT_CERT</code> and + <code>SSL_SERVER_CERT</code>. These contain the PEM-encoded X.509 + Certificates of client and server for the current HTTPS connection and can + be used by CGI scripts for deeper Certificate checking. 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 SSLeay's + <code>ssleay x509</code> command: <code>ssleay 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 encrypted version of the word + ``<code>password</code>''. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLOptions +FakeBasicAuth -CompatEnvVars +</pre> +</blockquote> +<!-- SSLRequireSSL --------------------------------------------------> +<p> +<br> +<a name="SSLRequireSSL"></a> +<H2><a name="ToC19">SSLRequireSSL</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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="ToC20">SSLRequire</a></H2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0"> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0"> +<tr> +<td><table cellspacing="0" cellpadding="1" border="0"> +<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 the machine representation is executed only. 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"> +<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"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table><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_VERSION_LIBRARY SSL_CLIENT_V_START SSL_SERVER_V_START +SSL_VERSION_INTERFACE SSL_CLIENT_V_END SSL_SERVER_V_END +SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN +SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C +SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_SP SSL_SERVER_S_DN_SP + SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L + SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O + SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU + SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN + 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_SP SSL_SERVER_I_DN_SP + 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_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 +</pre> +</td></tr></table></td> +</tr></table> +</td></tr></table> +</div> +<br> +<br> +<p> +<H1><a name="ToC21">Additional Features</a></H1> +<H2><a name="ToC22">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"> +<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"> +<tr><td valign="top" align="center" bgcolor="#ffffff"><table border="0" cellspacing="0" cellpadding="2" width="598"> +<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="D"><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</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 SSLeay 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_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> +<tr id="D"><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="H"><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> +<tr id="D"><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="H"><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> +<tr id="D"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> +<tr id="H"><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="D"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> +</table> +[ where <em>x509</em> is a component of a X.509 DN: <code>C, SP, L, O, OU, CN, Email</code> ]</td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<H2><a name="ToC23">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> + <tr> + <td> + <table width="600" border="0"> + <tr> + <td valign="top" align="left" width="250"> +<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> +<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" +><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"> +<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> +<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" +><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"> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.engelschall.com/sw/mod_ssl/">mod_ssl</a> 2.2, User Manual<br> + The Apache Interface to SSLeay + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-1999 + <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> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.wml b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.wml new file mode 100644 index 00000000000..f06b9f3966c --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_reference.wml @@ -0,0 +1,1341 @@ + +#use "ssl_template.inc" title="Reference" tag=ref num=3 + +<page_prev name="Introduction" url="ssl_intro.html"> +<page_next name="Compatibility" url="ssl_compat.html"> + +#use wml::std::toc style=nbsp +#use wml::std::grid + +<quotation width=150 author="Unknown"> +``Try to understand everything, +but believe nothing!'' +</quotation> + +<p> +<table cellspacing="0" cellpadding="0" border="0"> +<tr valign="bottom"> +<td> + +<big T>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"> +<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"> +<toc> +</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 occur mostly +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>Configuration Directives</h1> + +The most visible and error-prone things of mod_ssl are the configuration +directives it provides. 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>SSLPassPhraseDialog</h2> + +<p> +<directive + name="SSLPassPhraseDialog" + description="Type of pass phrase dialog for encrypted private keys" + syntax="<code>SSLPassPhraseDialog</code> <em>type</em>" + default="<code>SSLPassPhraseDialog builtin</code>" + context="server config" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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 an argument of + ``<code>servername:portnumber</code>'' for which 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 one could think about it. mod_ssl just defines the + interface: an executable program which provides the Pass Phrase on + <code>stdout</code>. Nothing more or less! So, when 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 too 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>SSLMutex</h2> + +<p> +<directive + name="SSLMutex" + description="Semaphore for internal mutual exclusion of operations" + syntax="<code>SSLMutex</code> <em>type</em>" + default="<code>SSLMutex none</code>" + context="server config" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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 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. Notice: 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 care about conflicts yourself. +<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 underlaying 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>SSLRandomSeed</h2> + +<p> +<directive + name="SSLRandomSeed" + description="Pseudo Random Number Generator (PRNG) seeding source" + syntax="<code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]" + default="<em>none</em>" + context="server config" + override="<em>Not applicable</em>" + compat="mod_ssl 2.2" +> + +<p> +This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in SSLeay 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. When + <em>bytes</em> is not specified the whole file forms the entropy. 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> +<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 it's <code>stdout</code> contents + form the entropy. When <em>bytes</em> is not specified the whole 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 at + the connection context slows down the server too dramatically, of course. + So usually you should avoid using external programs at this context. +</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>SSLSessionCache</h2> + +<directive + name="SSLSessionCache" + description="Type of the global/inter-process SSL Session Cache" + syntax="<code>SSLSessionCache</code> <em>type</em>" + default="<code>SSLSessionCache none</code>" + context="server config" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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. Because for requests to the same server process (via HTTP +keep-alive) SSLeay already caches the SSL session information locally. But +because modern clients request inlined images and other data via parallel +requests (usually up to four parallel requests are common) those requests 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 SSLeay memory caches of the server processes. The little more amount + of I/O on the server results in a visible request speedup for your + clients. So it's recommended to use this storage. +</ul> + +<p> +Example: +<blockquote> +<pre> +SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data +</pre> +</blockquote> + + +<!-- SSLSessionCacheTimeout -----------------------------------------> + +<p> +<br> +<a name="SSLSessionCacheTimeout"></a> +<h2>SSLSessionCacheTimeout</h2> + +<directive + name="SSLSessionCacheTimeout" + description="Number of seconds before an SSL session expires in the Session Cache" + syntax="<code>SSLSessionCacheTimeout</code> <em>seconds</em>" + default="<code>SSLSessionCacheTimeout 300</code>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.0" +> + +<p> +This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the SSLeay 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>SSLEngine</h2> + +<directive + name="SSLEngine" + description="SSL Engine Operation Switch" + syntax="<code>SSLEngine</code> <em>on|off</em>" + default="<code>SSLEngine off</code>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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. Per 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>SSLProtocol</h2> + +<directive + name="SSLProtocol" + description="Configure useable SSL protocol flavors" + syntax="<code>SSLProtocol</code> [+-]<em>protocol</em> ..." + default="<code>SSLProtocol all</code>" + context="server config, virtual host" + override="Options" + compat="mod_ssl 2.2" +> + +<p> +This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing it's 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 + mostly 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>SSLCipherSuite</h2> + +<directive + name="SSLCipherSuite" + description="Cipher Suite available for negotiation in SSL handshake" + syntax="<code>SSLCipherSuite</code> <em>cipher-spec</em>" + default="<code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>" + context="server config, virtual host, directory, .htaccess" + override="AuthConfig" + compat="mod_ssl 2.1" +> + +<p> +This complex directive uses a colon-separated <em>cipher-spec</em> string +consisting of SSLeay 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> +<float name="table1" caption="Table 1: SSLeay Cipher Specification Tags"> +<table border="0" cellspacing="0" cellpadding="2" width=598> +<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>EXP</code></td> <td>all export ciphers</td> </tr> +<tr id=H><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> +<tr id=D><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> +<tr id=H><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> +<tr id=D><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> +<tr id=H><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> +<tr id=D><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> +<tr id=H><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> +<tr id=D><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> +<tr id=H><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr> + +</table> +</float> + +<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, 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>ssleay 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> +$ ssleay 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> +# allow only strongest RSA ciphers +SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW +</pre> +</blockquote> + +<p> +<float name="table2" caption="Table 2: Particular SSL Ciphers"> +<table border="0" cellspacing="0" cellpadding="2" width=598> +<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> +</float> + + +<!-- SSLCertificateFile ---------------------------------------------> + +<p> +<br> +<a name="SSLCertificateFile"></a> +<h2>SSLCertificateFile</h2> + +<directive + name="SSLCertificateFile" + description="Server PEM-encoded X.509 Certificate file" + syntax="<code>SSLCertificateFile</code> <em>filename</em>" + default="<em>None</em>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.0" +> + +<p> +This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA 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. + +<p> +Example: +<blockquote> +<pre> +SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt +</pre> +</blockquote> + + +<!-- SSLCertificateKeyFile ------------------------------------------> + +<p> +<br> +<a name="SSLCertificateKeyFile"></a> +<h2>SSLCertificateKeyFile</h2> + +<directive + name="SSLCertificateKeyFile" + description="Server PEM-encoded RSA Private Key file" + syntax="<code>SSLCertificateKeyFile</code> <em>filename</em>" + default="<em>None</em>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.0" +> + +<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 dissuade from this practice. +Instead it is recommended to separate the Certificate and the Private Key. If +the contained Private Key is encrypted, the Pass Phrase dialog is forced at +startup time. + +<p> +Example: +<blockquote> +<pre> +SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +</pre> +</blockquote> + + +<!-- SSLCACertificatePath -------------------------------------------> + +<p> +<br> +<a name="SSLCACertificatePath"></a> +<h2>SSLCACertificatePath</h2> + +<directive + name="SSLCACertificatePath" + description="Directory of PEM-encoded CA Certificates for Client Auth." + syntax="<code>SSLCACertificatePath</code> <em>directory</em>" + default="<em>None</em>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.0" +> + +<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 have not only to place the Certificate files +there. Additionally you 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>SSLCACertificateFile</h2> + +<directive + name="SSLCACertificateFile" + description="File of concatenated PEM-encoded CA Certificates for Client Auth." + syntax="<code>SSLCACertificateFile</code> <em>filename</em>" + default="<em>None</em>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.0" +> + +<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> + + +<!-- SSLVerifyClient -------------------------------------------------> + +<p> +<br> +<a name="SSLVerifyClient"></a> +<h2>SSLVerifyClient</h2> + +<directive + name="SSLVerifyClient" + description="Type of Client Certificate verification" + syntax="<code>SSLVerifyClient</code> <em>level</em>" + default="<code>SSLVerifyClient none</code>" + context="server config, virtual host, directory, .htaccess" + override="AuthConfig" + compat="mod_ssl 2.0" +> + +<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 has not to be (successfully) verifyable. +</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>SSLVerifyDepth</h2> + +<directive + name="SSLVerifyDepth" + description="Maximum depth of CA Certificates in Client Certificate verification" + syntax="<code>SSLVerifyDepth</code> <em>number</em>" + default="<code>SSLVerifyDepth 1</code>" + context="server config, virtual host, directory, .htaccess" + override="AuthConfig" + compat="mod_ssl 2.0" +> + +<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>SSLLog</h2> + +<directive + name="SSLLog" + description="Where to write the dedicated SSL engine logfile" + syntax="<code>SSLLog</code> <em>filename</em>" + default="<em>None</em>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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>SSLLogLevel</h2> + +<directive + name="SSLLogLevel" + description="Logging level for the dedicated SSL engine logfile" + syntax="<code>SSLLogLevel</code> <em>level</em>" + default="<code>SSLLogLevel none</code>" + context="server config, virtual host" + override="<em>Not applicable</em>" + compat="mod_ssl 2.1" +> + +<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 tace 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>SSLOptions</h2> + +<directive + name="SSLOptions" + description="Configure various SSL engine run-time options" + syntax="<code>SSLOptions</code> [+-]<em>option</em> ..." + default="<em>None</em>" + context="server config, virtual host, directory, .htaccess" + override="Options" + compat="mod_ssl 2.1" +> + +<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>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 + actually generated variables. +<p> +<li><code>ExportCertData</code> + <p> + When this option is enabled, two additional CGI/SSI environment variables + are created: <code>SSL_CLIENT_CERT</code> and + <code>SSL_SERVER_CERT</code>. These contain the PEM-encoded X.509 + Certificates of client and server for the current HTTPS connection and can + be used by CGI scripts for deeper Certificate checking. 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 SSLeay's + <code>ssleay x509</code> command: <code>ssleay 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 encrypted version of the word + ``<code>password</code>''. +</ul> + +<p> +Example: +<blockquote> +<pre> +SSLOptions +FakeBasicAuth -CompatEnvVars +</pre> +</blockquote> + + +<!-- SSLRequireSSL --------------------------------------------------> + +<p> +<br> +<a name="SSLRequireSSL"></a> +<h2>SSLRequireSSL</h2> + +<directive + name="SSLRequireSSL" + description="Deny access when SSL is not used for the HTTP request" + syntax="<code>SSLRequireSSL</code>" + default="<em>None</em>" + context="directory, .htaccess" + override="AuthConfig" + compat="mod_ssl 2.0" +> + +<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>SSLRequire</h2> + +<directive + name="SSLRequire" + description="Allow access only when an arbitrarily complex boolean expression is true" + syntax="<code>SSLRequire</code> <em>expression</em>" + default="<em>None</em>" + context="directory, .htaccess" + override="AuthConfig" + compat="mod_ssl 2.1" +> + +<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 the machine representation is executed only. 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> + +<float name="table3" caption="Table 3: Available Variables for SSLRequire"> +<table><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_VERSION_LIBRARY SSL_CLIENT_V_START SSL_SERVER_V_START +SSL_VERSION_INTERFACE SSL_CLIENT_V_END SSL_SERVER_V_END +SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN +SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C +SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_SP SSL_SERVER_S_DN_SP + SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L + SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O + SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU + SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN + 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_SP SSL_SERVER_I_DN_SP + 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_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 +</pre> +</td></tr></table> +</float> + +<br> +<br> +<p> +<h1>Additional Features</h1> + +<h2>Environment Variables</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> +<float name="table4" caption="Table 4: SSI/CGI Environment Variables"> +<table border="0" cellspacing="0" cellpadding="2" width=598> +<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=D><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</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 SSLeay 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_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> +<tr id=D><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> +<tr id=H><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> +<tr id=D><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=H><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> +<tr id=D><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=H><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> +<tr id=D><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> +<tr id=H><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=D><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> +</table> +[ where <em>x509</em> is a component of a X.509 DN: <code>C, SP, L, O, OU, CN, Email</code> ] +</float> + + +<p> +<br> +<h2>Custom Log Formats</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> + diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-chapter.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-chapter.gif Binary files differnew file mode 100644 index 00000000000..7d69c96bd29 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-chapter.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-1.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-1.gif Binary files differnew file mode 100644 index 00000000000..b70504e2ec2 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-1.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-2.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-2.gif Binary files differnew file mode 100644 index 00000000000..14aa9f0ae11 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-2.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-3.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-3.gif Binary files differnew file mode 100644 index 00000000000..c55def0131a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-3.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-4.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-4.gif Binary files differnew file mode 100644 index 00000000000..3a590f51415 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-4.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-5.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-5.gif Binary files differnew file mode 100644 index 00000000000..6c74e3808f7 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-5.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-6.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-6.gif Binary files differnew file mode 100644 index 00000000000..95c45409752 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-6.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-7.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-7.gif Binary files differnew file mode 100644 index 00000000000..3e658aee73b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.head-num-7.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-000000.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-000000.gif Binary files differnew file mode 100644 index 00000000000..8dd81a90202 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-000000.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-transp.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-transp.gif Binary files differnew file mode 100644 index 00000000000..5bfd67a2d6f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.imgdot-1x1-transp.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-n.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-n.gif Binary files differnew file mode 100644 index 00000000000..ef0e7238be0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-n.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-s.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-s.gif Binary files differnew file mode 100644 index 00000000000..8b61339b763 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-next-s.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-n.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-n.gif Binary files differnew file mode 100644 index 00000000000..912076efd4b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-n.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-s.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-s.gif Binary files differnew file mode 100644 index 00000000000..47b3bb2916d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.navbut-prev-s.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-abstract.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-abstract.gif Binary files differnew file mode 100644 index 00000000000..126b5849d3f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-abstract.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-compat.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-compat.gif Binary files differnew file mode 100644 index 00000000000..930aa5f3ad4 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-compat.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-faq.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-faq.gif Binary files differnew file mode 100644 index 00000000000..d5bbc2ee42f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-faq.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-gloss.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-gloss.gif Binary files differnew file mode 100644 index 00000000000..9c233b8d507 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-gloss.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-howto.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-howto.gif Binary files differnew file mode 100644 index 00000000000..c20402d1a9d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-howto.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-intro.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-intro.gif Binary files differnew file mode 100644 index 00000000000..9c0371a2bf1 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-intro.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-over.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-over.gif Binary files differnew file mode 100644 index 00000000000..3e536598366 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-over.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-preface.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-preface.gif Binary files differnew file mode 100644 index 00000000000..3189868d92f --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-preface.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-ref.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-ref.gif Binary files differnew file mode 100644 index 00000000000..606a64a9955 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-ref.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-toc.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-toc.gif Binary files differnew file mode 100644 index 00000000000..2b096bf58ec --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-toc.gif diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-tutor.gif b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-tutor.gif Binary files differnew file mode 100644 index 00000000000..67aba321b36 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_ssl/ssl_template.title-tutor.gif |
