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