httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stodd...@apache.org
Subject cvs commit: httpd-2.0/docs/manual/ssl ssl_compat.wml ssl_cover.wml ssl_faq.wml ssl_glossary.wml ssl_howto.wml ssl_intro.wml ssl_overview.wml ssl_reference.wml
Date Mon, 05 Nov 2001 17:43:12 GMT
stoddard    01/11/05 09:43:12

  Added:       docs/manual/ssl ssl_compat.wml ssl_cover.wml ssl_faq.wml
                        ssl_glossary.wml ssl_howto.wml ssl_intro.wml
                        ssl_overview.wml ssl_reference.wml
  Log:
  SSL Doc... Now the .wml files
  
  Revision  Changes    Path
  1.1                  httpd-2.0/docs/manual/ssl/ssl_compat.wml
  
  Index: ssl_compat.wml
  ===================================================================
  
  #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>
  &nbsp;&nbsp;
  </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 &amp; 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>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_cover.wml
  
  Index: ssl_cover.wml
  ===================================================================
  #!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> &nbsp;&nbsp;
          </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>
                  &nbsp;&nbsp;&nbsp;&nbsp;
              </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>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_faq.wml
  
  Index: ssl_faq.wml
  ===================================================================
  
  #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>
  &nbsp;&nbsp;
  </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>\
      &nbsp;&nbsp;
      [<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>&lt;mod_ssl-version&gt;</em>-<em>&lt;apache-version&gt;</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 &amp; 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>&lt;VirtualHost&gt;</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>
      &lt;a href="document.html:SSL"&gt
      </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&nbsp;@&nbsp;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&nbsp;@&nbsp;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>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_glossary.wml
  
  Index: ssl_glossary.wml
  ===================================================================
  
  #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 &lt;eay@aus.rsa.com&gt;;
      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>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_howto.wml
  
  Index: ssl_howto.wml
  ===================================================================
  
  #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>
  &nbsp;&nbsp;
  </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>\
      &nbsp;&nbsp;
      [<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
  &lt;Directory /usr/local/apache/htdocs&gt;
  \#   but finally deny all browsers which haven't upgraded
  SSLRequire %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
  &lt;/Directory&gt;
  </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
  &lt;Location /strong/area&gt;
  \#   but https://hostname/strong/area/ and below requires strong ciphers
  SSLCipherSuite HIGH:MEDIUM
  &lt;/Location&gt;
  </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
  &lt;Location /secure/area&gt;
  SSLVerifyClient require
  SSLVerifyDepth 1
  &lt;/Location&gt;
  </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
  &lt;Directory /usr/local/apache/htdocs/secure/area&gt;
  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
  &lt;/Directory&gt;
  </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
  &lt;Directory /usr/local/apache/htdocs/secure/area&gt;
  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"} 
  &lt;/Directory&gt;
  </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
  
  &lt;Directory /usr/local/apache/htdocs&gt;
  \#   Outside the subarea only Intranet access is granted
  Order                deny,allow
  Deny                 from all
  Allow                from 192.168.1.0/24
  &lt;/Directory&gt;
  
  &lt;Directory /usr/local/apache/htdocs/subarea&gt;
  \#   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} &gt;= 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
  &lt;/Directory&gt;
  </config>
  
  </ul>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_intro.wml
  
  Index: ssl_intro.wml
  ===================================================================
  
  #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>
  &nbsp;&nbsp;
  </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>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_overview.wml
  
  Index: ssl_overview.wml
  ===================================================================
  
  #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>
  &nbsp;&nbsp;
  </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.
  
  
  
  
  1.1                  httpd-2.0/docs/manual/ssl/ssl_reference.wml
  
  Index: ssl_reference.wml
  ===================================================================
  
  #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 &lt;VirtualHost&gt;.  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 &lt;VirtualHost&gt; sections.  
  
  </td>
  <td>
  &nbsp;&nbsp;
  </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&amp;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 &lt;VirtualHost&gt; 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>
  &lt;VirtualHost _default_:443&gt;
  SSLEngine on
  ...
  &lt;/VirtualHost&gt;
  </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 &amp; 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>&nbsp;</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>&nbsp; </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>&nbsp;</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>&nbsp;</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>&nbsp; </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>&nbsp; </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>&nbsp; </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>&nbsp; </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>&nbsp;</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>&nbsp; </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>&nbsp; </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>&nbsp;</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>&nbsp; </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>&nbsp;</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>&nbsp;</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>&nbsp; </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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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
  &lt;Files ~ "\.(cgi|shtml)$"&gt;
      SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
  &lt;Files&gt;
  </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>&lt;</b>"  word | word "<b>lt</b>" word
             | word "<b>&lt;=</b>" word | word "<b>le</b>" word
             | word "<b>&gt;</b>"  word | word "<b>gt</b>" word
             | word "<b>&gt;=</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>
  
  
  
  

Mime
View raw message