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

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