granicus.if.org Git - apache/blob - docs/manual/mod/mod_ssl.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_ssl - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_ssl</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_ssl.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Strong cryptography using the Secure Sockets
  27 Layer (SSL) and Transport Layer Security (TLS) protocols</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>ssl_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_ssl.c</td></tr></table>
  31 <h3>Summary</h3>
  32
  33 <p>This module provides SSL v2/v3 and TLS v1 support for the Apache
  34 HTTP Server.  It was contributed by Ralf S. Engeschall based on his
  35 mod_ssl project and originally derived from work by Ben Laurie.</p>
  36
  37 <p>This module relies on <a href="http://www.openssl.org/">OpenSSL</a>
  38 to provide the cryptography engine.</p>
  39
  40 <p>Further details, discussion, and examples are provided in the
  41 <a href="../ssl/">SSL documentation</a>.</p>
  42 </div>
  43 <div id="quickview"><h3 class="directives">Directives</h3>
  44 <ul id="toc">
  45 <li><img alt="" src="../images/down.gif" /> <a href="#sslcacertificatefile">SSLCACertificateFile</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#sslcacertificatepath">SSLCACertificatePath</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#sslcadnrequestfile">SSLCADNRequestFile</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#sslcadnrequestpath">SSLCADNRequestPath</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#sslcarevocationfile">SSLCARevocationFile</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#sslcarevocationpath">SSLCARevocationPath</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#sslcertificatechainfile">SSLCertificateChainFile</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#sslcertificatefile">SSLCertificateFile</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#sslciphersuite">SSLCipherSuite</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#sslcryptodevice">SSLCryptoDevice</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#sslengine">SSLEngine</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#sslhonorcipherorder">SSLHonorCipherOrder</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#sslinsecurerenegotiation">SSLInsecureRenegotiation</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#sslocspenable">SSLOCSPEnable</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#ssloptions">SSLOptions</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#sslpassphrasedialog">SSLPassPhraseDialog</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#sslprotocol">SSLProtocol</a></li>
  65 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycacertificatefile">SSLProxyCACertificateFile</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></li>
  69 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></li>
  70 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire</a></li>
  71 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxyciphersuite">SSLProxyCipherSuite</a></li>
  72 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxyengine">SSLProxyEngine</a></li>
  73 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile</a></li>
  74 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxymachinecertificatepath">SSLProxyMachineCertificatePath</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxyprotocol">SSLProxyProtocol</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxyverify">SSLProxyVerify</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#sslproxyverifydepth">SSLProxyVerifyDepth</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#sslrandomseed">SSLRandomSeed</a></li>
  79 <li><img alt="" src="../images/down.gif" /> <a href="#sslrenegbuffersize">SSLRenegBufferSize</a></li>
  80 <li><img alt="" src="../images/down.gif" /> <a href="#sslrequire">SSLRequire</a></li>
  81 <li><img alt="" src="../images/down.gif" /> <a href="#sslrequiressl">SSLRequireSSL</a></li>
  82 <li><img alt="" src="../images/down.gif" /> <a href="#sslsessioncache">SSLSessionCache</a></li>
  83 <li><img alt="" src="../images/down.gif" /> <a href="#sslsessioncachetimeout">SSLSessionCacheTimeout</a></li>
  84 <li><img alt="" src="../images/down.gif" /> <a href="#sslstrictsnivhostcheck">SSLStrictSNIVHostCheck</a></li>
  85 <li><img alt="" src="../images/down.gif" /> <a href="#sslusername">SSLUserName</a></li>
  86 <li><img alt="" src="../images/down.gif" /> <a href="#sslverifyclient">SSLVerifyClient</a></li>
  87 <li><img alt="" src="../images/down.gif" /> <a href="#sslverifydepth">SSLVerifyDepth</a></li>
  88 </ul>
  89 <h3>Topics</h3>
  90 <ul id="topics">
  91 <li><img alt="" src="../images/down.gif" /> <a href="#envvars">Environment Variables</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#logformats">Custom Log Formats</a></li>
  93 </ul></div>
  94 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  95 <div class="section">
  96 <h2><a name="envvars" id="envvars">Environment Variables</a></h2>
  97
  98 <p>This module provides a lot of SSL information as additional environment
  99 variables to the SSI and CGI namespace. The generated variables are listed in
 100 the table below. For backward compatibility the information can
 101 be made available under different names, too. Look in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the
 102 compatibility variables.</p>
 103
 104 <table class="bordered">
 105
 106 <tr>
 107  <th><a name="table3">Variable Name:</a></th>
 108  <th>Value Type:</th>
 109  <th>Description:</th>
 110 </tr>
 111 <tr><td><code>HTTPS</code></td>                         <td>flag</td>      <td>HTTPS is being used.</td></tr>
 112 <tr><td><code>SSL_PROTOCOL</code></td>                  <td>string</td>    <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr>
 113 <tr><td><code>SSL_SESSION_ID</code></td>                <td>string</td>    <td>The hex-encoded SSL session id</td></tr>
 114 <tr><td><code>SSL_SESSION_RESUMED</code></td>           <td>string</td>    <td>Initial or Resumed SSL Session.  Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use</td></tr>
 115 <tr><td><code>SSL_SECURE_RENEG</code></td>              <td>string</td>    <td><code>true</code> if secure renegotiation is supported, else <code>false</code></td></tr>
 116 <tr><td><code>SSL_CIPHER</code></td>                    <td>string</td>    <td>The cipher specification name</td></tr>
 117 <tr><td><code>SSL_CIPHER_EXPORT</code></td>             <td>string</td>    <td><code>true</code> if cipher is an export cipher</td></tr>
 118 <tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td>         <td>number</td>    <td>Number of cipher bits (actually used)</td></tr>
 119 <tr><td><code>SSL_CIPHER_ALGKEYSIZE</code></td>         <td>number</td>    <td>Number of cipher bits (possible)</td></tr>
 120 <tr><td><code>SSL_COMPRESS_METHOD</code></td>           <td>string</td>    <td>SSL compression method negotiated</td></tr>
 121 <tr><td><code>SSL_VERSION_INTERFACE</code></td>         <td>string</td>    <td>The mod_ssl program version</td></tr>
 122 <tr><td><code>SSL_VERSION_LIBRARY</code></td>           <td>string</td>    <td>The OpenSSL program version</td></tr>
 123 <tr><td><code>SSL_CLIENT_M_VERSION</code></td>          <td>string</td>    <td>The version of the client certificate</td></tr>
 124 <tr><td><code>SSL_CLIENT_M_SERIAL</code></td>           <td>string</td>    <td>The serial of the client certificate</td></tr>
 125 <tr><td><code>SSL_CLIENT_S_DN</code></td>               <td>string</td>    <td>Subject DN in client's certificate</td></tr>
 126 <tr><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td>    <td>Component of client's Subject DN</td></tr>
 127 <tr><td><code>SSL_CLIENT_I_DN</code></td>               <td>string</td>    <td>Issuer DN of client's certificate</td></tr>
 128 <tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td>    <td>Component of client's Issuer DN</td></tr>
 129 <tr><td><code>SSL_CLIENT_V_START</code></td>            <td>string</td>    <td>Validity of client's certificate (start time)</td></tr>
 130 <tr><td><code>SSL_CLIENT_V_END</code></td>              <td>string</td>    <td>Validity of client's certificate (end time)</td></tr>
 131 <tr><td><code>SSL_CLIENT_V_REMAIN</code></td>           <td>string</td>    <td>Number of days until client's certificate expires</td></tr>
 132 <tr><td><code>SSL_CLIENT_A_SIG</code></td>              <td>string</td>    <td>Algorithm used for the signature of client's certificate</td></tr>
 133 <tr><td><code>SSL_CLIENT_A_KEY</code></td>              <td>string</td>    <td>Algorithm used for the public key of client's certificate</td></tr>
 134 <tr><td><code>SSL_CLIENT_CERT</code></td>               <td>string</td>    <td>PEM-encoded client certificate</td></tr>
 135 <tr><td><code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em></td> <td>string</td>    <td>PEM-encoded certificates in client certificate chain</td></tr>
 136 <tr><td><code>SSL_CLIENT_VERIFY</code></td>             <td>string</td>    <td><code>NONE</code>, <code>SUCCESS</code>, <code>GENEROUS</code> or <code>FAILED:</code><em>reason</em></td></tr>
 137 <tr><td><code>SSL_SERVER_M_VERSION</code></td>          <td>string</td>    <td>The version of the server certificate</td></tr>
 138 <tr><td><code>SSL_SERVER_M_SERIAL</code></td>           <td>string</td>    <td>The serial of the server certificate</td></tr>
 139 <tr><td><code>SSL_SERVER_S_DN</code></td>               <td>string</td>    <td>Subject DN in server's certificate</td></tr>
 140 <tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td>    <td>Component of server's Subject DN</td></tr>
 141 <tr><td><code>SSL_SERVER_I_DN</code></td>               <td>string</td>    <td>Issuer DN of server's certificate</td></tr>
 142 <tr><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td>    <td>Component of server's Issuer DN</td></tr>
 143 <tr><td><code>SSL_SERVER_V_START</code></td>            <td>string</td>    <td>Validity of server's certificate (start time)</td></tr>
 144 <tr><td><code>SSL_SERVER_V_END</code></td>              <td>string</td>    <td>Validity of server's certificate (end time)</td></tr>
 145 <tr><td><code>SSL_SERVER_A_SIG</code></td>              <td>string</td>    <td>Algorithm used for the signature of server's certificate</td></tr>
 146 <tr><td><code>SSL_SERVER_A_KEY</code></td>              <td>string</td>    <td>Algorithm used for the public key of server's certificate</td></tr>
 147 <tr><td><code>SSL_SERVER_CERT</code></td>               <td>string</td>    <td>PEM-encoded server certificate</td></tr>
 148 </table>
 149
 150 <p><em>x509</em> specifies a component of an X.509 DN; one of
 151 <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>.  In Apache 2.1 and
 152 later, <em>x509</em> may also include a numeric <code>_n</code>
 153 suffix.  If the DN in question contains multiple attributes of the
 154 same name, this suffix is used as an index to select a particular
 155 attribute.  For example, where the server certificate subject DN
 156 included two OU fields, <code>SSL_SERVER_S_DN_OU_0</code> and
 157 <code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each.</p>
 158
 159 <p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1
 160 and later.</p>
 161
 162 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 163 <div class="section">
 164 <h2><a name="logformats" id="logformats">Custom Log Formats</a></h2>
 165
 166 <p>When <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least
 167 loaded (under DSO situation) additional functions exist for the <a href="mod_log_config.html#formats">Custom Log Format</a> of
 168 <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>. First there is an
 169 additional ``<code>%{</code><em>varname</em><code>}x</code>''
 170 eXtension format function which can be used to expand any variables
 171 provided by any module, especially those provided by mod_ssl which can
 172 you find in the above table.</p>
 173 <p>
 174 For backward compatibility there is additionally a special
 175 ``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
 176 provided. Information about this function is provided in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p>
 177 <div class="example"><h3>Example</h3><p><code>
 178 CustomLog logs/ssl_request_log \
 179           "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
 180 </code></p></div>
 181 </div>
 182 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 183 <div class="directive-section"><h2><a name="SSLCACertificateFile" id="SSLCACertificateFile">SSLCACertificateFile</a> <a name="sslcacertificatefile" id="sslcacertificatefile">Directive</a></h2>
 184 <table class="directive">
 185 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates
 186 for Client Auth</td></tr>
 187 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificateFile <em>file-path</em></code></td></tr>
 188 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 189 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 190 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 191 </table>
 192 <p>
 193 This directive sets the <em>all-in-one</em> file where you can assemble the
 194 Certificates of Certification Authorities (CA) whose <em>clients</em> you deal
 195 with. These are used for Client Authentication. Such a file is simply the
 196 concatenation of the various PEM-encoded Certificate files, in order of
 197 preference. This can be used alternatively and/or additionally to
 198 <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>.</p>
 199 <div class="example"><h3>Example</h3><p><code>
 200 SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt
 201 </code></p></div>
 202
 203 </div>
 204 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 205 <div class="directive-section"><h2><a name="SSLCACertificatePath" id="SSLCACertificatePath">SSLCACertificatePath</a> <a name="sslcacertificatepath" id="sslcacertificatepath">Directive</a></h2>
 206 <table class="directive">
 207 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for
 208 Client Auth</td></tr>
 209 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificatePath <em>directory-path</em></code></td></tr>
 210 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 211 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 212 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 213 </table>
 214 <p>
 215 This directive sets the directory where you keep the Certificates of
 216 Certification Authorities (CAs) whose clients you deal with. These are used to
 217 verify the client certificate on Client Authentication.</p>
 218 <p>
 219 The files in this directory have to be PEM-encoded and are accessed through
 220 hash filenames. So usually you can't just place the Certificate files
 221 there: you also have to create symbolic links named
 222 <em>hash-value</em><code>.N</code>. And you should always make sure this directory
 223 contains the appropriate symbolic links. Use the <code>Makefile</code> which
 224 comes with mod_ssl to accomplish this task.</p>
 225 <div class="example"><h3>Example</h3><p><code>
 226 SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/
 227 </code></p></div>
 228
 229 </div>
 230 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 231 <div class="directive-section"><h2><a name="SSLCADNRequestFile" id="SSLCADNRequestFile">SSLCADNRequestFile</a> <a name="sslcadnrequestfile" id="sslcadnrequestfile">Directive</a></h2>
 232 <table class="directive">
 233 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates
 234 for defining acceptable CA names</td></tr>
 235 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestFile <em>file-path</em></code></td></tr>
 236 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 237 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 238 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 239 </table>
 240 <p>When a client certificate is requested by mod_ssl, a list of
 241 <em>acceptable Certificate Authority names</em> is sent to the client
 242 in the SSL handshake.  These CA names can be used by the client to
 243 select an appropriate client certificate out of those it has
 244 available.</p>
 245
 246 <p>If neither of the directives <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code> or <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> are given, then the
 247 set of acceptable CA names sent to the client is the names of all the
 248 CA certificates given by the <code class="directive"><a href="#sslcacertificatefile">SSLCACertificateFile</a></code> and <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> directives; in other
 249 words, the names of the CAs which will actually be used to verify the
 250 client certificate.</p>
 251
 252 <p>In some circumstances, it is useful to be able to send a set of
 253 acceptable CA names which differs from the actual CAs used to verify
 254 the client certificate - for example, if the client certificates are
 255 signed by intermediate CAs.  In such cases, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code> and/or <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> can be used; the
 256 acceptable CA names are then taken from the complete set of
 257 certificates in the directory and/or file specified by this pair of
 258 directives.</p>
 259
 260 <p><code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> must
 261 specify an <em>all-in-one</em> file containing a concatenation of
 262 PEM-encoded CA certificates.</p>
 263
 264 <div class="example"><h3>Example</h3><p><code>
 265 SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt
 266 </code></p></div>
 267
 268 </div>
 269 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 270 <div class="directive-section"><h2><a name="SSLCADNRequestPath" id="SSLCADNRequestPath">SSLCADNRequestPath</a> <a name="sslcadnrequestpath" id="sslcadnrequestpath">Directive</a></h2>
 271 <table class="directive">
 272 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for
 273 defining acceptable CA names</td></tr>
 274 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestPath <em>directory-path</em></code></td></tr>
 275 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 276 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 277 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 278 </table>
 279
 280 <p>This optional directive can be used to specify the set of
 281 <em>acceptable CA names</em> which will be sent to the client when a
 282 client certificate is requested.  See the <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> directive for more
 283 details.</p>
 284
 285 <p>The files in this directory have to be PEM-encoded and are accessed
 286 through hash filenames. So usually you can't just place the
 287 Certificate files there: you also have to create symbolic links named
 288 <em>hash-value</em><code>.N</code>. And you should always make sure
 289 this directory contains the appropriate symbolic links. Use the
 290 <code>Makefile</code> which comes with mod_ssl to accomplish this
 291 task.</p>
 292 <div class="example"><h3>Example</h3><p><code>
 293 SSLCADNRequestPath /usr/local/apache2/conf/ca-names.crt/
 294 </code></p></div>
 295
 296 </div>
 297 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 298 <div class="directive-section"><h2><a name="SSLCARevocationFile" id="SSLCARevocationFile">SSLCARevocationFile</a> <a name="sslcarevocationfile" id="sslcarevocationfile">Directive</a></h2>
 299 <table class="directive">
 300 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for
 301 Client Auth</td></tr>
 302 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationFile <em>file-path</em></code></td></tr>
 303 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 304 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 305 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 306 </table>
 307 <p>
 308 This directive sets the <em>all-in-one</em> file where you can
 309 assemble the Certificate Revocation Lists (CRL) of Certification
 310 Authorities (CA) whose <em>clients</em> you deal with. These are used
 311 for Client Authentication.  Such a file is simply the concatenation of
 312 the various PEM-encoded CRL files, in order of preference. This can be
 313 used alternatively and/or additionally to <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>.</p>
 314 <div class="example"><h3>Example</h3><p><code>
 315 SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl
 316 </code></p></div>
 317
 318 </div>
 319 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 320 <div class="directive-section"><h2><a name="SSLCARevocationPath" id="SSLCARevocationPath">SSLCARevocationPath</a> <a name="sslcarevocationpath" id="sslcarevocationpath">Directive</a></h2>
 321 <table class="directive">
 322 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for
 323 Client Auth</td></tr>
 324 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationPath <em>directory-path</em></code></td></tr>
 325 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 326 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 327 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 328 </table>
 329 <p>
 330 This directive sets the directory where you keep the Certificate Revocation
 331 Lists (CRL) of Certification Authorities (CAs) whose clients you deal with.
 332 These are used to revoke the client certificate on Client Authentication.</p>
 333 <p>
 334 The files in this directory have to be PEM-encoded and are accessed through
 335 hash filenames. So usually you have not only to place the CRL files there.
 336 Additionally you have to create symbolic links named
 337 <em>hash-value</em><code>.rN</code>. And you should always make sure this directory
 338 contains the appropriate symbolic links. Use the <code>Makefile</code> which
 339 comes with <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> to accomplish this task.</p>
 340 <div class="example"><h3>Example</h3><p><code>
 341 SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/
 342 </code></p></div>
 343
 344 </div>
 345 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 346 <div class="directive-section"><h2><a name="SSLCertificateChainFile" id="SSLCertificateChainFile">SSLCertificateChainFile</a> <a name="sslcertificatechainfile" id="sslcertificatechainfile">Directive</a></h2>
 347 <table class="directive">
 348 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of PEM-encoded Server CA Certificates</td></tr>
 349 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateChainFile <em>file-path</em></code></td></tr>
 350 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 351 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 352 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 353 </table>
 354 <p>
 355 This directive sets the optional <em>all-in-one</em> file where you can
 356 assemble the certificates of Certification Authorities (CA) which form the
 357 certificate chain of the server certificate. This starts with the issuing CA
 358 certificate of the server certificate and can range up to the root CA
 359 certificate. Such a file is simply the concatenation of the various
 360 PEM-encoded CA Certificate files, usually in certificate chain order.</p>
 361 <p>
 362 This should be used alternatively and/or additionally to <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> for explicitly
 363 constructing the server certificate chain which is sent to the browser
 364 in addition to the server certificate. It is especially useful to
 365 avoid conflicts with CA certificates when using client
 366 authentication. Because although placing a CA certificate of the
 367 server certificate chain into <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> has the same effect
 368 for the certificate chain construction, it has the side-effect that
 369 client certificates issued by this same CA certificate are also
 370 accepted on client authentication.</p>
 371 <p>
 372 But be careful: Providing the certificate chain works only if you are using a
 373 <em>single</em> RSA <em>or</em> DSA based server certificate. If you are
 374 using a coupled RSA+DSA certificate pair, this will work only if actually both
 375 certificates use the <em>same</em> certificate chain. Else the browsers will be
 376 confused in this situation.</p>
 377 <div class="example"><h3>Example</h3><p><code>
 378 SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt
 379 </code></p></div>
 380
 381 </div>
 382 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 383 <div class="directive-section"><h2><a name="SSLCertificateFile" id="SSLCertificateFile">SSLCertificateFile</a> <a name="sslcertificatefile" id="sslcertificatefile">Directive</a></h2>
 384 <table class="directive">
 385 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded X.509 Certificate file</td></tr>
 386 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateFile <em>file-path</em></code></td></tr>
 387 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 388 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 389 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 390 </table>
 391 <p>
 392 This directive points to the PEM-encoded Certificate file for the server and
 393 optionally also to the corresponding RSA or DSA Private Key file for it
 394 (contained in the same file). If the contained Private Key is encrypted the
 395 Pass Phrase dialog is forced at startup time. This directive can be used up to
 396 two times (referencing different filenames) when both a RSA and a DSA based
 397 server certificate is used in parallel.</p>
 398 <div class="example"><h3>Example</h3><p><code>
 399 SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt
 400 </code></p></div>
 401
 402 </div>
 403 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 404 <div class="directive-section"><h2><a name="SSLCertificateKeyFile" id="SSLCertificateKeyFile">SSLCertificateKeyFile</a> <a name="sslcertificatekeyfile" id="sslcertificatekeyfile">Directive</a></h2>
 405 <table class="directive">
 406 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded Private Key file</td></tr>
 407 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateKeyFile <em>file-path</em></code></td></tr>
 408 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 409 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 410 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 411 </table>
 412 <p>
 413 This directive points to the PEM-encoded Private Key file for the
 414 server. If the Private Key is not combined with the Certificate in the
 415 <code class="directive">SSLCertificateFile</code>, use this additional directive to
 416 point to the file with the stand-alone Private Key. When
 417 <code class="directive">SSLCertificateFile</code> is used and the file
 418 contains both the Certificate and the Private Key this directive need
 419 not be used. But we strongly discourage this practice.  Instead we
 420 recommend you to separate the Certificate and the Private Key. If the
 421 contained Private Key is encrypted, the Pass Phrase dialog is forced
 422 at startup time. This directive can be used up to two times
 423 (referencing different filenames) when both a RSA and a DSA based
 424 private key is used in parallel.</p>
 425 <div class="example"><h3>Example</h3><p><code>
 426 SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key
 427 </code></p></div>
 428
 429 </div>
 430 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 431 <div class="directive-section"><h2><a name="SSLCipherSuite" id="SSLCipherSuite">SSLCipherSuite</a> <a name="sslciphersuite" id="sslciphersuite">Directive</a></h2>
 432 <table class="directive">
 433 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL
 434 handshake</td></tr>
 435 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCipherSuite <em>cipher-spec</em></code></td></tr>
 436 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code></td></tr>
 437 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 438 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 439 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 440 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 441 </table>
 442 <p>
 443 This complex directive uses a colon-separated <em>cipher-spec</em> string
 444 consisting of OpenSSL cipher specifications to configure the Cipher Suite the
 445 client is permitted to negotiate in the SSL handshake phase. Notice that this
 446 directive can be used both in per-server and per-directory context. In
 447 per-server context it applies to the standard SSL handshake when a connection
 448 is established. In per-directory context it forces a SSL renegotation with the
 449 reconfigured Cipher Suite after the HTTP request was read but before the HTTP
 450 response is sent.</p>
 451 <p>
 452 An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major
 453 attributes plus a few extra minor ones:</p>
 454 <ul>
 455 <li><em>Key Exchange Algorithm</em>:<br />
 456     RSA or Diffie-Hellman variants.
 457 </li>
 458 <li><em>Authentication Algorithm</em>:<br />
 459     RSA, Diffie-Hellman, DSS or none.
 460 </li>
 461 <li><em>Cipher/Encryption Algorithm</em>:<br />
 462     DES, Triple-DES, RC4, RC2, IDEA or none.
 463 </li>
 464 <li><em>MAC Digest Algorithm</em>:<br />
 465     MD5, SHA or SHA1.
 466 </li>
 467 </ul>
 468 <p>An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1
 469 cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use,
 470 one can either specify all the Ciphers, one at a time, or use aliases to
 471 specify the preference and order for the ciphers (see <a href="#table1">Table
 472 1</a>).</p>
 473
 474 <table class="bordered">
 475
 476 <tr><th><a name="table1">Tag</a></th> <th>Description</th></tr>
 477 <tr><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr>
 478 <tr><td><code>kRSA</code></td>   <td>RSA key exchange</td></tr>
 479 <tr><td><code>kDHr</code></td>   <td>Diffie-Hellman key exchange with RSA key</td></tr>
 480 <tr><td><code>kDHd</code></td>   <td>Diffie-Hellman key exchange with DSA key</td></tr>
 481 <tr><td><code>kEDH</code></td>   <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td>   </tr>
 482 <tr><td colspan="2"><em>Authentication Algorithm:</em></td></tr>
 483 <tr><td><code>aNULL</code></td>  <td>No authentication</td></tr>
 484 <tr><td><code>aRSA</code></td>   <td>RSA authentication</td></tr>
 485 <tr><td><code>aDSS</code></td>   <td>DSS authentication</td> </tr>
 486 <tr><td><code>aDH</code></td>    <td>Diffie-Hellman authentication</td></tr>
 487 <tr><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr>
 488 <tr><td><code>eNULL</code></td>  <td>No encoding</td>         </tr>
 489 <tr><td><code>DES</code></td>    <td>DES encoding</td>        </tr>
 490 <tr><td><code>3DES</code></td>   <td>Triple-DES encoding</td> </tr>
 491 <tr><td><code>RC4</code></td>    <td>RC4 encoding</td>       </tr>
 492 <tr><td><code>RC2</code></td>    <td>RC2 encoding</td>       </tr>
 493 <tr><td><code>IDEA</code></td>   <td>IDEA encoding</td>       </tr>
 494 <tr><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr>
 495 <tr><td><code>MD5</code></td>    <td>MD5 hash function</td></tr>
 496 <tr><td><code>SHA1</code></td>   <td>SHA1 hash function</td></tr>
 497 <tr><td><code>SHA</code></td>    <td>SHA hash function</td> </tr>
 498 <tr><td colspan="2"><em>Aliases:</em></td></tr>
 499 <tr><td><code>SSLv2</code></td>  <td>all SSL version 2.0 ciphers</td></tr>
 500 <tr><td><code>SSLv3</code></td>  <td>all SSL version 3.0 ciphers</td> </tr>
 501 <tr><td><code>TLSv1</code></td>  <td>all TLS version 1.0 ciphers</td> </tr>
 502 <tr><td><code>EXP</code></td>    <td>all export ciphers</td>  </tr>
 503 <tr><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td>  </tr>
 504 <tr><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td>  </tr>
 505 <tr><td><code>LOW</code></td>    <td>all low strength ciphers (no export, single DES)</td></tr>
 506 <tr><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr>
 507 <tr><td><code>HIGH</code></td>   <td>all ciphers using Triple-DES</td>     </tr>
 508 <tr><td><code>RSA</code></td>    <td>all ciphers using RSA key exchange</td> </tr>
 509 <tr><td><code>DH</code></td>     <td>all ciphers using Diffie-Hellman key exchange</td> </tr>
 510 <tr><td><code>EDH</code></td>    <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr>
 511 <tr><td><code>ADH</code></td>    <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr>
 512 <tr><td><code>DSS</code></td>    <td>all ciphers using DSS authentication</td> </tr>
 513 <tr><td><code>NULL</code></td>   <td>all ciphers using no encryption</td> </tr>
 514 </table>
 515 <p>
 516 Now where this becomes interesting is that these can be put together
 517 to specify the order and ciphers you wish to use. To speed this up
 518 there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM,
 519 HIGH</code>) for certain groups of ciphers. These tags can be joined
 520 together with prefixes to form the <em>cipher-spec</em>. Available
 521 prefixes are:</p>
 522 <ul>
 523 <li>none: add cipher to list</li>
 524 <li><code>+</code>: add ciphers to list and pull them to current location in list</li>
 525 <li><code>-</code>: remove cipher from list (can be added later again)</li>
 526 <li><code>!</code>: kill cipher from list completely (can <strong>not</strong> be added later again)</li>
 527 </ul>
 528 <p>A simpler way to look at all of this is to use the ``<code>openssl ciphers
 529 -v</code>'' command which provides a nice way to successively create the
 530 correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string
 531 is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which
 532 means the following: first, remove from consideration any ciphers that do not
 533 authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
 534 use ciphers using RC4 and RSA. Next include the high, medium and then the low
 535 security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the
 536 end of the list.</p>
 537 <div class="example"><pre>
 538 $ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
 539 NULL-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=SHA1
 540 NULL-MD5                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=MD5
 541 EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
 542 ...                     ...               ...     ...           ...
 543 EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
 544 EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
 545 EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
 546 </pre></div>
 547 <p>The complete list of particular RSA &amp; DH ciphers for SSL is given in <a href="#table2">Table 2</a>.</p>
 548 <div class="example"><h3>Example</h3><p><code>
 549 SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
 550 </code></p></div>
 551 <table class="bordered">
 552
 553 <tr><th><a name="table2">Cipher-Tag</a></th> <th>Protocol</th> <th>Key Ex.</th> <th>Auth.</th> <th>Enc.</th> <th>MAC</th> <th>Type</th> </tr>
 554 <tr><td colspan="7"><em>RSA Ciphers:</em></td></tr>
 555 <tr><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr>
 556 <tr><td><code>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</td> <td /> </tr>
 557 <tr><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td /> </tr>
 558 <tr><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td /> </tr>
 559 <tr><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td /> </tr>
 560 <tr><td><code>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td /> </tr>
 561 <tr><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td /> </tr>
 562 <tr><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td /> </tr>
 563 <tr><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr>
 564 <tr><td><code>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td /> </tr>
 565 <tr><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td /> </tr>
 566 <tr><td><code>EXP-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>
 567 <tr><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td>  export</td> </tr>
 568 <tr><td><code>EXP-RC4-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td>  export</td> </tr>
 569 <tr><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td>  export</td> </tr>
 570 <tr><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td>  export</td> </tr>
 571 <tr><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td /> </tr>
 572 <tr><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td /> </tr>
 573 <tr><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr>
 574 <tr><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr>
 575 <tr><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr>
 576 <tr><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td /> </tr>
 577 <tr><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr>
 578 <tr><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr>
 579 <tr><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr>
 580 <tr><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr>
 581 <tr><td><code>EXP-EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>
 582 <tr><td><code>EXP-EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>DSS</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>
 583 <tr><td><code>EXP-ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr>
 584 <tr><td><code>EXP-ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>RC4(40)</td> <td>MD5</td> <td>  export</td> </tr>
 585 </table>
 586
 587 </div>
 588 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 589 <div class="directive-section"><h2><a name="SSLCryptoDevice" id="SSLCryptoDevice">SSLCryptoDevice</a> <a name="sslcryptodevice" id="sslcryptodevice">Directive</a></h2>
 590 <table class="directive">
 591 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable use of a cryptographic hardware accelerator</td></tr>
 592 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCryptoDevice <em>engine</em></code></td></tr>
 593 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCryptoDevice builtin</code></td></tr>
 594 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 595 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 596 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 597 </table>
 598 <p>
 599 This directive enables use of a cryptographic hardware accelerator
 600 board to offload some of the SSL processing overhead.  This directive
 601 can only be used if the SSL toolkit is built with "engine" support;
 602 OpenSSL 0.9.7 and later releases have "engine" support by default, the
 603 separate "-engine" releases of OpenSSL 0.9.6 must be used.</p>
 604
 605 <p>To discover which engine names are supported, run the command
 606 "<code>openssl engine</code>".</p>
 607
 608 <div class="example"><h3>Example</h3><p><code>
 609 # For a Broadcom accelerator:<br />
 610 SSLCryptoDevice ubsec
 611 </code></p></div>
 612
 613 </div>
 614 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 615 <div class="directive-section"><h2><a name="SSLEngine" id="SSLEngine">SSLEngine</a> <a name="sslengine" id="sslengine">Directive</a></h2>
 616 <table class="directive">
 617 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Engine Operation Switch</td></tr>
 618 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLEngine on|off|optional</code></td></tr>
 619 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLEngine off</code></td></tr>
 620 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 621 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 622 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 623 </table>
 624 <p>
 625 This directive toggles the usage of the SSL/TLS Protocol Engine. This
 626 is usually used inside a <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code> section to enable SSL/TLS for a
 627 particular virtual host. By default the SSL/TLS Protocol Engine is
 628 disabled for both the main server and all configured virtual hosts.</p>
 629 <div class="example"><h3>Example</h3><p><code>
 630 &lt;VirtualHost _default_:443&gt;<br />
 631 SSLEngine on<br />
 632 ...<br />
 633 &lt;/VirtualHost&gt;
 634 </code></p></div>
 635 <p>In Apache 2.1 and later, <code class="directive">SSLEngine</code> can be set to
 636 <code>optional</code>. This enables support for
 637 <a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS
 638 Within HTTP/1.1. At this time no web browsers support RFC 2817.</p>
 639
 640 </div>
 641 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 642 <div class="directive-section"><h2><a name="SSLHonorCipherOrder" id="SSLHonorCipherOrder">SSLHonorCipherOrder</a> <a name="sslhonorcipherorder" id="sslhonorcipherorder">Directive</a></h2>
 643 <table class="directive">
 644 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Option to prefer the server's cipher preference order</td></tr>
 645 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLHonorCiperOrder <em>flag</em></code></td></tr>
 646 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 647 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 648 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 649 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later, if using OpenSSL 0.9.7 or later</td></tr>
 650 </table>
 651 <p>When choosing a cipher during an SSLv3 or TLSv1 handshake, normally
 652 the client's preference is used.  If this directive is enabled, the
 653 server's preference will be used instead.</p>
 654 <div class="example"><h3>Example</h3><p><code>
 655 SSLHonorCipherOrder on
 656 </code></p></div>
 657
 658 </div>
 659 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 660 <div class="directive-section"><h2><a name="SSLInsecureRenegotiation" id="SSLInsecureRenegotiation">SSLInsecureRenegotiation</a> <a name="sslinsecurerenegotiation" id="sslinsecurerenegotiation">Directive</a></h2>
 661 <table class="directive">
 662 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Option to enable support for insecure renegotiation</td></tr>
 663 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLInsecureRenegotiation <em>flag</em></code></td></tr>
 664 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 665 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 666 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 667 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 1.0.0 Beta 5 or later</td></tr>
 668 </table>
 669 <p>As originally specified, all versions of the SSL and TLS protocols
 670 (up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle
 671 attack
 672 (<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555">CVE-2009-3555</a>)
 673 during a renegotiation.  This vulnerability allowed an attacker to
 674 "prefix" a chosen plaintext to the HTTP request as seen by the web
 675 server.  A protocol extension was developed which fixed this
 676 vulnerability if supported by both client and server.</p>
 677
 678 <p>If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is linked against OpenSSL version 1.0.0
 679 Beta 5 or later, by default renegotiation is only supported with
 680 clients supporting the new protocol extension.  If this directive is
 681 enabled, renegotiation will be allowed with old (unpatched) clients.
 682 SSL connections will be vulnerable to the prefix attack as described
 683 above if this directive is enabled.  The <code>SSL_SECURE_RENEG</code>
 684 variable can be used to determine whether secure renegotiation is
 685 supported for a given SSL connection.</p>
 686
 687 <div class="example"><h3>Example</h3><p><code>
 688 SSLInsecureRenegotiation on
 689 </code></p></div>
 690
 691 </div>
 692 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 693 <div class="directive-section"><h2><a name="SSLOCSPDefaultResponder" id="SSLOCSPDefaultResponder">SSLOCSPDefaultResponder</a> <a name="sslocspdefaultresponder" id="sslocspdefaultresponder">Directive</a></h2>
 694 <table class="directive">
 695 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the default responder URI for OCSP validation</td></tr>
 696 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSDefaultResponder <em>uri</em></code></td></tr>
 697 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 698 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 699 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 700 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr>
 701 </table>
 702 <p>This option sets the default OCSP responder to use.  If <code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code> is not enabled,
 703 the URI given will be used only if no responder URI is specified in
 704 the certificate being verified.</p>
 705
 706 </div>
 707 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 708 <div class="directive-section"><h2><a name="SSLOCSPEnable" id="SSLOCSPEnable">SSLOCSPEnable</a> <a name="sslocspenable" id="sslocspenable">Directive</a></h2>
 709 <table class="directive">
 710 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable OCSP validation of the client certificate chain</td></tr>
 711 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPEnable <em>flag</em></code></td></tr>
 712 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 713 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 714 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 715 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr>
 716 </table>
 717 <p>This option enables OCSP validation of the client certificate
 718 chain.  If this option is enabled, certificates in the client's
 719 certificate chain will be validated against an OCSP responder after
 720 normal verification (including CRL checks) have taken place.</p>
 721
 722 <p>The OCSP responder used is either extracted from the certificate
 723 itself, or derived by configuration; see the
 724 <code class="directive"><a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></code> and
 725 <code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code>
 726 directives.</p>
 727
 728 <div class="example"><h3>Example</h3><p><code>
 729 SSLVerifyClient on<br />
 730 SSLOCSPEnable on<br />
 731 SSLOCSPDefaultResponder http://responder.example.com:8888/responder<br />
 732 SSLOCSPOverrideResponder on
 733 </code></p></div>
 734
 735 </div>
 736 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 737 <div class="directive-section"><h2><a name="SSLOCSPOverrideResponder" id="SSLOCSPOverrideResponder">SSLOCSPOverrideResponder</a> <a name="sslocspoverrideresponder" id="sslocspoverrideresponder">Directive</a></h2>
 738 <table class="directive">
 739 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Force use of the default responder URI for OCSP validation</td></tr>
 740 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPOverrideResponder <em>flag</em></code></td></tr>
 741 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 742 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 743 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 744 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr>
 745 </table>
 746 <p>This option forces the configured default OCSP responder to be used
 747 during OCSP certificate validation, regardless of whether the
 748 certificate being validated references an OCSP responder.</p>
 749
 750 </div>
 751 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 752 <div class="directive-section"><h2><a name="SSLOptions" id="SSLOptions">SSLOptions</a> <a name="ssloptions" id="ssloptions">Directive</a></h2>
 753 <table class="directive">
 754 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure various SSL engine run-time options</td></tr>
 755 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOptions [+|-]<em>option</em> ...</code></td></tr>
 756 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 757 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
 758 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 759 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 760 </table>
 761 <p>
 762 This directive can be used to control various run-time options on a
 763 per-directory basis. Normally, if multiple <code>SSLOptions</code>
 764 could apply to a directory, then the most specific one is taken
 765 completely; the options are not merged. However if <em>all</em> the
 766 options on the <code>SSLOptions</code> directive are preceded by a
 767 plus (<code>+</code>) or minus (<code>-</code>) symbol, the options
 768 are merged. Any options preceded by a <code>+</code> are added to the
 769 options currently in force, and any options preceded by a
 770 <code>-</code> are removed from the options currently in force.</p>
 771 <p>
 772 The available <em>option</em>s are:</p>
 773 <ul>
 774 <li><code>StdEnvVars</code>
 775     <p>
 776     When this option is enabled, the standard set of SSL related CGI/SSI
 777     environment variables are created. This per default is disabled for
 778     performance reasons, because the information extraction step is a
 779     rather expensive operation. So one usually enables this option for
 780     CGI and SSI requests only.</p>
 781 </li>
 782 <li><code>ExportCertData</code>
 783     <p>
 784     When this option is enabled, additional CGI/SSI environment variables are
 785     created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and
 786     <code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em> (with <em>n</em> = 0,1,2,..).
 787     These contain the PEM-encoded X.509 Certificates of server and client for
 788     the current HTTPS connection and can be used by CGI scripts for deeper
 789     Certificate checking. Additionally all other certificates of the client
 790     certificate chain are provided, too. This bloats up the environment a
 791     little bit which is why you have to use this option to enable it on
 792     demand.</p>
 793 </li>
 794 <li><code>FakeBasicAuth</code>
 795     <p>
 796     When this option is enabled, the Subject Distinguished Name (DN) of the
 797     Client X509 Certificate is translated into a HTTP Basic Authorization
 798     username. This means that the standard Apache authentication methods can
 799     be used for access control. The user name is just the Subject of the
 800     Client's X509 Certificate (can be determined by running OpenSSL's
 801     <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in
 802     </code><em>certificate</em><code>.crt</code>). Note that no password is
 803     obtained from the user. Every entry in the user file needs this password:
 804     ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the
 805     word `<code>password</code>''. Those who live under MD5-based encryption
 806     (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5
 807     hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.</p>
 808 </li>
 809 <li><code>StrictRequire</code>
 810     <p>
 811     This <em>forces</em> forbidden access when <code>SSLRequireSSL</code> or
 812     <code>SSLRequire</code> successfully decided that access should be
 813     forbidden. Usually the default is that in the case where a ``<code>Satisfy
 814     any</code>'' directive is used, and other access restrictions are passed,
 815     denial of access due to <code>SSLRequireSSL</code> or
 816     <code>SSLRequire</code> is overridden (because that's how the Apache
 817     <code>Satisfy</code> mechanism should work.) But for strict access restriction
 818     you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in
 819     combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an
 820     additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has
 821     decided to deny access.</p>
 822 </li>
 823 <li><code>OptRenegotiate</code>
 824     <p>
 825     This enables optimized SSL connection renegotiation handling when SSL
 826     directives are used in per-directory context. By default a strict
 827     scheme is enabled where <em>every</em> per-directory reconfiguration of
 828     SSL parameters causes a <em>full</em> SSL renegotiation handshake. When this
 829     option is used mod_ssl tries to avoid unnecessary handshakes by doing more
 830     granular (but still safe) parameter checks. Nevertheless these granular
 831     checks sometimes maybe not what the user expects, so enable this on a
 832     per-directory basis only, please.</p>
 833 </li>
 834 </ul>
 835 <div class="example"><h3>Example</h3><p><code>
 836 SSLOptions +FakeBasicAuth -StrictRequire<br />
 837 &lt;Files ~ "\.(cgi|shtml)$"&gt;<br />
 838     SSLOptions +StdEnvVars -ExportCertData<br />
 839 &lt;Files&gt;
 840 </code></p></div>
 841
 842 </div>
 843 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 844 <div class="directive-section"><h2><a name="SSLPassPhraseDialog" id="SSLPassPhraseDialog">SSLPassPhraseDialog</a> <a name="sslpassphrasedialog" id="sslpassphrasedialog">Directive</a></h2>
 845 <table class="directive">
 846 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of pass phrase dialog for encrypted private
 847 keys</td></tr>
 848 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLPassPhraseDialog <em>type</em></code></td></tr>
 849 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLPassPhraseDialog builtin</code></td></tr>
 850 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 851 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 852 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 853 </table>
 854 <p>
 855 When Apache starts up it has to read the various Certificate (see
 856 <code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code>) and
 857 Private Key (see <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>) files of the
 858 SSL-enabled virtual servers. Because for security reasons the Private
 859 Key files are usually encrypted, mod_ssl needs to query the
 860 administrator for a Pass Phrase in order to decrypt those files. This
 861 query can be done in two ways which can be configured by
 862 <em>type</em>:</p>
 863 <ul>
 864 <li><code>builtin</code>
 865     <p>
 866     This is the default where an interactive terminal dialog occurs at startup
 867     time just before Apache detaches from the terminal. Here the administrator
 868     has to manually enter the Pass Phrase for each encrypted Private Key file.
 869     Because a lot of SSL-enabled virtual hosts can be configured, the
 870     following reuse-scheme is used to minimize the dialog: When a Private Key
 871     file is encrypted, all known Pass Phrases (at the beginning there are
 872     none, of course) are tried. If one of those known Pass Phrases succeeds no
 873     dialog pops up for this particular Private Key file. If none succeeded,
 874     another Pass Phrase is queried on the terminal and remembered for the next
 875     round (where it perhaps can be reused).</p>
 876     <p>
 877     This scheme allows mod_ssl to be maximally flexible (because for N encrypted
 878     Private Key files you <em>can</em> use N different Pass Phrases - but then
 879     you have to enter all of them, of course) while minimizing the terminal
 880     dialog (i.e. when you use a single Pass Phrase for all N Private Key files
 881     this Pass Phrase is queried only once).</p></li>
 882
 883 <li><code>|/path/to/program [args...]</code>
 884
 885    <p>This mode allows an external program to be used which acts as a
 886    pipe to a particular input device; the program is sent the standard
 887    prompt text used for the <code>builtin</code> mode on
 888    <code>stdin</code>, and is expected to write password strings on
 889    <code>stdout</code>.  If several passwords are needed (or an
 890    incorrect password is entered), additional prompt text will be
 891    written subsequent to the first password being returned, and more
 892    passwords must then be written back.</p></li>
 893
 894 <li><code>exec:/path/to/program</code>
 895     <p>
 896     Here an external program is configured which is called at startup for each
 897     encrypted Private Key file. It is called with two arguments (the first is
 898     of the form ``<code>servername:portnumber</code>'', the second is either
 899     ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which
 900     server and algorithm it has to print the corresponding Pass Phrase to
 901     <code>stdout</code>. The intent is that this external program first runs
 902     security checks to make sure that the system is not compromised by an
 903     attacker, and only when these checks were passed successfully it provides
 904     the Pass Phrase.</p>
 905     <p>
 906     Both these security checks, and the way the Pass Phrase is determined, can
 907     be as complex as you like. Mod_ssl just defines the interface: an
 908     executable program which provides the Pass Phrase on <code>stdout</code>.
 909     Nothing more or less! So, if you're really paranoid about security, here
 910     is your interface. Anything else has to be left as an exercise to the
 911     administrator, because local security requirements are so different.</p>
 912     <p>
 913     The reuse-algorithm above is used here, too. In other words: The external
 914     program is called only once per unique Pass Phrase.</p></li>
 915 </ul>
 916 <div class="example"><h3>Example</h3><p><code>
 917 SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
 918 </code></p></div>
 919
 920 </div>
 921 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 922 <div class="directive-section"><h2><a name="SSLProtocol" id="SSLProtocol">SSLProtocol</a> <a name="sslprotocol" id="sslprotocol">Directive</a></h2>
 923 <table class="directive">
 924 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL protocol versions</td></tr>
 925 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProtocol [+|-]<em>protocol</em> ...</code></td></tr>
 926 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProtocol all</code></td></tr>
 927 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 928 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 929 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 930 </table>
 931 <p>
 932 This directive can be used to control which versions of the SSL protocol
 933 will be accepted in new connections.</p>
 934 <p>
 935 The available (case-insensitive) <em>protocol</em>s are:</p>
 936 <ul>
 937 <li><code>SSLv2</code>
 938     <p>
 939     This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the
 940     original SSL protocol as designed by Netscape Corporation.  Though it's
 941     use has been deprecated, because of weaknesses in the security of the protocol.</p></li>
 942
 943 <li><code>SSLv3</code>
 944     <p>
 945     This is the Secure Sockets Layer (SSL) protocol, version 3.0, from
 946     the Netscape Corporation.
 947     It is the successor to SSLv2 and the predecessor to TLSv1. It's supported by
 948     almost all popular browsers.</p></li>
 949
 950 <li><code>TLSv1</code>
 951     <p>
 952     This is the Transport Layer Security (TLS) protocol, version 1.0. It is the
 953     successor to SSLv3 and is defined in <a href="http://www.ietf.org/rfc/rfc2246.txt">RFC2246</a>.
 954     Which has been obsoleted by <a href="http://www.ietf.org/rfc/rfc4346.txt">RFC4346</a>.</p></li>
 955
 956 <li><code>All</code>
 957     <p>
 958     This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a
 959     convenient way for enabling all protocols except one when used in
 960     combination with the minus sign on a protocol as the example above
 961     shows.</p></li>
 962 </ul>
 963 <div class="example"><h3>Example</h3><p><code>
 964 #   enable SSLv3 and TLSv1, but not SSLv2<br />
 965 SSLProtocol all -SSLv2
 966 </code></p></div>
 967
 968 </div>
 969 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 970 <div class="directive-section"><h2><a name="SSLProxyCACertificateFile" id="SSLProxyCACertificateFile">SSLProxyCACertificateFile</a> <a name="sslproxycacertificatefile" id="sslproxycacertificatefile">Directive</a></h2>
 971 <table class="directive">
 972 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates
 973 for Remote Server Auth</td></tr>
 974 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificateFile <em>file-path</em></code></td></tr>
 975 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 976 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 977 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
 978 </table>
 979 <p>
 980 This directive sets the <em>all-in-one</em> file where you can assemble the
 981 Certificates of Certification Authorities (CA) whose <em>remote servers</em> you deal
 982 with. These are used for Remote Server Authentication. Such a file is simply the
 983 concatenation of the various PEM-encoded Certificate files, in order of
 984 preference. This can be used alternatively and/or additionally to
 985 <code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>.</p>
 986 <div class="example"><h3>Example</h3><p><code>
 987 SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt
 988 </code></p></div>
 989
 990 </div>
 991 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 992 <div class="directive-section"><h2><a name="SSLProxyCACertificatePath" id="SSLProxyCACertificatePath">SSLProxyCACertificatePath</a> <a name="sslproxycacertificatepath" id="sslproxycacertificatepath">Directive</a></h2>
 993 <table class="directive">
 994 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for
 995 Remote Server Auth</td></tr>
 996 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificatePath <em>directory-path</em></code></td></tr>
 997 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 998 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 999 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1000 </table>
1001 <p>
1002 This directive sets the directory where you keep the Certificates of
1003 Certification Authorities (CAs) whose remote servers you deal with. These are used to
1004 verify the remote server certificate on Remote Server Authentication.</p>
1005 <p>
1006 The files in this directory have to be PEM-encoded and are accessed through
1007 hash filenames. So usually you can't just place the Certificate files
1008 there: you also have to create symbolic links named
1009 <em>hash-value</em><code>.N</code>. And you should always make sure this directory
1010 contains the appropriate symbolic links. Use the <code>Makefile</code> which
1011 comes with mod_ssl to accomplish this task.</p>
1012 <div class="example"><h3>Example</h3><p><code>
1013 SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/
1014 </code></p></div>
1015
1016 </div>
1017 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1018 <div class="directive-section"><h2><a name="SSLProxyCARevocationFile" id="SSLProxyCARevocationFile">SSLProxyCARevocationFile</a> <a name="sslproxycarevocationfile" id="sslproxycarevocationfile">Directive</a></h2>
1019 <table class="directive">
1020 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for
1021 Remote Server Auth</td></tr>
1022 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationFile <em>file-path</em></code></td></tr>
1023 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1024 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1025 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1026 </table>
1027 <p>
1028 This directive sets the <em>all-in-one</em> file where you can
1029 assemble the Certificate Revocation Lists (CRL) of Certification
1030 Authorities (CA) whose <em>remote servers</em> you deal with. These are used
1031 for Remote Server Authentication.  Such a file is simply the concatenation of
1032 the various PEM-encoded CRL files, in order of preference. This can be
1033 used alternatively and/or additionally to <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code>.</p>
1034 <div class="example"><h3>Example</h3><p><code>
1035 SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl
1036 </code></p></div>
1037
1038 </div>
1039 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1040 <div class="directive-section"><h2><a name="SSLProxyCARevocationPath" id="SSLProxyCARevocationPath">SSLProxyCARevocationPath</a> <a name="sslproxycarevocationpath" id="sslproxycarevocationpath">Directive</a></h2>
1041 <table class="directive">
1042 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for
1043 Remote Server Auth</td></tr>
1044 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationPath <em>directory-path</em></code></td></tr>
1045 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1046 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1047 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1048 </table>
1049 <p>
1050 This directive sets the directory where you keep the Certificate Revocation
1051 Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with.
1052 These are used to revoke the remote server certificate on Remote Server Authentication.</p>
1053 <p>
1054 The files in this directory have to be PEM-encoded and are accessed through
1055 hash filenames. So usually you have not only to place the CRL files there.
1056 Additionally you have to create symbolic links named
1057 <em>hash-value</em><code>.rN</code>. And you should always make sure this directory
1058 contains the appropriate symbolic links. Use the <code>Makefile</code> which
1059 comes with <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> to accomplish this task.</p>
1060 <div class="example"><h3>Example</h3><p><code>
1061 SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/
1062 </code></p></div>
1063
1064 </div>
1065 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1066 <div class="directive-section"><h2><a name="SSLProxyCheckPeerCN" id="SSLProxyCheckPeerCN">SSLProxyCheckPeerCN</a> <a name="sslproxycheckpeercn" id="sslproxycheckpeercn">Directive</a></h2>
1067 <table class="directive">
1068 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check the remote server certificates CN field
1069 </td></tr>
1070 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerCN on|off</code></td></tr>
1071 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerCN on</code></td></tr>
1072 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1073 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1074 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1075 </table>
1076 <p>
1077 This directive sets whether the remote server certificates CN field is
1078 compared against the hostname of the request URL. If both are not equal
1079 a 502 status code (Bad Gateway) is sent.
1080 </p>
1081 <div class="example"><h3>Example</h3><p><code>
1082 SSLProxyCheckPeerCN on
1083 </code></p></div>
1084
1085 </div>
1086 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1087 <div class="directive-section"><h2><a name="SSLProxyCheckPeerExpire" id="SSLProxyCheckPeerExpire">SSLProxyCheckPeerExpire</a> <a name="sslproxycheckpeerexpire" id="sslproxycheckpeerexpire">Directive</a></h2>
1088 <table class="directive">
1089 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check if remote server certificate is expired
1090 </td></tr>
1091 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerExpire on|off</code></td></tr>
1092 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerExpire on</code></td></tr>
1093 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1094 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1095 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1096 </table>
1097 <p>
1098 This directive sets whether it is checked if the remote server certificate
1099 is expired or not. If the check fails a 502 status code (Bad Gateway) is
1100 sent.
1101 </p>
1102 <div class="example"><h3>Example</h3><p><code>
1103 SSLProxyCheckPeerExpire on
1104 </code></p></div>
1105
1106 </div>
1107 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1108 <div class="directive-section"><h2><a name="SSLProxyCipherSuite" id="SSLProxyCipherSuite">SSLProxyCipherSuite</a> <a name="sslproxyciphersuite" id="sslproxyciphersuite">Directive</a></h2>
1109 <table class="directive">
1110 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL
1111 proxy handshake</td></tr>
1112 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCipherSuite <em>cipher-spec</em></code></td></tr>
1113 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code></td></tr>
1114 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1115 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1116 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1117 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1118 </table>
1119 <p>Equivalent to <code>SSLCipherSuite</code>, but for the proxy connection.
1120 Please refer to <code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code>
1121 for additional information.</p>
1122
1123 </div>
1124 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1125 <div class="directive-section"><h2><a name="SSLProxyEngine" id="SSLProxyEngine">SSLProxyEngine</a> <a name="sslproxyengine" id="sslproxyengine">Directive</a></h2>
1126 <table class="directive">
1127 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Proxy Engine Operation Switch</td></tr>
1128 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyEngine on|off</code></td></tr>
1129 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyEngine off</code></td></tr>
1130 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1131 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1132 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1133 </table>
1134 <p>
1135 This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This
1136 is usually used inside a <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code> section to enable SSL/TLS for proxy
1137 usage in a particular virtual host. By default the SSL/TLS Protocol Engine is
1138 disabled for proxy image both for the main server and all configured virtual hosts.</p>
1139 <div class="example"><h3>Example</h3><p><code>
1140 &lt;VirtualHost _default_:443&gt;<br />
1141 SSLProxyEngine on<br />
1142 ...<br />
1143 &lt;/VirtualHost&gt;
1144 </code></p></div>
1145
1146 </div>
1147 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1148 <div class="directive-section"><h2><a name="SSLProxyMachineCertificateFile" id="SSLProxyMachineCertificateFile">SSLProxyMachineCertificateFile</a> <a name="sslproxymachinecertificatefile" id="sslproxymachinecertificatefile">Directive</a></h2>
1149 <table class="directive">
1150 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded client certificates and keys to be used by the proxy</td></tr>
1151 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificateFile <em>filename</em></code></td></tr>
1152 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1153 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Not applicable</td></tr>
1154 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1155 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1156 </table>
1157 <p>
1158 This directive sets the all-in-one file where you keep the certificates and
1159 keys used for authentication of the proxy server to remote servers.
1160 </p>
1161 <p>
1162 This referenced file is simply the concatenation of the various PEM-encoded
1163 certificate files, in order of preference. Use this directive alternatively
1164 or additionally to <code>SSLProxyMachineCertificatePath</code>.
1165 </p>
1166 <div class="warning">
1167 <p>Currently there is no support for encrypted private keys</p>
1168 </div>
1169 <div class="example"><h3>Example</h3><p><code>
1170 SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem
1171 </code></p></div>
1172
1173 </div>
1174 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1175 <div class="directive-section"><h2><a name="SSLProxyMachineCertificatePath" id="SSLProxyMachineCertificatePath">SSLProxyMachineCertificatePath</a> <a name="sslproxymachinecertificatepath" id="sslproxymachinecertificatepath">Directive</a></h2>
1176 <table class="directive">
1177 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded client certificates and keys to be used by the proxy</td></tr>
1178 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificatePath <em>directory</em></code></td></tr>
1179 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1180 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Not applicable</td></tr>
1181 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1182 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1183 </table>
1184 <p>
1185 This directive sets the directory where you keep the certificates and
1186 keys used for authentication of the proxy server to remote servers.
1187 </p>
1188 <p>The files in this directory must be PEM-encoded and are accessed through
1189 hash filenames. Additionally, you must create symbolic links named
1190 <code><em>hash-value</em>.N</code>. And you should always make sure this
1191 directory contains the appropriate symbolic links. Use the Makefile which
1192 comes with mod_ssl to accomplish this task.
1193 </p>
1194 <div class="warning">
1195 <p>Currently there is no support for encrypted private keys</p>
1196 </div>
1197 <div class="example"><h3>Example</h3><p><code>
1198 SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/
1199 </code></p></div>
1200
1201 </div>
1202 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1203 <div class="directive-section"><h2><a name="SSLProxyProtocol" id="SSLProxyProtocol">SSLProxyProtocol</a> <a name="sslproxyprotocol" id="sslproxyprotocol">Directive</a></h2>
1204 <table class="directive">
1205 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL protocol flavors for proxy usage</td></tr>
1206 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyProtocol [+|-]<em>protocol</em> ...</code></td></tr>
1207 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyProtocol all</code></td></tr>
1208 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1209 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
1210 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1211 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1212 </table>
1213
1214 <p>
1215 This directive can be used to control the SSL protocol flavors mod_ssl should
1216 use when establishing its server environment for proxy . It will only connect
1217 to servers using one of the provided protocols.</p>
1218 <p>Please refer to <code class="directive"><a href="#sslprotocol">SSLProtocol</a></code>
1219 for additional information.
1220 </p>
1221
1222 </div>
1223 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1224 <div class="directive-section"><h2><a name="SSLProxyVerify" id="SSLProxyVerify">SSLProxyVerify</a> <a name="sslproxyverify" id="sslproxyverify">Directive</a></h2>
1225 <table class="directive">
1226 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of remote server Certificate verification</td></tr>
1227 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerify <em>level</em></code></td></tr>
1228 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerify none</code></td></tr>
1229 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1230 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1231 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1232 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1233 </table>
1234
1235 <p>When a proxy is configured to forward requests to a remote SSL
1236 server, this directive can be used to configure certificate
1237 verification of the remote server.  Notice that this directive can be
1238 used both in per-server and per-directory context. In per-server
1239 context it applies to the remote server authentication process used in
1240 the standard SSL handshake when a connection is established by the
1241 proxy. In per-directory context it forces a SSL renegotation with the
1242 reconfigured remote server verification level after the HTTP request
1243 was read but before the HTTP response is sent.</p>
1244
1245 <p>
1246 The following levels are available for <em>level</em>:</p>
1247 <ul>
1248 <li><strong>none</strong>:
1249      no remote server Certificate is required at all</li>
1250 <li><strong>optional</strong>:
1251      the remote server <em>may</em> present a valid Certificate</li>
1252 <li><strong>require</strong>:
1253      the remote server <em>has to</em> present a valid Certificate</li>
1254 <li><strong>optional_no_ca</strong>:
1255      the remote server may present a valid Certificate<br />
1256      but it need not to be (successfully) verifiable.</li>
1257 </ul>
1258 <p>In practice only levels <strong>none</strong> and
1259 <strong>require</strong> are really interesting, because level
1260 <strong>optional</strong> doesn't work with all servers and level
1261 <strong>optional_no_ca</strong> is actually against the idea of
1262 authentication (but can be used to establish SSL test pages, etc.)</p>
1263 <div class="example"><h3>Example</h3><p><code>
1264 SSLProxyVerify require
1265 </code></p></div>
1266
1267 </div>
1268 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1269 <div class="directive-section"><h2><a name="SSLProxyVerifyDepth" id="SSLProxyVerifyDepth">SSLProxyVerifyDepth</a> <a name="sslproxyverifydepth" id="sslproxyverifydepth">Directive</a></h2>
1270 <table class="directive">
1271 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Remote Server
1272 Certificate verification</td></tr>
1273 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerifyDepth <em>number</em></code></td></tr>
1274 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerifyDepth 1</code></td></tr>
1275 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1276 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1277 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1278 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1279 </table>
1280 <p>
1281 This directive sets how deeply mod_ssl should verify before deciding that the
1282 remote server does not have a valid certificate. Notice that this directive can be
1283 used both in per-server and per-directory context. In per-server context it
1284 applies to the client authentication process used in the standard SSL
1285 handshake when a connection is established. In per-directory context it forces
1286 a SSL renegotation with the reconfigured remote server verification depth after the
1287 HTTP request was read but before the HTTP response is sent.</p>
1288 <p>
1289 The depth actually is the maximum number of intermediate certificate issuers,
1290 i.e. the number of CA certificates which are max allowed to be followed while
1291 verifying the remote server certificate. A depth of 0 means that self-signed
1292 remote server certificates are accepted only, the default depth of 1 means
1293 the remote server certificate can be self-signed or has to be signed by a CA
1294 which is directly known to the server (i.e. the CA's certificate is under
1295 <code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>), etc.</p>
1296 <div class="example"><h3>Example</h3><p><code>
1297 SSLProxyVerifyDepth 10
1298 </code></p></div>
1299
1300 </div>
1301 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1302 <div class="directive-section"><h2><a name="SSLRandomSeed" id="SSLRandomSeed">SSLRandomSeed</a> <a name="sslrandomseed" id="sslrandomseed">Directive</a></h2>
1303 <table class="directive">
1304 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pseudo Random Number Generator (PRNG) seeding
1305 source</td></tr>
1306 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRandomSeed <em>context</em> <em>source</em>
1307 [<em>bytes</em>]</code></td></tr>
1308 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1309 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1310 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1311 </table>
1312 <p>
1313 This configures one or more sources for seeding the Pseudo Random Number
1314 Generator (PRNG) in OpenSSL at startup time (<em>context</em> is
1315 <code>startup</code>) and/or just before a new SSL connection is established
1316 (<em>context</em> is <code>connect</code>). This directive can only be used
1317 in the global server context because the PRNG is a global facility.</p>
1318 <p>
1319 The following <em>source</em> variants are available:</p>
1320 <ul>
1321 <li><code>builtin</code>
1322     <p> This is the always available builtin seeding source. It's usage
1323     consumes minimum CPU cycles under runtime and hence can be always used
1324     without drawbacks. The source used for seeding the PRNG contains of the
1325     current time, the current process id and (when applicable) a randomly
1326     choosen 1KB extract of the inter-process scoreboard structure of Apache.
1327     The drawback is that this is not really a strong source and at startup
1328     time (where the scoreboard is still not available) this source just
1329     produces a few bytes of entropy. So you should always, at least for the
1330     startup, use an additional seeding source.</p></li>
1331 <li><code>file:/path/to/source</code>
1332     <p>
1333     This variant uses an external file <code>/path/to/source</code> as the
1334     source for seeding the PRNG. When <em>bytes</em> is specified, only the
1335     first <em>bytes</em> number of bytes of the file form the entropy (and
1336     <em>bytes</em> is given to <code>/path/to/source</code> as the first
1337     argument). When <em>bytes</em> is not specified the whole file forms the
1338     entropy (and <code>0</code> is given to <code>/path/to/source</code> as
1339     the first argument). Use this especially at startup time, for instance
1340     with an available <code>/dev/random</code> and/or
1341     <code>/dev/urandom</code> devices (which usually exist on modern Unix
1342     derivates like FreeBSD and Linux).</p>
1343     <p>
1344     <em>But be careful</em>: Usually <code>/dev/random</code> provides only as
1345     much entropy data as it actually has, i.e. when you request 512 bytes of
1346     entropy, but the device currently has only 100 bytes available two things
1347     can happen: On some platforms you receive only the 100 bytes while on
1348     other platforms the read blocks until enough bytes are available (which
1349     can take a long time). Here using an existing <code>/dev/urandom</code> is
1350     better, because it never blocks and actually gives the amount of requested
1351     data. The drawback is just that the quality of the received data may not
1352     be the best.</p>
1353     <p>
1354     On some platforms like FreeBSD one can even control how the entropy is
1355     actually generated, i.e. by which system interrupts. More details one can
1356     find under <em>rndcontrol(8)</em> on those platforms. Alternatively, when
1357     your system lacks such a random device, you can use tool
1358     like <a href="http://www.lothar.com/tech/crypto/">EGD</a>
1359     (Entropy Gathering Daemon) and run it's client program with the
1360     <code>exec:/path/to/program/</code> variant (see below) or use
1361     <code>egd:/path/to/egd-socket</code> (see below).</p></li>
1362
1363 <li><code>exec:/path/to/program</code>
1364     <p>
1365     This variant uses an external executable
1366     <code>/path/to/program</code> as the source for seeding the
1367     PRNG. When <em>bytes</em> is specified, only the first
1368     <em>bytes</em> number of bytes of its <code>stdout</code> contents
1369     form the entropy. When <em>bytes</em> is not specified, the
1370     entirety of the data produced on <code>stdout</code> form the
1371     entropy. Use this only at startup time when you need a very strong
1372     seeding with the help of an external program (for instance as in
1373     the example above with the <code>truerand</code> utility you can
1374     find in the mod_ssl distribution which is based on the AT&amp;T
1375     <em>truerand</em> library). Using this in the connection context
1376     slows down the server too dramatically, of course.  So usually you
1377     should avoid using external programs in that context.</p></li>
1378 <li><code>egd:/path/to/egd-socket</code> (Unix only)
1379     <p>
1380     This variant uses the Unix domain socket of the
1381     external Entropy Gathering Daemon (EGD) (see <a href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech
1382     /crypto/</a>) to seed the PRNG. Use this if no random device exists
1383     on your platform.</p></li>
1384 </ul>
1385 <div class="example"><h3>Example</h3><p><code>
1386 SSLRandomSeed startup builtin<br />
1387 SSLRandomSeed startup file:/dev/random<br />
1388 SSLRandomSeed startup file:/dev/urandom 1024<br />
1389 SSLRandomSeed startup exec:/usr/local/bin/truerand 16<br />
1390 SSLRandomSeed connect builtin<br />
1391 SSLRandomSeed connect file:/dev/random<br />
1392 SSLRandomSeed connect file:/dev/urandom 1024<br />
1393 </code></p></div>
1394
1395 </div>
1396 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1397 <div class="directive-section"><h2><a name="SSLRenegBufferSize" id="SSLRenegBufferSize">SSLRenegBufferSize</a> <a name="sslrenegbuffersize" id="sslrenegbuffersize">Directive</a></h2>
1398 <table class="directive">
1399 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the size for the SSL renegotiation buffer</td></tr>
1400 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRenegBufferSize <var>bytes</var></code></td></tr>
1401 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLRenegBufferSize 131072</code></td></tr>
1402 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
1403 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1404 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1405 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1406 </table>
1407
1408 <p>If an SSL renegotiation is required in per-location context, for
1409 example, any use of <code class="directive"><a href="#sslverifyclient">SSLVerifyClient</a></code> in a Directory or
1410 Location block, then <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> must buffer any HTTP
1411 request body into memory until the new SSL handshake can be performed.
1412 This directive can be used to set the amount of memory that will be
1413 used for this buffer. </p>
1414
1415 <div class="warning"><p>
1416 Note that in many configurations, the client sending the request body
1417 will be untrusted so a denial of service attack by consumption of
1418 memory must be considered when changing this configuration setting.
1419 </p></div>
1420
1421 <div class="example"><h3>Example</h3><p><code>
1422 SSLRenegBufferSize 262144
1423 </code></p></div>
1424
1425 </div>
1426 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1427 <div class="directive-section"><h2><a name="SSLRequire" id="SSLRequire">SSLRequire</a> <a name="sslrequire" id="sslrequire">Directive</a></h2>
1428 <table class="directive">
1429 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow access only when an arbitrarily complex
1430 boolean expression is true</td></tr>
1431 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequire <em>expression</em></code></td></tr>
1432 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
1433 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1434 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1435 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1436 </table>
1437 <p>
1438 This directive specifies a general access requirement which has to be
1439 fulfilled in order to allow access. It is a very powerful directive because the
1440 requirement specification is an arbitrarily complex boolean expression
1441 containing any number of access checks.</p>
1442 <div class="warning">
1443 <p>The implementation of <code>SSLRequire</code> is not thread safe.
1444    Using <code>SSLRequire</code> inside <code>.htaccess</code> files
1445    on a threaded <a href="../mpm.html">MPM</a> may cause random crashes.
1446 </p>
1447 </div>
1448 <p>
1449 The <em>expression</em> must match the following syntax (given as a BNF
1450 grammar notation):</p>
1451 <blockquote>
1452 <pre>
1453 expr     ::= "<strong>true</strong>" | "<strong>false</strong>"
1454            | "<strong>!</strong>" expr
1455            | expr "<strong>&amp;&amp;</strong>" expr
1456            | expr "<strong>||</strong>" expr
1457            | "<strong>(</strong>" expr "<strong>)</strong>"
1458            | comp
1459
1460 comp     ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word
1461            | word "<strong>!=</strong>" word | word "<strong>ne</strong>" word
1462            | word "<strong>&lt;</strong>"  word | word "<strong>lt</strong>" word
1463            | word "<strong>&lt;=</strong>" word | word "<strong>le</strong>" word
1464            | word "<strong>&gt;</strong>"  word | word "<strong>gt</strong>" word
1465            | word "<strong>&gt;=</strong>" word | word "<strong>ge</strong>" word
1466            | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>"
1467            | word "<strong>in</strong>" "<strong>PeerExtList(</strong>" word "<strong>)</strong>"
1468            | word "<strong>=~</strong>" regex
1469            | word "<strong>!~</strong>" regex
1470
1471 wordlist ::= word
1472            | wordlist "<strong>,</strong>" word
1473
1474 word     ::= digit
1475            | cstring
1476            | variable
1477            | function
1478
1479 digit    ::= [0-9]+
1480 cstring  ::= "..."
1481 variable ::= "<strong>%{</strong>" varname "<strong>}</strong>"
1482 function ::= funcname "<strong>(</strong>" funcargs "<strong>)</strong>"
1483 </pre>
1484 </blockquote>
1485 <p>while for <code>varname</code> any variable from <a href="#table3">Table 3</a> can be used. Finally for
1486 <code>funcname</code> the following functions are available:</p>
1487 <ul>
1488 <li><code>file(</code><em>filename</em><code>)</code>
1489     <p>
1490     This function takes one string argument and expands to the contents of the
1491     file. This is especially useful for matching this contents against a
1492     regular expression, etc.</p>
1493 </li>
1494 </ul>
1495 <p>Notice that <em>expression</em> is first parsed into an internal machine
1496 representation and then evaluated in a second step. Actually, in Global and
1497 Per-Server Class context <em>expression</em> is parsed at startup time and
1498 at runtime only the machine representation is executed. For Per-Directory
1499 context this is different: here <em>expression</em> has to be parsed and
1500 immediately executed for every request.</p>
1501 <div class="example"><h3>Example</h3><p><code>
1502 SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \<br />
1503             and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \<br />
1504             and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \<br />
1505             and %{TIME_WDAY} &gt;= 1 and %{TIME_WDAY} &lt;= 5 \<br />
1506             and %{TIME_HOUR} &gt;= 8 and %{TIME_HOUR} &lt;= 20       ) \<br />
1507            or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
1508 </code></p></div>
1509 <p>The <code>PeerExtList(<em>object id</em>)</code> function expects to find
1510 zero or more instances of the X.509 Certificate Extension (as identified by
1511 the given <em>object id</em>) in the client certificate, and compares the
1512 left-hand side string against the value of any matching attribute value. Every
1513 extension with the specified object id is checked, until a match is found.
1514 </p>
1515
1516 <p><em>Standard CGI/1.0 and Apache variables:</em></p>
1517 <pre>
1518 HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
1519 HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
1520 HTTP_COOKIE            REMOTE_HOST           API_VERSION
1521 HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
1522 HTTP_HOST              IS_SUBREQ             TIME_MON
1523 HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
1524 HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
1525 HTTP:headername        SERVER_NAME           TIME_MIN
1526 THE_REQUEST            SERVER_PORT           TIME_SEC
1527 REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
1528 REQUEST_SCHEME         REMOTE_ADDR           TIME
1529 REQUEST_URI            REMOTE_USER           ENV:<strong>variablename</strong>
1530 REQUEST_FILENAME
1531 </pre>
1532 <p><em>SSL-related variables:</em></p>
1533 <pre>
1534 HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
1535                        SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL
1536 SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START
1537 SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END
1538 SSL_SESSION_RESUMED    SSL_CLIENT_S_DN        SSL_SERVER_S_DN
1539 SSL_CIPHER             SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C
1540 SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST
1541 SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L
1542 SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O
1543 SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU
1544 SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN
1545                        SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T
1546                        SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I
1547                        SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G
1548                        SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S
1549                        SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D
1550                        SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID
1551                        SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
1552                        SSL_CLIENT_I_DN        SSL_SERVER_I_DN
1553                        SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C
1554                        SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST
1555                        SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L
1556                        SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O
1557                        SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU
1558                        SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN
1559                        SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T
1560                        SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I
1561                        SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G
1562                        SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S
1563                        SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D
1564                        SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID
1565                        SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
1566                        SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG
1567                        SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY
1568                        SSL_CLIENT_CERT        SSL_SERVER_CERT
1569                        SSL_CLIENT_CERT_CHAIN_<strong>n</strong>
1570                        SSL_CLIENT_VERIFY
1571 </pre>
1572
1573 </div>
1574 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1575 <div class="directive-section"><h2><a name="SSLRequireSSL" id="SSLRequireSSL">SSLRequireSSL</a> <a name="sslrequiressl" id="sslrequiressl">Directive</a></h2>
1576 <table class="directive">
1577 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deny access when SSL is not used for the
1578 HTTP request</td></tr>
1579 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequireSSL</code></td></tr>
1580 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
1581 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1582 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1583 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1584 </table>
1585 <p>
1586 This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for
1587 the current connection. This is very handy inside the SSL-enabled virtual
1588 host or directories for defending against configuration errors that expose
1589 stuff that should be protected. When this directive is present all requests
1590 are denied which are not using SSL.</p>
1591 <div class="example"><h3>Example</h3><p><code>
1592 SSLRequireSSL
1593 </code></p></div>
1594
1595 </div>
1596 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1597 <div class="directive-section"><h2><a name="SSLSessionCache" id="SSLSessionCache">SSLSessionCache</a> <a name="sslsessioncache" id="sslsessioncache">Directive</a></h2>
1598 <table class="directive">
1599 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of the global/inter-process SSL Session
1600 Cache</td></tr>
1601 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCache <em>type</em></code></td></tr>
1602 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCache none</code></td></tr>
1603 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
1604 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1605 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1606 </table>
1607 <p>
1608 This configures the storage type of the global/inter-process SSL Session
1609 Cache. This cache is an optional facility which speeds up parallel request
1610 processing. For requests to the same server process (via HTTP keep-alive),
1611 OpenSSL already caches the SSL session information locally. But because modern
1612 clients request inlined images and other data via parallel requests (usually
1613 up to four parallel requests are common) those requests are served by
1614 <em>different</em> pre-forked server processes. Here an inter-process cache
1615 helps to avoid unneccessary session handshakes.</p>
1616 <p>
1617 The following four storage <em>type</em>s are currently supported:</p>
1618 <ul>
1619 <li><code>none</code>
1620
1621     <p>This disables the global/inter-process Session Cache.  This
1622     will incur a noticeable speed penalty and may cause problems if
1623     using certain browsers, particularly if client certificates are
1624     enabled.  This setting is not recommended.</p></li>
1625
1626 <li><code>nonenotnull</code>
1627
1628     <p>This disables any global/inter-process Session Cache.  However
1629     it does force OpenSSL to send a non-null session ID to
1630     accommodate buggy clients that require one.</p></li>
1631
1632 <li><code>dbm:/path/to/datafile</code>
1633
1634     <p>This makes use of a DBM hashfile on the local disk to
1635     synchronize the local OpenSSL memory caches of the server
1636     processes.  This session cache may suffer reliability issues under
1637     high load.</p></li>
1638
1639 <li><code>shm:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>]
1640
1641     <p>This makes use of a high-performance cyclic buffer
1642     (approx. <em>size</em> bytes in size) inside a shared memory
1643     segment in RAM (established via <code>/path/to/datafile</code>) to
1644     synchronize the local OpenSSL memory caches of the server
1645     processes.  This is the recommended session cache.</p></li>
1646
1647 <li><code>dc:UNIX:/path/to/socket</code>
1648
1649     <p>This makes use of the <a href="http://www.distcache.org/">distcache</a> distributed session
1650     caching libraries.  The argument should specify the location of
1651     the server or proxy to be used using the distcache address syntax;
1652     for example, <code>UNIX:/path/to/socket</code> specifies a UNIX
1653     domain socket (typically a local dc_client proxy);
1654     <code>IP:server.example.com:9001</code> specifies an IP
1655     address.</p></li>
1656
1657 </ul>
1658
1659 <div class="example"><h3>Examples</h3><p><code>
1660 SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data<br />
1661 SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
1662 </code></p></div>
1663
1664 <p>The <code>ssl-cache</code> mutex is used to serialize access to
1665 the session cache to prevent corruption.  This mutex can be configured
1666 using the <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
1667
1668 </div>
1669 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1670 <div class="directive-section"><h2><a name="SSLSessionCacheTimeout" id="SSLSessionCacheTimeout">SSLSessionCacheTimeout</a> <a name="sslsessioncachetimeout" id="sslsessioncachetimeout">Directive</a></h2>
1671 <table class="directive">
1672 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before an SSL session expires
1673 in the Session Cache</td></tr>
1674 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCacheTimeout <em>seconds</em></code></td></tr>
1675 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCacheTimeout 300</code></td></tr>
1676 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1677 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1678 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1679 </table>
1680 <p>
1681 This directive sets the timeout in seconds for the information stored in the
1682 global/inter-process SSL Session Cache and the OpenSSL internal memory cache.
1683 It can be set as low as 15 for testing, but should be set to higher
1684 values like 300 in real life.</p>
1685 <div class="example"><h3>Example</h3><p><code>
1686 SSLSessionCacheTimeout 600
1687 </code></p></div>
1688
1689 </div>
1690 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1691 <div class="directive-section"><h2><a name="SSLStrictSNIVHostCheck" id="SSLStrictSNIVHostCheck">SSLStrictSNIVHostCheck</a> <a name="sslstrictsnivhostcheck" id="sslstrictsnivhostcheck">Directive</a></h2>
1692 <table class="directive">
1693 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to allow non SNI clients to access a name based virtual
1694 host.
1695 </td></tr>
1696 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStrictSNIVHostCheck on|off</code></td></tr>
1697 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStrictSNIVHostCheck off</code></td></tr>
1698 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
1699 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1700 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1701 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.2.12 and later</td></tr>
1702 </table>
1703 <p>
1704 This directive sets whether a non SNI client is allowed to access a name based
1705 virtual host. If set to <code>on</code> in the non default name based virtual
1706 host, non SNI clients are not allowed to access this particular virtual host.
1707 If set to <code>on</code> in the default name based virtual host, non SNI
1708 clients are not allowed to access any name based virtual host belonging to
1709 this IP / port combination.
1710 </p>
1711
1712 <div class="warning"><p>
1713 This option is only available if httpd was compiled against an SNI capable
1714 version of OpenSSL.
1715 </p></div>
1716
1717 <div class="example"><h3>Example</h3><p><code>
1718 SSLStrictSNIVHostCheck on
1719 </code></p></div>
1720
1721 </div>
1722 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1723 <div class="directive-section"><h2><a name="SSLUserName" id="SSLUserName">SSLUserName</a> <a name="sslusername" id="sslusername">Directive</a></h2>
1724 <table class="directive">
1725 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Variable name to determine user name</td></tr>
1726 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLUserName <em>varname</em></code></td></tr>
1727 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, directory, .htaccess</td></tr>
1728 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1729 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1730 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1731 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.0.51 and later</td></tr>
1732 </table>
1733 <p>
1734 This directive sets the "user" field in the Apache request object.
1735 This is used by lower modules to identify the user with a character
1736 string. In particular, this may cause the environment variable
1737 <code>REMOTE_USER</code> to be set.  The <em>varname</em> can be
1738 any of the <a href="#envvars">SSL environment variables</a>.</p>
1739
1740 <p>Note that this directive has no effect if the
1741 <code>FakeBasic</code> option is used (see <a href="#ssloptions">SSLOptions</a>).</p>
1742
1743 <div class="example"><h3>Example</h3><p><code>
1744 SSLUserName SSL_CLIENT_S_DN_CN
1745 </code></p></div>
1746
1747 </div>
1748 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1749 <div class="directive-section"><h2><a name="SSLVerifyClient" id="SSLVerifyClient">SSLVerifyClient</a> <a name="sslverifyclient" id="sslverifyclient">Directive</a></h2>
1750 <table class="directive">
1751 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of Client Certificate verification</td></tr>
1752 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyClient <em>level</em></code></td></tr>
1753 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyClient none</code></td></tr>
1754 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1755 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1756 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1757 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1758 </table>
1759 <p>
1760 This directive sets the Certificate verification level for the Client
1761 Authentication. Notice that this directive can be used both in per-server and
1762 per-directory context. In per-server context it applies to the client
1763 authentication process used in the standard SSL handshake when a connection is
1764 established. In per-directory context it forces a SSL renegotation with the
1765 reconfigured client verification level after the HTTP request was read but
1766 before the HTTP response is sent.</p>
1767 <p>
1768 The following levels are available for <em>level</em>:</p>
1769 <ul>
1770 <li><strong>none</strong>:
1771      no client Certificate is required at all</li>
1772 <li><strong>optional</strong>:
1773      the client <em>may</em> present a valid Certificate</li>
1774 <li><strong>require</strong>:
1775      the client <em>has to</em> present a valid Certificate</li>
1776 <li><strong>optional_no_ca</strong>:
1777      the client may present a valid Certificate<br />
1778      but it need not to be (successfully) verifiable.</li>
1779 </ul>
1780 <p>In practice only levels <strong>none</strong> and
1781 <strong>require</strong> are really interesting, because level
1782 <strong>optional</strong> doesn't work with all browsers and level
1783 <strong>optional_no_ca</strong> is actually against the idea of
1784 authentication (but can be used to establish SSL test pages, etc.)</p>
1785 <div class="example"><h3>Example</h3><p><code>
1786 SSLVerifyClient require
1787 </code></p></div>
1788
1789 </div>
1790 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1791 <div class="directive-section"><h2><a name="SSLVerifyDepth" id="SSLVerifyDepth">SSLVerifyDepth</a> <a name="sslverifydepth" id="sslverifydepth">Directive</a></h2>
1792 <table class="directive">
1793 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Client
1794 Certificate verification</td></tr>
1795 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyDepth <em>number</em></code></td></tr>
1796 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyDepth 1</code></td></tr>
1797 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1798 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
1799 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
1800 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr>
1801 </table>
1802 <p>
1803 This directive sets how deeply mod_ssl should verify before deciding that the
1804 clients don't have a valid certificate. Notice that this directive can be
1805 used both in per-server and per-directory context. In per-server context it
1806 applies to the client authentication process used in the standard SSL
1807 handshake when a connection is established. In per-directory context it forces
1808 a SSL renegotation with the reconfigured client verification depth after the
1809 HTTP request was read but before the HTTP response is sent.</p>
1810 <p>
1811 The depth actually is the maximum number of intermediate certificate issuers,
1812 i.e. the number of CA certificates which are max allowed to be followed while
1813 verifying the client certificate. A depth of 0 means that self-signed client
1814 certificates are accepted only, the default depth of 1 means the client
1815 certificate can be self-signed or has to be signed by a CA which is directly
1816 known to the server (i.e. the CA's certificate is under
1817 <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>), etc.</p>
1818 <div class="example"><h3>Example</h3><p><code>
1819 SSLVerifyDepth 10
1820 </code></p></div>
1821
1822 </div>
1823 </div>
1824 <div class="bottomlang">
1825 <p><span>Available Languages: </span><a href="../en/mod/mod_ssl.html" title="English">&nbsp;en&nbsp;</a></p>
1826 </div><div id="footer">
1827 <p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
1828 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
1829 </body></html>