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