--- /dev/null
+
+#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 major products available on the market: Ben
+Laurie's freely available <a href="http://www.apache-ssl.org/">Apache-SSL</a>
+(from where mod_ssl were originally derived in 1998), 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 mod_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 up to Stronghold 2.x and based on
+mod_ssl since Stronghold 3.x).
+
+</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>SSLCipherSuite</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>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
+<tr id=H><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
+<tr id=H><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</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_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
+<tr id=H><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</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=H><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
+<tr id=H><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</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=H><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
+<tr id=H><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
+<tr id=H><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
+<tr id=H><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
+<tr id=D><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</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_KEY_SIZE</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>
+</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>
+
--- /dev/null
+#!wml -o index.html
+
+#use "ssl_template.inc" title="Title Page" tag=title num=0
+
+<br>
+<table cellspacing=0 cellpadding=0 border=0>
+<tr>
+ <td>
+ <table cellspacing=0 cellpadding=0 border=0>
+ <tr>
+ <td>
+ <img
+ src="ssl_cover_title.jpg"
+ alt="User Manual"
+ >
+ </td>
+ </tr>
+ <tr>
+ <td align=right>
+ <font face="Arial,Helvetica">mod_ssl version 2.8</font>
+ </td>
+ </tr>
+ </table>
+ <br>
+ </td>
+</tr>
+<tr>
+ <td>
+ <a
+ href="http://www.modssl.org/"
+ ><img
+ src="ssl_cover_logo.jpg"
+ alt="mod_ssl - The Apache Interface to OpenSSL"
+ border=0
+ ></a>
+ </td>
+</tr>
+<tr>
+ <td align=right>
+ <table>
+ <tr>
+ <td>
+ <tt>Ralf S. Engelschall</tt><br>
+ <tt>rse@engelschall.com</tt><br>
+ <tt>www.engelschall.com</tt><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>
+ <td>
+ <space width=30>
+ </td>
+ </tr>
+ </table>
+ </td>
+</tr>
+</table>
+
--- /dev/null
+
+#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:modssl-users@modssl.org">
+<code>modssl-users@modssl.org</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=350>
+<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-tag faq endtag=required>
+<preserve ref>
+<preserve toc>
+<set-var %attributes>
+<p>
+<li><toc_h3 alt="<get-var toc>"></toc_h3>
+ <a name="<get-var ref>"></a>
+ <strong id="faq">%body</strong>\
+
+ [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#<get-var ref>"><b>L</b></a>]
+ <p>
+<restore toc>
+<restore ref>
+</define-tag>
+
+
+<h2>About the module</h2>
+
+<ul>
+
+<faq ref="history" toc="What is the history of mod_ssl?">
+What is the history of mod_ssl?
+</faq>
+
+ The mod_ssl v1 package was initially created in April 1998 by <a
+ href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> via porting <a
+ href="mailto:ben@algroup.co.uk">Ben Laurie</a>'s <a
+ href="http://www.apache-ssl.org/">Apache-SSL</a> 1.17 source patches for
+ Apache 1.2.6 to Apache 1.3b6. 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 1.x with the newer Apache-SSL
+ 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The
+ first publically released version was mod_ssl 2.0.0 from August 10th,
+ 1998. As of this writing (August 1999) the current mod_ssl version is 2.4.0.
+ <p>
+ After one year of very active development with over 1000 working hours and
+ over 40 releases mod_ssl reached its current state. The result is an
+ already very clean source base implementing a very rich functionality.
+ The code size increased by a factor of 4 to currently a total of over
+ 10.000 lines of ANSI C consisting of approx. 70% code and 30% code
+ documentation. From the original Apache-SSL code currently approx. 5% is
+ remaining only.
+
+<faq ref="apssl-diff" toc="Apache-SSL vs. mod_ssl: differences?">
+What are the functional differences between mod_ssl and Apache-SSL, from where
+it is originally derived?
+</faq>
+
+ This neither can be answered in short (there were too many code changes)
+ nor can be answered at all by the author (there would immediately be flame
+ wars with no reasonable results at the end). But as you easily can guess
+ from the 5% of remaining Apache-SSL code, a lot of differences exists,
+ although user-visible backward compatibility exists for most things.
+ <p>
+ When you really want a detailed comparison you have to read the entries in
+ the large <code>CHANGES</code> file that is in the mod_ssl
+ distribution. Usually this is much too hard-core. So I recommend you to
+ either believe in the opinion and recommendations of other users (the
+ simplest approach) or do a comparison yourself (the most reasonable
+ approach). For the latter, grab distributions of mod_ssl (from <a
+ href="http://www.modssl.org/">http://www.modssl.org</a>) and Apache-SSL
+ (from <a href="http://www.apache-ssl.org/">http://www.apache-ssl.org</a>),
+ install both packages, read their documentation and try them out yourself.
+ Then choose the one which pleases you most.
+ <p>
+ A few final hints to help direct your comparison: quality of documentation
+ ("can you easily find answers and are they sufficient?"), quality of
+ source code ("is the source code reviewable so you can make sure there
+ aren't any trapdoors or inherent security risks because of bad programming
+ style?"), easy and clean installation ("can the SSL functionality easily
+ added to an Apache source tree without manual editing or patching?"),
+ clean integration into Apache ("is the SSL functionality encapsulated and
+ cleanly separated from the remaining Apache functionality?"), support for
+ Dynamic Shared Object (DSO) facility ("can the SSL functionality built as
+ a separate DSO for maximum flexibility?"), Win32 port ("is the SSL
+ functionality available also under the Win32 platform?"), amount and
+ quality of functionality ("is the provided SSL functionality and control
+ possibilities sufficient for your situation?"), quality of problem tracing
+ ("is it possible for you to easily trace down the problems via logfiles,
+ etc?"), etc. pp.
+
+<faq ref="apssl-diff" toc="mod_ssl vs. commercial alternatives?">
+What are the major differences between mod_ssl and
+the commercial alternatives like Raven or Stronghold?
+</faq>
+
+ In the past (until September 20th, 2000) the major difference was
+ the RSA license which one received (very cheaply in contrast to
+ a direct licensing from RSA DSI) with the commercial Apache SSL
+ products. On the other hand, one needed this license only in the US,
+ of course. So for non-US citizens this point was useless. But now
+ even for US citizens the situations changed because the RSA patent
+ expired on September 20th, 2000 and RSA DSI also placed the RSA
+ algorithm explicitly into the public domain.
+
+ <p>
+ Second, there is the point that one has guaranteed support from
+ the commercial vendors. On the other hand, if you monitored the
+ Open Source quality of mod_ssl and the support activities
+ found on <a href="mailto:modssl-users@modssl.org">
+ <code>modssl-users@modssl.org</code></a>, you could ask yourself
+ whether you are really convinced that you can get better support
+ from a commercial vendor.
+
+ <p>
+ Third, people often think they would receive perhaps at least a
+ better technical SSL solution than mod_ssl from the commercial
+ vendors. But this is not really true, because all commercial
+ alternatives (Raven 1.4.x, Stronghold 3.x, RedHat SWS 2.x, etc.)
+ <i>are</i> actually based on mod_ssl and OpenSSL. The reason for
+ this common misunderstanding is mainly because some vendors make no
+ attempt to make it reasonably clear that their product is actually
+ mod_ssl based. So, do not think, just because the commercial
+ alternatives are usually more expensive, that you are also receiving
+ an alternative <i>technical</i> SSL solution. This is usually not
+ the case. Actually the vendor versions of Apache, mod_ssl and OpenSSL
+ often stay behind the latest free versions and perhaps this way still do not
+ include important bug and security fixes. On the other hand,
+ it sometimes occurs that a vendor version includes useful changes
+ which are not available through the official freely available
+ packages. But most vendors play fair and contribute back those
+ changes to the free software world, of course.
+
+ <p>
+ So, in short: There are lots of commercial versions of the popular
+ Apache+mod_ssl+OpenSSL server combination available. Every user
+ should decide carefully whether they really need to buy a commercial
+ version or whether it would not be sufficient to directly use the
+ free and official versions of the Apache, mod_ssl and OpenSSL
+ packages.
+
+<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.4.0-1.3.9</code>. This directly indicates that it's
+ mod_ssl version 2.4.0 for Apache version 1.3.9. 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 almost 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 OpenSSL 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 OpenSSL 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 OpenSSL are not affected by the Wassenaar Agreement.
+
+</ul>
+
+<p>
+<br>
+<h2>About Installation</h2>
+
+<ul>
+
+<faq ref="core-dbm" toc="Core dumps for HTTPS requests?">
+When I access my website the first time via HTTPS I get a core dump?
+</faq>
+
+ There can be a lot of reasons why a core dump can occur, of course.
+ Ranging from buggy third-party modules, over buggy vendor libraries up to
+ a buggy mod_ssl version. But the above situation is often caused by old or
+ broken vendor DBM libraries. To solve it either build mod_ssl with the
+ built-in SDBM library (specify <tt>--enable-rule=SSL_SDBM</tt> at the
+ APACI command line) or switch from ``<tt>SSLSessionCache dbm:</tt>'' to the
+ newer ``<tt>SSLSessionCache shm:</tt>'' variant (after you have rebuilt
+ Apache with MM, of course).
+
+<faq ref="core-php3" toc="Core dumps for Apache+mod_ssl+PHP3?">
+My Apache dumps core when I add both mod_ssl and PHP3?
+</faq>
+
+ Make sure you add mod_ssl to the Apache source tree first and then do a
+ fresh configuration and installation of PHP3. For SSL support EAPI patches
+ are required which have to change internal Apache structures. PHP3 needs
+ to know about these in order to work correctly. Always make sure that
+ <tt>-DEAPI</tt> is contained in the compiler flags when PHP3 is build.
+
+<faq ref="dso-sym" toc="Undefined symbols on startup?">
+When I startup Apache I get errors about undefined symbols like ap_global_ctx?
+</faq>
+
+ This actually means you installed mod_ssl as a DSO, but without rebuilding
+ Apache with EAPI. Because EAPI is a requirement for mod_ssl, you need an
+ extra patched Apache (containing the EAPI patches) and you have to build
+ this Apache with EAPI enabled (explicitly specify
+ <tt>--enable-rule=EAPI</tt> at the APACI command line).
+
+<faq ref="mutex-perm" toc="Permission problem on SSLMutex">
+When I startup Apache I get permission errors related to SSLMutex?
+</faq>
+
+ When you receive entries like ``<code>mod_ssl: Child could not open
+ SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
+ [...] System: Permission denied (errno: 13)</code>'' this is usually
+ caused by to restrictive permissions on the <i>parent</i> directories.
+ Make sure that all parent directories (here <code>/opt</code>,
+ <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit
+ set at least for the UID under which Apache's children are running (see
+ the <code>User</code> directive of Apache).
+
+<faq ref="mm" toc="Shared memory and process size?">
+When I use the MM library and the shared memory cache each process grows
+1.5MB according to `top' although I specified 512000 as the cache size?
+</faq>
+
+ The additional 1MB are caused by the global shared memory pool EAPI
+ allocates for all modules and which is not used by mod_ssl for
+ various reasons. So the actually allocated shared memory is always
+ 1MB more than what you specify on <code>SSLSessionCache</code>.
+ But don't be confused by the display of `top': although is
+ indicates that <i>each</i> process grow, this is not reality, of
+ course. Instead the additional memory consumption is shared by
+ all processes, i.e. the 1.5MB are allocated only once per Apache
+ instance and not once per Apache server process.
+
+<faq ref="mmpath" toc="Shared memory and pathname?">
+Apache creates files in a directory declared by the internal
+EAPI_MM_CORE_PATH define. Is there a way to override the path using a
+configuration directive?
+</faq>
+
+ No, there is not configuration directive, because for technical
+ bootstrapping reasons, a directive not possible at all. Instead
+ use ``<code>CFLAGS='-DEAPI_MM_CORE_PATH="/path/to/wherever/"'
+ ./configure ...</code>'' when building Apache or use option
+ <b>-d</b> when starting <code>httpd</code>.
+
+<faq ref="entropy" toc="PRNG and not enough entropy?">
+When I fire up the server, mod_ssl stops with the error
+"Failed to generate temporary 512 bit RSA private key", why?
+And a "PRNG not seeded" error occurs if I try "make certificate".
+</faq>
+
+ Cryptographic software needs a source of unpredictable data
+ to work correctly. Many open source operating systems provide
+ a "randomness device" that serves this purpose (usually named
+ <code>/dev/random</code>). On other systems, applications have to
+ seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with
+ appropriate data before generating keys or performing public key
+ encryption. As of version 0.9.5, the OpenSSL functions that need
+ randomness report an error if the PRNG has not been seeded with
+ at least 128 bits of randomness. So mod_ssl has to provide enough
+ entropy to the PRNG to work correctly. For this one has to use the
+ <code>SSLRandomSeed</code> directives (to solve the run-time problem)
+ and create a <code>$HOME/.rnd</code> file to make sure enough
+ entropy is available also for the "<code>make certificate</code>"
+ step (in case the "<code>make certificate</code>" procedure is not
+ able to gather enough entropy theirself by searching for system
+ files).
+
+</ul>
+
+<p>
+<br>
+<h2>About Configuration</h2>
+
+<ul>
+
+<faq ref="https-parallel" toc="HTTP and HTTPS with a single server?">
+Is it possible to provide HTTP and HTTPS with a single server?</strong>
+</faq>
+
+ Yes, HTTP and HTTPS use different server ports, so there is no direct
+ conflict between them. Either run two separate server instances (one binds
+ to port 80, the other to port 443) or even use Apache's elegant virtual
+ hosting facility where you can easily create two virtual servers which
+ Apache dispatches: one responding to port 80 and speaking HTTP and one
+ responding to port 443 speaking 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 OpenSSL's <code>s_client</code> command you can do a similar
+ check even for HTTPS:
+ <p>
+ <code><b>$ openssl 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://curl.haxx.nu/">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 connection hang?">
+Why does the connection hang when I connect to my SSL-aware Apache server?
+</faq>
+
+ Because you connected with HTTP to the HTTPS port, i.e. you used an URL of
+ the form ``<code>http://</code>'' instead of ``<code>https://</code>''.
+ This also happens the other way round when you connect via HTTPS to a HTTP
+ port, 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="hang" toc="Why do I get connection refused?">
+Why do I get ``Connection Refused'' messages when trying to access my freshly
+installed Apache+mod_ssl server via HTTPS?
+</faq>
+
+ There can be various reasons. Some of the common mistakes is that people
+ start Apache with just ``<tt>apachectl start</tt>'' (or
+ ``<tt>httpd</tt>'') instead of ``<tt>apachectl startssl</tt>'' (or
+ ``<tt>httpd -DSSL</tt>''. Or you're configuration is not correct. At
+ least make sure that your ``<tt>Listen</tt>'' directives match your
+ ``<tt><VirtualHost></tt>'' directives. And if all fails, please do
+ yourself a favor and start over with the default configuration mod_ssl
+ provides you.
+
+<faq ref="env-vars" toc="Why are the SSL_XXX variables missing?">
+In my CGI programs and SSI scripts the various documented
+<code>SSL_XXX</code> variables do not exists. Why?
+</faq>
+
+ Just make sure you have ``<code>SSLOptions +StdEnvVars</code>''
+ enabled for the context of your CGI/SSI requests.
+
+<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 OpenSSL is really installed and in your <code>PATH</code>.
+ But some commands even work ok when you just run the
+ ``<code>openssl</code>'' program from within the OpenSSL source tree as
+ ``<code>./apps/openssl</code>''.
+ <p>
+ <li>Create a RSA private key for your Apache server
+ (will be Triple-DES encrypted and PEM formatted):
+
+ <p>
+ <code><strong>$ openssl 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>$ openssl 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>$ openssl rsa -in server.key -out server.key.unsecure</strong></code>
+
+ <p>
+ <li>Create a Certificate Signing Request (CSR) with the server RSA private
+ key (output will be PEM formatted):
+
+ <p>
+ <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code>
+
+ <p>
+ Make sure you enter the FQDN ("Fully Qualified Domain Name") of the
+ server when OpenSSL prompts you for the "CommonName", i.e. when you
+ generate a CSR for a website which will be later accessed via
+ <code>https://www.foo.dom/</code>, enter "www.foo.dom" here.
+ You can see the details of this CSR via the command
+
+ <p>
+ <code><strong>$ openssl 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 two 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>$ openssl 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> or <code>CA.pl</code>
+ script provided by OpenSSL. 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>$ openssl 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>$ openssl 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>$ openssl rsa -in ca.key -out ca.key.unsecure</strong></code>
+
+ <p>
+ <li>Create a self-signed CA Certificate (X509 structure)
+ with the RSA key of the CA (output will be PEM formatted):
+
+ <p>
+ <code><strong>$ openssl 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>$ openssl x509 -noout -text -in ca.crt</strong></code>
+
+ <p>
+ <li>Prepare a script for signing which is needed because
+ the ``<code>openssl ca</code>'' command has some strange requirements
+ and the default OpenSSL config doesn't allow one easily to use
+ ``<code>openssl 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 server CSR's in order to create real
+ SSL Certificates for use inside an Apache webserver (assuming
+ you already have a <code>server.csr</code> at hand):
+
+ <p>
+ <code><strong>$ ./sign.sh server.csr</strong></code>
+
+ <p>
+ This signs the server 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>$ openssl 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>$ openssl 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>
+ As an alternative approach you can use the ``<code>SSLPassPhraseDialog
+ exec:/path/to/program</code>'' facility. But keep in mind that this is
+ neither more nor less secure, of course.
+
+<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>$ openssl x509 -noout -text -in server.crt</strong></code><br>
+ <code><strong>$ openssl 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>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br>
+ <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl 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>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code>
+
+<faq ref="keysize1" toc="Bad Certificate Error?">
+What does it mean when my connections fail with an "alert bad certificate"
+error?
+</faq>
+
+ Usually when you see errors like ``<tt>OpenSSL: error:14094412: SSL
+ routines:SSL3_READ_BYTES:sslv3 alert bad certificate</tt>'' in the SSL
+ logfile, this means that the browser was unable to handle the server
+ certificate/private-key which perhaps contain a RSA-key not equal to 1024
+ bits. For instance Netscape Navigator 3.x is one of those browsers.
+
+<faq ref="keysize2" 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>openssl 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.
+
+<faq ref="pem-to-der" toc="How to convert from PEM to DER?">
+How can I convert a certificate from PEM to DER format?
+</faq>
+
+ The default certificate format for SSLeay/OpenSSL is PEM, which actually
+ is Base64 encoded DER with header and footer lines. For some applications
+ (e.g. Microsoft Internet Explorer) you need the certificate in plain DER
+ format. You can convert a PEM file <code>cert.pem</code> into the
+ corresponding DER file <code>cert.der</code> with the following command:
+
+ <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code>
+
+<faq ref="verisign-getca" toc="Verisign and the magic getca program?">
+I try to install a Verisign certificate. Why can't I find neither the
+<code>getca</code> nor <code>getverisign</code> programs Verisign mentions?
+</faq>
+
+ This is because Verisign has never provided specific instructions
+ for Apache+mod_ssl. Rather they tell you what you should do
+ if you were using C2Net's Stronghold (a commercial Apache
+ based server with SSL support). The only thing you have to do
+ is to save the certificate into a file and give the name of
+ that file to the <code>SSLCertificateFile</code> directive.
+ Remember that you need to give the key file in as well (see
+ <code>SSLCertificateKeyFile</code> directive). For a better
+ CA-related overview on SSL certificate fiddling you can look at <a
+ href="http://www.thawte.com/certs/server/keygen/mod_ssl.html">
+ Thawte's mod_ssl instructions</a>.
+
+<faq ref="gid" toc="Global IDs or SGC?">
+Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global
+ID) also with mod_ssl?
+</faq>
+
+ Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have
+ to configure anything special for this, just use a Global ID as your
+ server certificate. The <i>step up</i> of the clients are then
+ automatically handled by mod_ssl under run-time. For details please read
+ the <tt>README.GlobalID</tt> document in the mod_ssl distribution.
+
+<faq ref="gid" toc="Global IDs and Cert Chain?">
+After I have installed my new Verisign Global ID server certificate, the
+browsers complain that they cannot verify the server certificate?
+</faq>
+
+ That is because Verisign uses an intermediate CA certificate between
+ the root CA certificate (which is installed in the browsers) and
+ the server certificate (which you installed in the server). You
+ should have received this additional CA certificate from Verisign.
+ If not, complain to them. Then configure this certificate with the
+ <code>SSLCertificateChainFile</code> directive in the server. This
+ makes sure the intermediate CA certificate is send to the browser
+ and this way fills the gap in the certificate chain.
+
+</ul>
+
+<p>
+<br>
+<h2>About SSL Protocol</h2>
+
+<ul>
+
+<faq ref="random-errors" toc="Random SSL errors under heavy load?">
+Why do I get lots of random SSL protocol errors under heavy server load?
+</faq>
+
+ There can be a number of reasons for this, but the main one
+ is problems with the SSL session Cache specified by the
+ <tt>SSLSessionCache</tt> directive. The DBM session cache is most
+ likely the source of the problem, so trying the SHM session cache or
+ no cache at all may help.
+
+<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="random" toc="Why are connections horribly slow?">
+Often HTTPS connections to my server require up to 30 seconds for establishing
+the connection, although sometimes it works faster?
+</faq>
+
+ Usually this is caused by using a <code>/dev/random</code> device for
+ <code>SSLRandomSeed</code> which is blocking in read(2) calls if not
+ enough entropy is available. Read more about this problem in the refernce
+ chapter under <code>SSLRandomSeed</code>.
+
+<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 OpenSSL in use (can depend on the way you built
+ OpenSSL). 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>$ openssl ciphers -v</strong></code><br>
+
+<faq ref="cipher-adh" toc="How to use Anonymous-DH ciphers">
+I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no
+shared cipher'' errors?
+</faq>
+
+ In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough
+ to just put ``<code>ADH</code>'' into your <code>SSLCipherSuite</code>.
+ Additionally you have to build OpenSSL with
+ ``<code>-DSSL_ALLOW_ADH</code>''. Because per default OpenSSL does not
+ allow ADH ciphers for security reasons. So if you are actually enabling
+ these ciphers make sure you are informed about the side-effects.
+
+<faq ref="cipher-shared" toc="Why do I get 'no shared ciphers'?">
+I always just get a 'no shared ciphers' error if
+I try to connect to my freshly installed server?
+</faq>
+
+ Either you have messed up your <code>SSLCipherSuite</code>
+ directive (compare it with the pre-configured example in
+ <code>httpd.conf-dist</code>) or you have choosen the DSA/DH
+ algorithms instead of RSA under "<code>make certificate</code>"
+ and ignored or overseen the warnings. Because if you have choosen
+ DSA/DH, then your server no longer speaks RSA-based SSL ciphers
+ (at least not until you also configure an additional RSA-based
+ certificate/key pair). But current browsers like NS or IE only speak
+ RSA ciphers. The result is the "no shared ciphers" error. To fix
+ this, regenerate your server certificate/key pair and this time
+ choose the RSA algorithm.
+
+<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.
+
+<faq ref="io-ie" toc="Why do I get I/O errors with MSIE clients?">
+When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet
+Explorer (MSIE) I get various I/O errors. What is the reason?
+</faq>
+
+ The first reason is that the SSL implementation in some MSIE versions has
+ some subtle bugs related to the HTTP keep-alive facility and the SSL close
+ notify alerts on socket connection close. Additionally the interaction
+ between SSL and HTTP/1.1 features are problematic with some MSIE versions,
+ too. You've to work-around these problems by forcing
+ Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or
+ sending the SSL close notify messages to MSIE clients. This can be done by
+ using the following directive in your SSL-aware virtual host section:
+
+ <pre>
+ SetEnvIf User-Agent ".*MSIE.*" \\
+ <b>nokeepalive ssl-unclean-shutdown \\
+ downgrade-1.0 force-response-1.0</b>\
+ </pre>
+
+ Additionally it is known some MSIE versions have also problems
+ with particular ciphers. Unfortunately one cannot workaround these
+ bugs only for those MSIE particular clients, because the ciphers
+ are already used in the SSL handshake phase. So a MSIE-specific
+ <tt>SetEnvIf</tt> doesn't work to solve these problems. Instead one
+ has to do more drastic adjustments to the global parameters. But
+ before you decide to do this, make sure your clients really have
+ problems. If not, do not do this, because it affects all(!) your
+ clients, i.e., also your non-MSIE clients.
+
+ <p>
+ The next problem is that 56bit export versions of MSIE 5.x browsers have a
+ broken SSLv3 implementation which badly interacts with OpenSSL versions
+ greater than 0.9.4. You can either accept this and force your clients to
+ upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you
+ can decide to workaround it by accepting the drawback that your workaround
+ will horribly affect also other browsers:
+
+ <pre>
+ SSLProtocol all <b>-SSLv3</b>\
+ </pre>
+
+ This completely disables the SSLv3 protocol and lets those browsers work.
+ But usually this is an even less acceptable workaround. A more reasonable
+ workaround is to address the problem more closely and disable only the
+ ciphers which cause trouble.
+
+ <pre>
+ SSLCipherSuite ALL:!ADH:<b>!EXPORT56</b>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\
+ </pre>
+
+ This also lets the broken MSIE versions work, but only removes the
+ newer 56bit TLS ciphers.
+
+ <p>
+ Another problem with MSIE 5.x clients is that they refuse to connect to
+ URLs of the form <tt>https://12.34.56.78/</tt> (IP-addresses are used
+ instead of the hostname), if the server is using the Server Gated
+ Cryptography (SGC) facility. This can only be avoided by using the fully
+ qualified domain name (FQDN) of the website in hyperlinks instead, because
+ MSIE 5.x has an error in the way it handles the SGC negotiation.
+
+ <p>
+ And finally there are versions of MSIE which seem to require that
+ an SSL session can be reused (a totally non standard-conforming
+ behaviour, of course). Connection with those MSIE versions only work
+ if a SSL session cache is used. So, as a work-around, make sure you
+ are using a session cache (see <tt>SSLSessionCache</tt> directive).
+
+<faq ref="io-ns" toc="Why do I get I/O errors with NS clients?">
+When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I
+get I/O errors and the message "Netscape has encountered bad data from the
+server" What's the reason?
+</faq>
+
+ The problem usually is that you had created a new server certificate with
+ the same DN, but you had told your browser to accept forever the old
+ server certificate. Once you clear the entry in your browser for the old
+ certificate, everything usually will work fine. Netscape's SSL
+ implementation is correct, so when you encounter I/O errors with Netscape
+ Navigator it is most of the time caused by the configured certificates.
+
+</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.modssl.org/docs/2.8/ssl_faq.html">
+ http://www.modssl.org/docs/2.8/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 modssl-users Support Mailing List</em>
+ <a href="http://www.modssl.org/support/">
+ http://www.modssl.org/support/</a><br>
+ Second search for your problem in one of the existing archives of the
+ modssl-users 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.modssl.org/support/bugdb/">
+ http://www.modssl.org/support/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.modssl.org/support/bugdb/">
+ http://www.modssl.org/support/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 modssl-users mailing list (others see the current problems and
+ learn from answers).
+<p>
+<li><em>Write a Problem Report to the modssl-users Support Mailing List</em><br>
+ <a href="mailto:modssl-users@modssl.org">
+ modssl-users @ modssl.org</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 modssl-users.
+</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 OpenSSL version information</em><br>
+ The mod_ssl version you should really know. For instance, it's the version
+ number in the distribution tarball. The Apache version can be determined
+ by running ``<code>httpd -v</code>''. The OpenSSL version can be
+ determined by running ``<code>openssl 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+OpenSSL</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+OpenSSL 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="core-dumped" toc="I got a core dump, can you help me?">
+I got a core dump, can you help me?
+</faq>
+
+ In general no, at least not unless you provide more details about the code
+ location where Apache dumped core. What is usually always required in
+ order to help you is a backtrace (see next question). Without this
+ information it is mostly impossible to find the problem and help you in
+ fixing it.
+
+<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
+ most "current" kernels do not allow a process to dump core after it has
+ done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
+ security reasons (there can be privileged information left over in
+ memory). Additionally you can run ``<code>/path/to/httpd -X</code>''
+ manually to force Apache to 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>
+
--- /dev/null
+
+#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="Richard Nixon">
+``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">OpenSSL</div>
+<dd>The Open Source toolkit for SSL/TLS;
+ see <a href="http://www.openssl.org/">http://www.openssl.org/</a>
+<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 original SSL/TLS implementation library developed by
+ Eric A. Young <eay@aus.rsa.com>;
+ see <a href="http://www.ssleay.org/">http://www.ssleay.org/</a>
+<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>
+
--- /dev/null
+
+#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-tag howto endtag=required>
+<preserve ref>
+<preserve toc>
+<set-var %attributes>
+<p>
+<li><toc_h3 alt="<get-var toc>"></toc_h3>
+ <a name="<get-var ref>"></a>
+ <strong id="howto">%body</strong>\
+
+ [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#<get-var ref>"><b>L</b></a>]
+ <p>
+<restore toc>
+<restore ref>
+</define-tag>
+
+<define-tag config endtag=required>
+<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-tag>
+
+<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
+its 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:+eNULL
+<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:+eNULL
+<Location /strong/area>
+\# but https://hostname/strong/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
+AuthName "Snake Oil Authentication"
+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 Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
+/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
+/C=US/L=L.A./O=Snake Oil, 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>
+
+<howto ref="auth-intranet" toc="intranet vs. internet authentication"> How can
+I require HTTPS with strong ciphers and either basic authentication or client
+certificates for access to a subarea on the Intranet website for clients
+coming from the Internet but still allow plain HTTP access for clients on the
+Intranet?
+</howto>
+
+Let us assume the Intranet can be distinguished through the IP network
+192.160.1.0/24 and the subarea on the Intranet website has the URL
+<tt>/subarea</tt>. Then configure the following outside your HTTPS virtual
+host (so it applies to both HTTPS and HTTP):
+
+<p>
+<config>
+SSLCACertificateFile conf/ssl.crt/company-ca.crt
+
+<Directory /usr/local/apache/htdocs>
+\# Outside the subarea only Intranet access is granted
+Order deny,allow
+Deny from all
+Allow from 192.168.1.0/24
+</Directory>
+
+<Directory /usr/local/apache/htdocs/subarea>
+\# Inside the subarea any Intranet access is allowed
+\# but from the Internet only HTTPS + Strong-Cipher + Password
+\# or the alternative HTTPS + Strong-Cipher + Client-Certificate
+
+\# If HTTPS is used, make sure a strong cipher is used.
+\# Additionally allow client certs as alternative to basic auth.
+SSLVerifyClient optional
+SSLVerifyDepth 1
+SSLOptions +FakeBasicAuth +StrictRequire
+SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
+
+\# Force clients from the Internet to use HTTPS
+RewriteEngine on
+RewriteCond %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
+RewriteCond %{HTTPS} !=on
+RewriteRule .* - [F]
+
+\# Allow Network Access and/or Basic Auth
+Satisfy any
+
+\# Network Access Control
+Order deny,allow
+Deny from all
+Allow 192.168.1.0/24
+
+\# HTTP Basic Authentication
+AuthType basic
+AuthName "Protected Intranet Area"
+AuthUserFile conf/protected.passwd
+Require valid-user
+</Directory>
+</config>
+
+</ul>
+
--- /dev/null
+
+#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. Tanenbaum, ``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 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+OpenSSL
+</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+OpenSSL
+</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+OpenSSL</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 56 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>Multipurpose 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>
+
--- /dev/null
+
+#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 F.A.Q.">
+``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.openssl.org/">OpenSSL</A> from <A
+HREF="mailto:eay@aus.rsa.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.modssl.org/">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 OpenSSL in general (both
+are freely available and useable software packages), you should be aware that
+especially the cryptographic algorithms used inside OpenSSL 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+OpenSSL in your country depends mainly on your local state laws.
+The authors of neither Apache nor mod_ssl nor OpenSSL are liable for any
+violations you make here.
+
+<p>
+If you're not sure what law details apply to your country you're strongly
+advised 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 United States (USA) it's not allowed to (re-)export mod_ssl
+or OpenSSL 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 OpenSSL.
+</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/openssl ./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 (libssl.a, libcrypo.a).
+Not all platform support this.
+
--- /dev/null
+
+#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 pretty much occur
+everywhere. Especially both inside the server config files and the
+per-directory <code>.htaccess</code> files. The three classes are subsets of
+each other, i.e. directives from the per-directory class can also be used in
+the per-server and global context, and directives from the per-server class
+can also be used the in the global context.
+
+<p>
+Additional directives and environment variables provided by mod_ssl (via
+on-the-fly mapping) for backward compatiblity to other Apache SSL solutions
+are documented in the <a href="ssl_compat.html">Compatibility</a> chapter.
+
+
+<h1>Configuration Directives</h1>
+
+The most visible and error-prone things of mod_ssl are its configuration
+directives. So we document them in great detail here to assist you in setting
+up the best possible configuration of your SSL-aware webserver.
+
+
+<!-- SSLPassPhraseDialog -------------------------------------------->
+
+<p>
+<br>
+<a name="SSLPassPhraseDialog"></a>
+<h2>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 two arguments (the first is
+ of the form ``<code>servername:portnumber</code>'', the second is either
+ ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which
+ server and algorithm it has to print the corresponding Pass Phrase to
+ <code>stdout</code>. The intent is that this external program first runs
+ security checks to make sure that the system is not compromised by an
+ attacker, and only when these checks were passed successfully it provides
+ the Pass Phrase.
+ <p>
+ Both these security checks, and the way the Pass Phrase is determined, can
+ be as complex as you like. Mod_ssl just defines the interface: an
+ executable program which provides the Pass Phrase on <code>stdout</code>.
+ Nothing more or less! So, if you're really paranoid about security, here
+ is your interface. Anything else has to be left as an exercise to the
+ administrator, because local security requirements are so different.
+ <p>
+ The reuse-algorithm above is used here, too. In other words: The external
+ program is called only once per unique Pass Phrase.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
+</pre>
+</blockquote>
+
+
+<!-- SSLMutex ------------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLMutex"></a>
+<h2>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 (under Unix) always provided Mutex variant where
+ a physical (lock-)file is used as the Mutex. Always use a local disk
+ filesystem for <code>/path/to/mutex</code> and never a file residing on a
+ NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the
+ Apache parent process is automatically appended to
+ <code>/path/to/mutex</code> to make it unique, so you don't have to worry
+ about conflicts yourself. Notice that this type of mutex is not available
+ under the Win32 environment. There you <i>have</i> to use the semaphore
+ mutex.
+<p>
+<li><code>sem</code>
+ <p>
+ This is the most elegant but also most non-portable Mutex variant where a
+ SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used
+ when possible. It is only available when the underlying platform
+ supports it.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLMutex file:/usr/local/apache/logs/ssl_mutex
+</pre>
+</blockquote>
+
+
+<!-- SSLRandomSeed -------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLRandomSeed"></a>
+<h2>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 OpenSSL at startup time (<em>context</em> is
+<code>startup</code>) and/or just before a new SSL connection is established
+(<em>context</em> is <code>connect</code>). This directive can only be used
+in the global server context because the PRNG is a global facility.
+
+<p>
+The following <em>source</em> variants are available:
+
+<ul>
+<li><code>builtin</code>
+ <p> This is the always available builtin seeding source. It's usage
+ consumes minimum CPU cycles under runtime and hence can be always used
+ without drawbacks. The source used for seeding the PRNG contains of the
+ current time, the current process id and (when applicable) a randomly
+ choosen 1KB extract of the inter-process scoreboard structure of Apache.
+ The drawback is that this is not really a strong source and at startup
+ time (where the scoreboard is still not available) this source just
+ produces a few bytes of entropy. So you should always, at least for the
+ startup, use an additional seeding source.
+<p>
+<li><code>file:/path/to/source</code>
+ <p>
+ This variant uses an external file <code>/path/to/source</code> as the
+ source for seeding the PRNG. When <em>bytes</em> is specified, only the
+ first <em>bytes</em> number of bytes of the file form the entropy (and
+ <em>bytes</em> is given to <code>/path/to/source</code> as the first
+ argument). When <em>bytes</em> is not specified the whole file forms the
+ entropy (and <code>0</code> is given to <code>/path/to/source</code> as
+ the first argument). Use this especially at startup time, for instance
+ with an available <code>/dev/random</code> and/or
+ <code>/dev/urandom</code> devices (which usually exist on modern Unix
+ derivates like FreeBSD and Linux).
+ <p>
+ <em>But be careful</em>: Usually <code>/dev/random</code> provides only as
+ much entropy data as it actually has, i.e. when you request 512 bytes of
+ entropy, but the device currently has only 100 bytes available two things
+ can happen: On some platforms you receive only the 100 bytes while on
+ other platforms the read blocks until enough bytes are available (which
+ can take a long time). Here using an existing <code>/dev/urandom</code> is
+ better, because it never blocks and actually gives the amount of requested
+ data. The drawback is just that the quality of the received data may not
+ be the best.
+ <p>
+ On some platforms like FreeBSD one can even control how the entropy is
+ actually generated, i.e. by which system interrupts. More details one can
+ find under <i>rndcontrol(8)</i> on those platforms. Alternatively, when
+ your system lacks such a random device, you can use tool
+ like <a href="http://www.lothar.com/tech/crypto/">EGD</a>
+ (Entropy Gathering Daemon) and run it's client program with the
+ <code>exec:/path/to/program/</code> variant (see below) or use
+ <code>egd:/path/to/egd-socket</code> (see below).
+<p>
+<li><code>exec:/path/to/program</code>
+ <p>
+ This variant uses an external executable <code>/path/to/program</code> as
+ the source for seeding the PRNG. When <em>bytes</em> is specified, only the
+ first <em>bytes</em> number of bytes of its <code>stdout</code> contents
+ form the entropy. When <em>bytes</em> is not specified, the entirety of
+ the data produced on <code>stdout</code> form the entropy. Use this only
+ at startup time when you need a very strong seeding with the help of an
+ external program (for instance as in the example above with the
+ <code>truerand</code> utility you can find in the mod_ssl distribution
+ which is based on the AT&T <em>truerand</em> library). Using this in
+ the connection context slows down the server too dramatically, of course.
+ So usually you should avoid using external programs in that context.
+<p>
+<li><code>egd:/path/to/egd-socket</code> (Unix only)
+ <p>
+ This variant uses the Unix domain socket of the
+ external Entropy Gathering Daemon (EGD) (see <a
+ href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech
+ /crypto/</a>) to seed the PRNG. Use this if no random device exists
+ on your platform.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLRandomSeed startup builtin
+SSLRandomSeed startup file:/dev/random
+SSLRandomSeed startup file:/dev/urandom 1024
+SSLRandomSeed startup exec:/usr/local/bin/truerand 16
+SSLRandomSeed connect builtin
+SSLRandomSeed connect file:/dev/random
+SSLRandomSeed connect file:/dev/urandom 1024
+</pre>
+</blockquote>
+
+
+<!-- SSLSessionCache ------------------------------------------------>
+
+<p>
+<br>
+<a name="SSLSessionCache"></a>
+<h2>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. For requests to the same server process (via HTTP keep-alive),
+OpenSSL already caches the SSL session information locally. But because modern
+clients request inlined images and other data via parallel requests (usually
+up to four parallel requests are common) those requests are served by
+<em>different</em> pre-forked server processes. Here an inter-process cache
+helps to avoid unneccessary session handshakes.
+
+<p>
+The following two storage <em>type</em>s are currently supported:
+
+<ul>
+<li><code>none</code>
+ <p>
+ This is the default and just disables the global/inter-process Session
+ Cache. There is no drawback in functionality, but a noticeable speed
+ penalty can be observed.
+<p>
+<li><code>dbm:/path/to/datafile</code>
+ <p>
+ This makes use of a DBM hashfile on the local disk to synchronize the
+ local OpenSSL memory caches of the server processes. The slight increase
+ in I/O on the server results in a visible request speedup for your
+ clients, so this type of storage is generally recommended.
+<p>
+<li><code>shm:/path/to/datafile</code>[<code>(</code><i>size</i><code>)</code>]
+ <p>
+ This makes use of a high-performance hash table (approx. <i>size</i> bytes
+ in size) inside a shared memory segment in RAM (established via
+ <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory
+ caches of the server processes. This storage type is not available on all
+ platforms. See the mod_ssl <code>INSTALL</code> document for details on
+ how to build Apache+EAPI with shared memory support.
+</ul>
+
+<p>
+Examples:
+<blockquote>
+<pre>
+SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
+SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
+</pre>
+</blockquote>
+
+
+<!-- SSLSessionCacheTimeout ----------------------------------------->
+
+<p>
+<br>
+<a name="SSLSessionCacheTimeout"></a>
+<h2>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 OpenSSL internal memory cache.
+It can be set as low as 15 for testing, but should be set to higher
+values like 300 in real life.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLSessionCacheTimeout 600
+</pre>
+</blockquote>
+
+
+<!-- SSLEngine ------------------------------------------------------>
+
+<p>
+<br>
+<a name="SSLEngine"></a>
+<h2>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. By default the SSL/TLS Protocol Engine is disabled
+for both the main server and all configured virtual hosts.
+
+<p>
+Example:
+<blockquote>
+<pre>
+<VirtualHost _default_:443>
+SSLEngine on
+...
+</VirtualHost>
+</pre>
+</blockquote>
+
+
+<!-- SSLProtocol ---------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLProtocol"></a>
+<h2>SSLProtocol</h2>
+
+<directive
+ name="SSLProtocol"
+ description="Configure usable 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 its server environment. Clients then can only connect
+with one of the provided protocols.
+
+<p>
+The available (case-insensitive) <em>protocol</em>s are:
+
+<ul>
+<li><code>SSLv2</code>
+ <p>
+ This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the
+ original SSL protocol as designed by Netscape Corporation.
+<p>
+<li><code>SSLv3</code>
+ <p>
+ This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the
+ successor to SSLv2 and the currently (as of February 1999) de-facto
+ standardized SSL protocol from Netscape Corporation. It's supported by
+ almost all popular browsers.
+<p>
+<li><code>TLSv1</code>
+ <p>
+ This is the Transport Layer Security (TLS) protocol, version 1.0. It is the
+ successor to SSLv3 and currently (as of February 1999) still under
+ construction by the Internet Engineering Task Force (IETF). It's still
+ not supported by any popular browsers.
+<p>
+<li><code>All</code>
+ <p>
+ This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a
+ convinient way for enabling all protocols except one when used in
+ combination with the minus sign on a protocol as the example above shows.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+\# enable SSLv3 and TLSv1, but not SSLv2
+SSLProtocol all -SSLv2
+</pre>
+</blockquote>
+
+
+<!-- SSLCipherSuite ------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLCipherSuite"></a>
+<h2>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 OpenSSL cipher specifications to configure the Cipher Suite the
+client is permitted to negotiate in the SSL handshake phase. Notice that this
+directive can be used both in per-server and per-directory context. In
+per-server context it applies to the standard SSL handshake when a connection
+is established. In per-directory context it forces a SSL renegotation with the
+reconfigured Cipher Suite after the HTTP request was read but before the HTTP
+response is sent.
+
+<p>
+An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major
+attributes plus a few extra minor ones:
+
+<ul>
+<li><em>Key Exchange Algorithm</em>:<br>
+ RSA or Diffie-Hellman variants.
+<p>
+<li><em>Authentication Algorithm</em>:<br>
+ RSA, Diffie-Hellman, DSS or none.
+<p>
+<li><em>Cipher/Encryption Algorithm</em>:<br>
+ DES, Triple-DES, RC4, RC2, IDEA or none.
+<p>
+<li><em>MAC Digest Algorithm</em>:<br>
+ MD5, SHA or SHA1.
+</ul>
+
+An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1
+cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use,
+one can either specify all the Ciphers, one at a time, or use aliases to
+specify the preference and order for the ciphers (see <a href="#table1">Table
+1</a>).
+
+<p>
+<float name="table1" caption="Table 1: OpenSSL 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>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr>
+<tr id=H><td><code>EXP</code></td> <td>all export ciphers</td> </tr>
+<tr id=D><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr>
+<tr id=H><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr>
+<tr id=D><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr>
+<tr id=H><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr>
+<tr id=D><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr>
+<tr id=H><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr>
+<tr id=D><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr>
+<tr id=H><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr>
+<tr id=D><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr>
+<tr id=H><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr>
+<tr id=D><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr>
+
+</table>
+</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, TLSv1, EXP, LOW, MEDIUM,
+HIGH</code>) for certain groups of ciphers. These tags can be joined
+together with prefixes to form the <em>cipher-spec</em>. Available
+prefixes are:
+
+<ul>
+<li>none: add cipher to list
+<li><code>+</code>: add ciphers to list and pull them to current location in list
+<li><code>-</code>: remove cipher from list (can be added later again)
+<li><code>!</code>: kill cipher from list completely (can <b>not</b> be added later again)
+</ul>
+
+A simpler way to look at all of this is to use the ``<code>openssl ciphers
+-v</code>'' command which provides a nice way to successively create the
+correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string
+is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which
+means the following: first, remove from consideration any ciphers that do not
+authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
+use ciphers using RC4 and RSA. Next include the high, medium and then the low
+security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the
+end of the list.
+
+<blockquote>
+<pre>
+$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
+NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1
+NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5
+EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
+... ... ... ... ...
+EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
+EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+</pre>
+</blockquote>
+
+The complete list of particular RSA & DH ciphers for SSL is given in <a
+href="#table2">Table 2</a>.
+
+<p>
+Example:
+<blockquote>
+<pre>
+# 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 or DSA Private Key file for it
+(contained in the same file). If the contained Private Key is encrypted the
+Pass Phrase dialog is forced at startup time. This directive can be used up to
+two times (referencing different filenames) when both a RSA and a DSA based
+server certificate is used in parallel.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt
+</pre>
+</blockquote>
+
+
+<!-- SSLCertificateKeyFile ------------------------------------------>
+
+<p>
+<br>
+<a name="SSLCertificateKeyFile"></a>
+<h2>SSLCertificateKeyFile</h2>
+
+<directive
+ name="SSLCertificateKeyFile"
+ description="Server PEM-encoded 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 discourage this practice.
+Instead we recommend you to separate the Certificate and the Private Key. If
+the contained Private Key is encrypted, the Pass Phrase dialog is forced at
+startup time. This directive can be used up to two times (referencing
+different filenames) when both a RSA and a DSA based private key is used in
+parallel.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key
+</pre>
+</blockquote>
+
+
+<!-- SSLCertificateChainFile ---------------------------------------->
+
+<p>
+<br>
+<a name="SSLCertificateChainFile"></a>
+<h2>SSLCertificateChainFile</h2>
+
+<directive
+ name="SSLCertificateChainFile"
+ description="File of PEM-encoded Server CA Certificates"
+ syntax="<code>SSLCertificateChainFile</code> <em>filename</em>"
+ default="<em>None</em>"
+ context="server config, virtual host"
+ override="<em>Not applicable</em>"
+ compat="mod_ssl 2.3.6"
+>
+
+<p>
+This directive sets the optional <em>all-in-one</em> file where you can
+assemble the certificates of Certification Authorities (CA) which form the
+certificate chain of the server certificate. This starts with the issuing CA
+certificate of of the server certificate and can range up to the root CA
+certificate. Such a file is simply the concatenation of the various
+PEM-encoded CA Certificate files, usually in certificate chain order.
+
+<p>
+This should be used alternatively and/or additionally to <a
+href="#SSLCACertificatePath">SSLCACertificatePath</a> for explicitly
+constructing the server certificate chain which is sent to the browser in
+addition to the server certificate. It is especially useful to avoid conflicts
+with CA certificates when using client authentication. Because although
+placing a CA certificate of the server certificate chain into <a
+href="#SSLCACertificatePath">SSLCACertificatePath</a> has the same effect for
+the certificate chain construction, it has the side-effect that client
+certificates issued by this same CA certificate are also accepted on client
+authentication. That's usually not one expect.
+
+<p>
+But be careful: Providing the certificate chain works only if you are using a
+<i>single</i> (either RSA <i>or</i> DSA) based server certificate. If you are
+using a coupled RSA+DSA certificate pair, this will work only if actually both
+certificates use the <i>same</i> certificate chain. Else the browsers will be
+confused in this situation.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt
+</pre>
+</blockquote>
+
+
+<!-- SSLCACertificatePath ------------------------------------------->
+
+<p>
+<br>
+<a name="SSLCACertificatePath"></a>
+<h2>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 can't just place the Certificate files
+there: you also have to create symbolic links named
+<i>hash-value</i><tt>.N</tt>. And you should always make sure this directory
+contains the appropriate symbolic links. Use the <code>Makefile</code> which
+comes with mod_ssl to accomplish this task.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCACertificatePath /usr/local/apache/conf/ssl.crt/
+</pre>
+</blockquote>
+
+
+<!-- SSLCACertificateFile ------------------------------------------->
+
+<p>
+<br>
+<a name="SSLCACertificateFile"></a>
+<h2>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>
+
+
+<!-- SSLCARevocationPath -------------------------------------------->
+
+<p>
+<br>
+<a name="SSLCARevocationPath"></a>
+<h2>SSLCARevocationPath</h2>
+
+<directive
+ name="SSLCARevocationPath"
+ description="Directory of PEM-encoded CA CRLs for Client Auth."
+ syntax="<code>SSLCARevocationPath</code> <em>directory</em>"
+ default="<em>None</em>"
+ context="server config, virtual host"
+ override="<em>Not applicable</em>"
+ compat="mod_ssl 2.3"
+>
+
+<p>
+This directive sets the directory where you keep the Certificate Revocation
+Lists (CRL) of Certification Authorities (CAs) whose clients you deal with.
+These are used to revoke the client certificate on Client Authentication.
+
+<p>
+The files in this directory have to be PEM-encoded and are accessed through
+hash filenames. So usually you have not only to place the CRL files there.
+Additionally you have to create symbolic links named
+<i>hash-value</i><tt>.rN</tt>. And you should always make sure this directory
+contains the appropriate symbolic links. Use the <code>Makefile</code> which
+comes with mod_ssl to accomplish this task.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCARevocationPath /usr/local/apache/conf/ssl.crl/
+</pre>
+</blockquote>
+
+
+<!-- SSLCARevocationFile -------------------------------------------->
+
+<p>
+<br>
+<a name="SSLCARevocationFile"></a>
+<h2>SSLCARevocationFile</h2>
+
+<directive
+ name="SSLCARevocationFile"
+ description="File of concatenated PEM-encoded CA CRLs for Client Auth."
+ syntax="<code>SSLCARevocationFile</code> <em>filename</em>"
+ default="<em>None</em>"
+ context="server config, virtual host"
+ override="<em>Not applicable</em>"
+ compat="mod_ssl 2.3"
+>
+
+<p>
+This directive sets the <em>all-in-one</em> file where you can assemble the
+Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose
+<em>clients</em> you deal with. These are used for Client Authentication.
+Such a file is simply the concatenation of the various PEM-encoded CRL
+files, in order of preference. This can be used alternatively and/or
+additionally to <a href="#SSLCARevocationPath">SSLCARevocationPath</a>.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl
+</pre>
+</blockquote>
+
+
+<!-- SSLVerifyClient ------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLVerifyClient"></a>
+<h2>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 it need not to be (successfully) verifiable.
+</ul>
+
+In practice only levels <strong>none</strong> and <strong>require</strong> are
+really interesting, because level <strong>optional</strong> doesn't work with
+all browsers and level <strong>optional_no_ca</strong> is actually against the
+idea of authentication (but can be used to establish SSL test pages, etc.)
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLVerifyClient require
+</pre>
+</blockquote>
+
+
+<!-- SSLVerifyDepth ------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLVerifyDepth"></a>
+<h2>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 trace messages, i.e. messages which show minor processing steps.
+<p>
+<li><code>debug</code><br>
+ log also debugging messages, i.e. messages which show development and
+ low-level I/O information.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLLogLevel warn
+</pre>
+</blockquote>
+
+
+<!-- SSLOptions ----------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLOptions"></a>
+<h2>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>StdEnvVars</code>
+ <p>
+ When this option is enabled, the standard set of SSL related CGI/SSI
+ environment variables are created. This per default is disabled for
+ performance reasons, because the information extraction step is a
+ rather expensive operation. So one usually enables this option for
+ CGI and SSI requests only.
+<p>
+<li><code>CompatEnvVars</code>
+ <p>
+ When this option is enabled, additional CGI/SSI environment variables are
+ created for backward compatibility to other Apache SSL solutions. Look in
+ the <a href="ssl_compat.html">Compatibility</a> chapter for details
+ on the particular variables generated.
+<p>
+<li><code>ExportCertData</code>
+ <p>
+ When this option is enabled, additional CGI/SSI environment variables are
+ created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and
+ <code>SSL_CLIENT_CERT_CHAIN</code><i>n</i> (with <i>n</i> = 0,1,2,..).
+ These contain the PEM-encoded X.509 Certificates of server and client for
+ the current HTTPS connection and can be used by CGI scripts for deeper
+ Certificate checking. Additionally all other certificates of the client
+ certificate chain are provided, too. This bloats up the environment a
+ little bit which is why you have to use this option to enable it on
+ demand.
+<p>
+<li><code>FakeBasicAuth</code>
+ <p>
+ When this option is enabled, the Subject Distinguished Name (DN) of the
+ Client X509 Certificate is translated into a HTTP Basic Authorization
+ username. This means that the standard Apache authentication methods can
+ be used for access control. The user name is just the Subject of the
+ Client's X509 Certificate (can be determined by running OpenSSL's
+ <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in
+ </code><em>certificate</em><code>.crt</code>). Note that no password is
+ obtained from the user. Every entry in the user file needs this password:
+ ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the
+ word `<code>password</code>''. Those who live under MD5-based encryption
+ (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5
+ hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.
+<p>
+<li><code>StrictRequire</code>
+ <p>
+ This <i>forces</i> forbidden access when <code>SSLRequireSSL</code> or
+ <code>SSLRequire</code> successfully decided that access should be
+ forbidden. Usually the default is that in the case where a ``<code>Satisfy
+ any</code>'' directive is used, and other access restrictions are passed,
+ denial of access due to <code>SSLRequireSSL</code> or
+ <code>SSLRequire</code> is overridden (because that's how the Apache
+ <tt>Satisfy</tt> mechanism should work.) But for strict access restriction
+ you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in
+ combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an
+ additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has
+ decided to deny access.
+<p>
+<li><code>OptRenegotiate</code>
+ <p>
+ This enables optimized SSL connection renegotiation handling when SSL
+ directives are used in per-directory context. By default a strict
+ scheme is enabled where <i>every</i> per-directory reconfiguration of
+ SSL parameters causes a <i>full</i> SSL renegotiation handshake. When this
+ option is used mod_ssl tries to avoid unnecessary handshakes by doing more
+ granular (but still safe) parameter checks. Nevertheless these granular
+ checks sometimes maybe not what the user expects, so enable this on a
+ per-directory basis only, please.
+</ul>
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLOptions +FakeBasicAuth -StrictRequire
+<Files ~ "\.(cgi|shtml)$">
+ SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
+<Files>
+</pre>
+</blockquote>
+
+
+<!-- SSLRequireSSL -------------------------------------------------->
+
+<p>
+<br>
+<a name="SSLRequireSSL"></a>
+<h2>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 only the machine representation is executed. For Per-Directory
+context this is different: here <em>expression</em> has to be parsed and
+immediately executed for every request.
+
+<p>
+Example:
+<blockquote>
+<pre>
+SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \\
+ and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \\
+ and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \\
+ and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \\
+ and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \\
+ or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
+</pre>
+</blockquote>
+
+<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_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START
+SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END
+SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN
+SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C
+SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST
+SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L
+SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O
+SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU
+ SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN
+ SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T
+ SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I
+ SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G
+ SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S
+ SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D
+ SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID
+ SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email
+ SSL_CLIENT_I_DN SSL_SERVER_I_DN
+ SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C
+ SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST
+ SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L
+ SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O
+ SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU
+ SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN
+ SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T
+ SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I
+ SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G
+ SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S
+ SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D
+ SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID
+ SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email
+ SSL_CLIENT_A_SIG SSL_SERVER_A_SIG
+ SSL_CLIENT_A_KEY SSL_SERVER_A_KEY
+ SSL_CLIENT_CERT SSL_SERVER_CERT
+ SSL_CLIENT_CERT_CHAIN<b>n</b>
+ SSL_CLIENT_VERIFY
+</pre>
+</td></tr></table>
+</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=H><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr>
+<tr id=D><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>
+<tr id=D><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr>
+<tr id=H><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr>
+<tr id=D><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr>
+<tr id=H><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr>
+<tr id=D><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr>
+<tr id=H><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr>
+<tr id=D><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>
+<tr id=H><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr>
+<tr id=D><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr>
+<tr id=H><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>
+<tr id=D><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr>
+<tr id=H><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr>
+<tr id=D><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr>
+<tr id=H><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr>
+<tr id=D><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr>
+<tr id=H><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr>
+<tr id=D><td><code>SSL_CLIENT_CERT_CHAIN</code><i>n</i></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr>
+<tr id=H><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><tt>NONE</tt>, <tt>SUCCESS</tt>, <tt>GENEROUS</tt> or <tt>FAILED:</tt><i>reason</i></td></tr>
+<tr id=D><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr>
+<tr id=H><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr>
+<tr id=D><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr>
+<tr id=H><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr>
+<tr id=D><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr>
+<tr id=H><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr>
+<tr id=D><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>
+<tr id=H><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr>
+<tr id=D><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr>
+<tr id=H><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr>
+<tr id=D><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr>
+</table>
+[ where <em>x509</em> is a component of a X.509 DN:
+ <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ]
+</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>
+
projects / apache / commitdiff