1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_ssl - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_ssl</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_ssl.html" title="English"> en </a> | 28<a href="/fr/mod/mod_ssl.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 29</div> 30<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Strong cryptography using the Secure Sockets 31Layer (SSL) and Transport Layer Security (TLS) protocols</td></tr> 32<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 33<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>ssl_module</td></tr> 34<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_ssl.c</td></tr></table> 35<h3>Summary</h3> 36 37<p>This module provides SSL v3 and TLS v1.x support for the Apache 38HTTP Server. SSL v2 is no longer supported.</p> 39 40<p>This module relies on <a href="http://www.openssl.org/">OpenSSL</a> 41to provide the cryptography engine.</p> 42 43<p>Further details, discussion, and examples are provided in the 44<a href="/ssl/">SSL documentation</a>.</p> 45</div> 46<div id="quickview"><h3 class="directives">Directives</h3> 47<ul id="toc"> 48<li><img alt="" src="/images/down.gif" /> <a href="#sslcacertificatefile">SSLCACertificateFile</a></li> 49<li><img alt="" src="/images/down.gif" /> <a href="#sslcacertificatepath">SSLCACertificatePath</a></li> 50<li><img alt="" src="/images/down.gif" /> <a href="#sslcadnrequestfile">SSLCADNRequestFile</a></li> 51<li><img alt="" src="/images/down.gif" /> <a href="#sslcadnrequestpath">SSLCADNRequestPath</a></li> 52<li><img alt="" src="/images/down.gif" /> <a href="#sslcarevocationcheck">SSLCARevocationCheck</a></li> 53<li><img alt="" src="/images/down.gif" /> <a href="#sslcarevocationfile">SSLCARevocationFile</a></li> 54<li><img alt="" src="/images/down.gif" /> <a href="#sslcarevocationpath">SSLCARevocationPath</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#sslcertificatechainfile">SSLCertificateChainFile</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#sslcertificatefile">SSLCertificateFile</a></li> 57<li><img alt="" src="/images/down.gif" /> <a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></li> 58<li><img alt="" src="/images/down.gif" /> <a href="#sslciphersuite">SSLCipherSuite</a></li> 59<li><img alt="" src="/images/down.gif" /> <a href="#sslcompression">SSLCompression</a></li> 60<li><img alt="" src="/images/down.gif" /> <a href="#sslcryptodevice">SSLCryptoDevice</a></li> 61<li><img alt="" src="/images/down.gif" /> <a href="#sslengine">SSLEngine</a></li> 62<li><img alt="" src="/images/down.gif" /> <a href="#sslfips">SSLFIPS</a></li> 63<li><img alt="" src="/images/down.gif" /> <a href="#sslhonorcipherorder">SSLHonorCipherOrder</a></li> 64<li><img alt="" src="/images/down.gif" /> <a href="#sslinsecurerenegotiation">SSLInsecureRenegotiation</a></li> 65<li><img alt="" src="/images/down.gif" /> <a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></li> 66<li><img alt="" src="/images/down.gif" /> <a href="#sslocspenable">SSLOCSPEnable</a></li> 67<li><img alt="" src="/images/down.gif" /> <a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></li> 68<li><img alt="" src="/images/down.gif" /> <a href="#sslocsprespondertimeout">SSLOCSPResponderTimeout</a></li> 69<li><img alt="" src="/images/down.gif" /> <a href="#sslocspresponsemaxage">SSLOCSPResponseMaxAge</a></li> 70<li><img alt="" src="/images/down.gif" /> <a href="#sslocspresponsetimeskew">SSLOCSPResponseTimeSkew</a></li> 71<li><img alt="" src="/images/down.gif" /> <a href="#sslopensslconfcmd">SSLOpenSSLConfCmd</a></li> 72<li><img alt="" src="/images/down.gif" /> <a href="#ssloptions">SSLOptions</a></li> 73<li><img alt="" src="/images/down.gif" /> <a href="#sslpassphrasedialog">SSLPassPhraseDialog</a></li> 74<li><img alt="" src="/images/down.gif" /> <a href="#sslprotocol">SSLProtocol</a></li> 75<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycacertificatefile">SSLProxyCACertificateFile</a></li> 76<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></li> 77<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycarevocationcheck">SSLProxyCARevocationCheck</a></li> 78<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></li> 79<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></li> 80<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></li> 81<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire</a></li> 82<li><img alt="" src="/images/down.gif" /> <a href="#sslproxycheckpeername">SSLProxyCheckPeerName</a></li> 83<li><img alt="" src="/images/down.gif" /> <a href="#sslproxyciphersuite">SSLProxyCipherSuite</a></li> 84<li><img alt="" src="/images/down.gif" /> <a href="#sslproxyengine">SSLProxyEngine</a></li> 85<li><img alt="" src="/images/down.gif" /> <a href="#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile</a></li> 86<li><img alt="" src="/images/down.gif" /> <a href="#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile</a></li> 87<li><img alt="" src="/images/down.gif" /> <a href="#sslproxymachinecertificatepath">SSLProxyMachineCertificatePath</a></li> 88<li><img alt="" src="/images/down.gif" /> <a href="#sslproxyprotocol">SSLProxyProtocol</a></li> 89<li><img alt="" src="/images/down.gif" /> <a href="#sslproxyverify">SSLProxyVerify</a></li> 90<li><img alt="" src="/images/down.gif" /> <a href="#sslproxyverifydepth">SSLProxyVerifyDepth</a></li> 91<li><img alt="" src="/images/down.gif" /> <a href="#sslrandomseed">SSLRandomSeed</a></li> 92<li><img alt="" src="/images/down.gif" /> <a href="#sslrenegbuffersize">SSLRenegBufferSize</a></li> 93<li><img alt="" src="/images/down.gif" /> <a href="#sslrequire">SSLRequire</a></li> 94<li><img alt="" src="/images/down.gif" /> <a href="#sslrequiressl">SSLRequireSSL</a></li> 95<li><img alt="" src="/images/down.gif" /> <a href="#sslsessioncache">SSLSessionCache</a></li> 96<li><img alt="" src="/images/down.gif" /> <a href="#sslsessioncachetimeout">SSLSessionCacheTimeout</a></li> 97<li><img alt="" src="/images/down.gif" /> <a href="#sslsessionticketkeyfile">SSLSessionTicketKeyFile</a></li> 98<li><img alt="" src="/images/down.gif" /> <a href="#sslsrpunknownuserseed">SSLSRPUnknownUserSeed</a></li> 99<li><img alt="" src="/images/down.gif" /> <a href="#sslsrpverifierfile">SSLSRPVerifierFile</a></li> 100<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingcache">SSLStaplingCache</a></li> 101<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout</a></li> 102<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingfaketrylater">SSLStaplingFakeTryLater</a></li> 103<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingforceurl">SSLStaplingForceURL</a></li> 104<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingrespondertimeout">SSLStaplingResponderTimeout</a></li> 105<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingresponsemaxage">SSLStaplingResponseMaxAge</a></li> 106<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingresponsetimeskew">SSLStaplingResponseTimeSkew</a></li> 107<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors</a></li> 108<li><img alt="" src="/images/down.gif" /> <a href="#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout</a></li> 109<li><img alt="" src="/images/down.gif" /> <a href="#sslstrictsnivhostcheck">SSLStrictSNIVHostCheck</a></li> 110<li><img alt="" src="/images/down.gif" /> <a href="#sslusername">SSLUserName</a></li> 111<li><img alt="" src="/images/down.gif" /> <a href="#sslusestapling">SSLUseStapling</a></li> 112<li><img alt="" src="/images/down.gif" /> <a href="#sslverifyclient">SSLVerifyClient</a></li> 113<li><img alt="" src="/images/down.gif" /> <a href="#sslverifydepth">SSLVerifyDepth</a></li> 114</ul> 115<h3>Topics</h3> 116<ul id="topics"> 117<li><img alt="" src="/images/down.gif" /> <a href="#envvars">Environment Variables</a></li> 118<li><img alt="" src="/images/down.gif" /> <a href="#logformats">Custom Log Formats</a></li> 119<li><img alt="" src="/images/down.gif" /> <a href="#notes">Request Notes</a></li> 120<li><img alt="" src="/images/down.gif" /> <a href="#authzproviders">Authorization providers for use with Require</a></li> 121</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 122<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 123<div class="section"> 124<h2><a name="envvars" id="envvars">Environment Variables</a></h2> 125 126<p>This module can be configured to provide several items of SSL information 127as additional environment variables to the SSI and CGI namespace. This 128information is not provided by default for performance reasons. (See 129<code class="directive">SSLOptions</code> StdEnvVars, below.) The generated variables 130are listed in the table below. For backward compatibility the information can 131be made available under different names, too. Look in the <a href="/ssl/ssl_compat.html">Compatibility</a> chapter for details on the 132compatibility variables.</p> 133 134<table class="bordered"> 135 136<tr> 137 <th><a name="table3">Variable Name:</a></th> 138 <th>Value Type:</th> 139 <th>Description:</th> 140</tr> 141<tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> 142<tr><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2)</td></tr> 143<tr><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> 144<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> 145<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> 146<tr><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr> 147<tr><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> 148<tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> 149<tr><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> 150<tr><td><code>SSL_COMPRESS_METHOD</code></td> <td>string</td> <td>SSL compression method negotiated</td></tr> 151<tr><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> 152<tr><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> 153<tr><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> 154<tr><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> 155<tr><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> 156<tr><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr> 157<tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> 158<tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> 159<tr><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> 160<tr><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> 161<tr><td><code>SSL_CLIENT_V_REMAIN</code></td> <td>string</td> <td>Number of days until client's certificate expires</td></tr> 162<tr><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> 163<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> 164<tr><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> 165<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> 166<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> 167<tr><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> 168<tr><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> 169<tr><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> 170<tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr> 171<tr><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> 172<tr><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> 173<tr><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> 174<tr><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> 175<tr><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> 176<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> 177<tr><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> 178<tr><td><code>SSL_SRP_USER</code></td> <td>string</td> <td>SRP username</td></tr> 179<tr><td><code>SSL_SRP_USERINFO</code></td> <td>string</td> <td>SRP user info</td></tr> 180<tr><td><code>SSL_TLS_SNI</code></td> <td>string</td> <td>Contents of the SNI TLS extension (if supplied with ClientHello)</td></tr> 181</table> 182 183<p><em>x509</em> specifies a component of an X.509 DN; one of 184<code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>. In Apache 2.1 and 185later, <em>x509</em> may also include a numeric <code>_n</code> 186suffix. If the DN in question contains multiple attributes of the 187same name, this suffix is used as a zero-based index to select a 188particular attribute. For example, where the server certificate 189subject DN included two OU attributes, <code>SSL_SERVER_S_DN_OU_0</code> 190and 191<code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each. A 192variable name without a <code>_n</code> suffix is equivalent to that 193name with a <code>_0</code> suffix; the first (or only) attribute. 194When the environment table is populated using 195the <code>StdEnvVars</code> option of 196the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> directive, the 197first (or only) attribute of any DN is added only under a non-suffixed 198name; i.e. no <code>_0</code> suffixed entries are added.</p> 199 200<p>The format of the <em>*_DN</em> variables has changed in Apache HTTPD 2012.3.11. See the <code>LegacyDNStringFormat</code> option for 202<code class="directive"><a href="#ssloptions">SSLOptions</a></code> for details.</p> 203 204<p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1 205and later.</p> 206 207<p>A number of additional environment variables can also be used 208in <code class="directive">SSLRequire</code> expressions, or in custom log 209formats:</p> 210 211<div class="note"><pre>HTTP_USER_AGENT PATH_INFO AUTH_TYPE 212HTTP_REFERER QUERY_STRING SERVER_SOFTWARE 213HTTP_COOKIE REMOTE_HOST API_VERSION 214HTTP_FORWARDED REMOTE_IDENT TIME_YEAR 215HTTP_HOST IS_SUBREQ TIME_MON 216HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY 217HTTP_ACCEPT SERVER_ADMIN TIME_HOUR 218THE_REQUEST SERVER_NAME TIME_MIN 219REQUEST_FILENAME SERVER_PORT TIME_SEC 220REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY 221REQUEST_SCHEME REMOTE_ADDR TIME 222REQUEST_URI REMOTE_USER</pre></div> 223 224<p>In these contexts, two special formats can also be used:</p> 225 226<dl> 227 <dt><code>ENV:<em>variablename</em></code></dt> 228 <dd>This will expand to the standard environment 229 variable <em>variablename</em>.</dd> 230 231 <dt><code>HTTP:<em>headername</em></code></dt> 232 <dd>This will expand to the value of the request header with name 233 <em>headername</em>.</dd> 234</dl> 235 236</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 237<div class="section"> 238<h2><a name="logformats" id="logformats">Custom Log Formats</a></h2> 239 240<p>When <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least 241loaded (under DSO situation) additional functions exist for the <a href="mod_log_config.html#formats">Custom Log Format</a> of 242<code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code>. First there is an 243additional ``<code>%{</code><em>varname</em><code>}x</code>'' 244eXtension format function which can be used to expand any variables 245provided by any module, especially those provided by mod_ssl which can 246you find in the above table.</p> 247<p> 248For backward compatibility there is additionally a special 249``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function 250provided. Information about this function is provided in the <a href="/ssl/ssl_compat.html">Compatibility</a> chapter.</p> 251<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CustomLog logs/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"</pre> 252</div> 253</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 254<div class="section"> 255<h2><a name="notes" id="notes">Request Notes</a></h2> 256 257<p><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> sets "notes" for the request which can be 258used in logging with the <code>%{<em>name</em>}n</code> format 259string in <code class="module"><a href="/mod/mod_log_config.html">mod_log_config</a></code>.</p> 260 261<p>The notes supported are as follows:</p> 262 263<dl> 264 <dt><code>ssl-access-forbidden</code></dt> 265 <dd>This note is set to the value <code>1</code> if access was 266 denied due to an <code class="directive">SSLRequire</code> 267 or <code class="directive">SSLRequireSSL</code> directive.</dd> 268 269 <dt><code>ssl-secure-reneg</code></dt> 270 <dd>If <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is built against a version of 271 OpenSSL which supports the secure renegotiation extension, this note 272 is set to the value <code>1</code> if SSL is in used for the current 273 connection, and the client also supports the secure renegotiation 274 extension. If the client does not support the secure renegotiation 275 extension, the note is set to the value <code>0</code>. 276 If <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is not built against a version of 277 OpenSSL which supports secure renegotiation, or if SSL is not in use 278 for the current connection, the note is not set.</dd> 279</dl> 280 281</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 282<div class="section"> 283<h2><a name="authzproviders" id="authzproviders">Authorization providers for use with Require</a></h2> 284 285 <p><code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> provides a few authentication providers for use 286 with <code class="module"><a href="/mod/mod_authz_core.html">mod_authz_core</a></code>'s 287 <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> directive.</p> 288 289 <h3><a name="reqssl" id="reqssl">Require ssl</a></h3> 290 291 <p>The <code>ssl</code> provider denies access if a connection is not 292 encrypted with SSL. This is similar to the 293 <code class="directive">SSLRequireSSL</code> directive.</p> 294 295 <pre class="prettyprint lang-config">Require ssl</pre> 296 297 298 299 300 <h3><a name="reqverifyclient" id="reqverifyclient">Require ssl-verify-client</a></h3> 301 302 <p>The <code>ssl</code> provider allows access if the user is 303 authenticated with a valid client certificate. This is only 304 useful if <code>SSLVerifyClient optional</code> is in effect.</p> 305 306 <p>The following example grants access if the user is authenticated 307 either with a client certificate or by username and password.</p> 308 309 <pre class="prettyprint lang-config"> Require ssl-verify-client<br /> 310 Require valid-user</pre> 311 312 313 314 315</div> 316<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 317<div class="directive-section"><h2><a name="SSLCACertificateFile" id="SSLCACertificateFile">SSLCACertificateFile</a> <a name="sslcacertificatefile" id="sslcacertificatefile">Directive</a></h2> 318<table class="directive"> 319<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates 320for Client Auth</td></tr> 321<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificateFile <em>file-path</em></code></td></tr> 322<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 323<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 324<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 325</table> 326<p> 327This directive sets the <em>all-in-one</em> file where you can assemble the 328Certificates of Certification Authorities (CA) whose <em>clients</em> you deal 329with. These are used for Client Authentication. Such a file is simply the 330concatenation of the various PEM-encoded Certificate files, in order of 331preference. This can be used alternatively and/or additionally to 332<code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>.</p> 333<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt</pre> 334</div> 335 336</div> 337<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 338<div class="directive-section"><h2><a name="SSLCACertificatePath" id="SSLCACertificatePath">SSLCACertificatePath</a> <a name="sslcacertificatepath" id="sslcacertificatepath">Directive</a></h2> 339<table class="directive"> 340<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for 341Client Auth</td></tr> 342<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificatePath <em>directory-path</em></code></td></tr> 343<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 344<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 345<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 346</table> 347<p> 348This directive sets the directory where you keep the Certificates of 349Certification Authorities (CAs) whose clients you deal with. These are used to 350verify the client certificate on Client Authentication.</p> 351<p> 352The files in this directory have to be PEM-encoded and are accessed through 353hash filenames. So usually you can't just place the Certificate files 354there: you also have to create symbolic links named 355<em>hash-value</em><code>.N</code>. And you should always make sure this directory 356contains the appropriate symbolic links.</p> 357<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/</pre> 358</div> 359 360</div> 361<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 362<div class="directive-section"><h2><a name="SSLCADNRequestFile" id="SSLCADNRequestFile">SSLCADNRequestFile</a> <a name="sslcadnrequestfile" id="sslcadnrequestfile">Directive</a></h2> 363<table class="directive"> 364<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates 365for defining acceptable CA names</td></tr> 366<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestFile <em>file-path</em></code></td></tr> 367<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 368<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 369<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 370</table> 371<p>When a client certificate is requested by mod_ssl, a list of 372<em>acceptable Certificate Authority names</em> is sent to the client 373in the SSL handshake. These CA names can be used by the client to 374select an appropriate client certificate out of those it has 375available.</p> 376 377<p>If neither of the directives <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code> or <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> are given, then the 378set of acceptable CA names sent to the client is the names of all the 379CA certificates given by the <code class="directive"><a href="#sslcacertificatefile">SSLCACertificateFile</a></code> and <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> directives; in other 380words, the names of the CAs which will actually be used to verify the 381client certificate.</p> 382 383<p>In some circumstances, it is useful to be able to send a set of 384acceptable CA names which differs from the actual CAs used to verify 385the client certificate - for example, if the client certificates are 386signed by intermediate CAs. In such cases, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code> and/or <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> can be used; the 387acceptable CA names are then taken from the complete set of 388certificates in the directory and/or file specified by this pair of 389directives.</p> 390 391<p><code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> must 392specify an <em>all-in-one</em> file containing a concatenation of 393PEM-encoded CA certificates.</p> 394 395<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt</pre> 396</div> 397 398</div> 399<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 400<div class="directive-section"><h2><a name="SSLCADNRequestPath" id="SSLCADNRequestPath">SSLCADNRequestPath</a> <a name="sslcadnrequestpath" id="sslcadnrequestpath">Directive</a></h2> 401<table class="directive"> 402<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for 403defining acceptable CA names</td></tr> 404<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestPath <em>directory-path</em></code></td></tr> 405<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 406<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 407<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 408</table> 409 410<p>This optional directive can be used to specify the set of 411<em>acceptable CA names</em> which will be sent to the client when a 412client certificate is requested. See the <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> directive for more 413details.</p> 414 415<p>The files in this directory have to be PEM-encoded and are accessed 416through hash filenames. So usually you can't just place the 417Certificate files there: you also have to create symbolic links named 418<em>hash-value</em><code>.N</code>. And you should always make sure 419this directory contains the appropriate symbolic links.</p> 420<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCADNRequestPath /usr/local/apache2/conf/ca-names.crt/</pre> 421</div> 422 423</div> 424<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 425<div class="directive-section"><h2><a name="SSLCARevocationCheck" id="SSLCARevocationCheck">SSLCARevocationCheck</a> <a name="sslcarevocationcheck" id="sslcarevocationcheck">Directive</a></h2> 426<table class="directive"> 427<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable CRL-based revocation checking</td></tr> 428<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationCheck chain|leaf|none</code></td></tr> 429<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCARevocationCheck none</code></td></tr> 430<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 431<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 432<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 433</table> 434<p> 435Enables certificate revocation list (CRL) checking. At least one of 436<code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code> 437or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code> must be 438configured. When set to <code>chain</code> (recommended setting), 439CRL checks are applied to all certificates in the chain, while setting it to 440<code>leaf</code> limits the checks to the end-entity cert. 441</p> 442<div class="note"> 443<h3>When set to <code>chain</code> or <code>leaf</code>, 444CRLs <em>must</em> be available for successful validation</h3> 445<p> 446Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when 447no CRL(s) were found in any of the locations configured with 448<code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code> 449or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>. 450With the introduction of this directive, the behavior has been changed: 451when checking is enabled, CRLs <em>must</em> be present for the validation 452to succeed - otherwise it will fail with an 453<code>"unable to get certificate CRL"</code> error. 454</p> 455</div> 456<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationCheck chain</pre> 457</div> 458 459</div> 460<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 461<div class="directive-section"><h2><a name="SSLCARevocationFile" id="SSLCARevocationFile">SSLCARevocationFile</a> <a name="sslcarevocationfile" id="sslcarevocationfile">Directive</a></h2> 462<table class="directive"> 463<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for 464Client Auth</td></tr> 465<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationFile <em>file-path</em></code></td></tr> 466<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 467<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 468<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 469</table> 470<p> 471This directive sets the <em>all-in-one</em> file where you can 472assemble the Certificate Revocation Lists (CRL) of Certification 473Authorities (CA) whose <em>clients</em> you deal with. These are used 474for Client Authentication. Such a file is simply the concatenation of 475the various PEM-encoded CRL files, in order of preference. This can be 476used alternatively and/or additionally to <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>.</p> 477<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl</pre> 478</div> 479 480</div> 481<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 482<div class="directive-section"><h2><a name="SSLCARevocationPath" id="SSLCARevocationPath">SSLCARevocationPath</a> <a name="sslcarevocationpath" id="sslcarevocationpath">Directive</a></h2> 483<table class="directive"> 484<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for 485Client Auth</td></tr> 486<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationPath <em>directory-path</em></code></td></tr> 487<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 488<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 489<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 490</table> 491<p> 492This directive sets the directory where you keep the Certificate Revocation 493Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. 494These are used to revoke the client certificate on Client Authentication.</p> 495<p> 496The files in this directory have to be PEM-encoded and are accessed through 497hash filenames. So usually you have not only to place the CRL files there. 498Additionally you have to create symbolic links named 499<em>hash-value</em><code>.rN</code>. And you should always make sure this directory 500contains the appropriate symbolic links.</p> 501<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/</pre> 502</div> 503 504</div> 505<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 506<div class="directive-section"><h2><a name="SSLCertificateChainFile" id="SSLCertificateChainFile">SSLCertificateChainFile</a> <a name="sslcertificatechainfile" id="sslcertificatechainfile">Directive</a></h2> 507<table class="directive"> 508<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of PEM-encoded Server CA Certificates</td></tr> 509<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateChainFile <em>file-path</em></code></td></tr> 510<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 511<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 512<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 513</table> 514<div class="note"><h3>SSLCertificateChainFile is deprecated</h3> 515<p><code>SSLCertificateChainFile</code> became obsolete with version 2.4.8, 516when <code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code> 517was extended to also load intermediate CA certificates from the server 518certificate file.</p> 519</div> 520 521<p> 522This directive sets the optional <em>all-in-one</em> file where you can 523assemble the certificates of Certification Authorities (CA) which form the 524certificate chain of the server certificate. This starts with the issuing CA 525certificate of the server certificate and can range up to the root CA 526certificate. Such a file is simply the concatenation of the various 527PEM-encoded CA Certificate files, usually in certificate chain order.</p> 528<p> 529This should be used alternatively and/or additionally to <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> for explicitly 530constructing the server certificate chain which is sent to the browser 531in addition to the server certificate. It is especially useful to 532avoid conflicts with CA certificates when using client 533authentication. Because although placing a CA certificate of the 534server certificate chain into <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> has the same effect 535for the certificate chain construction, it has the side-effect that 536client certificates issued by this same CA certificate are also 537accepted on client authentication.</p> 538<p> 539But be careful: Providing the certificate chain works only if you are using a 540<em>single</em> RSA <em>or</em> DSA based server certificate. If you are 541using a coupled RSA+DSA certificate pair, this will work only if actually both 542certificates use the <em>same</em> certificate chain. Else the browsers will be 543confused in this situation.</p> 544<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt</pre> 545</div> 546 547</div> 548<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 549<div class="directive-section"><h2><a name="SSLCertificateFile" id="SSLCertificateFile">SSLCertificateFile</a> <a name="sslcertificatefile" id="sslcertificatefile">Directive</a></h2> 550<table class="directive"> 551<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded X.509 certificate data file</td></tr> 552<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateFile <em>file-path</em></code></td></tr> 553<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 554<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 555<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 556</table> 557<p> 558This directive points to a file with certificate data in PEM format. 559At a minimum, the file must include an end-entity (leaf) certificate. 560Beginning with version 2.4.8, it may also include intermediate CA 561certificates, sorted from leaf to root, and obsoletes 562<code class="directive"><a href="#sslcertificatechainfile">SSLCertificateChainFile</a></code>. 563</p> 564 565<p> 566Additional optional elements are DH parameters and/or an EC curve name 567for ephemeral keys, as generated by <code>openssl dhparam</code> and 568<code>openssl ecparam</code>, respectively (supported in version 2.4.7 569or later) and finally, the end-entity certificate's private key. 570If the private key is encrypted, the pass phrase dialog is forced 571at startup time.</p> 572 573<p> 574This directive can be used multiple times (referencing different filenames) 575to support multiple algorithms for server authentication - typically 576RSA, DSA, and ECC. The number of supported algorithms depends on the 577OpenSSL version being used for mod_ssl: with version 1.0.0 or later, 578<code>openssl list-public-key-algorithms</code> will output a list 579of supported algorithms.</p> 580 581<p> 582When running with OpenSSL 1.0.2 or later, this directive allows 583to configure the intermediate CA chain on a per-certificate basis, 584which removes a limitation of the (now obsolete) 585<code class="directive"><a href="#sslcertificatechainfile">SSLCertificateChainFile</a></code> directive. 586DH and ECDH parameters, however, are only read from the first 587<code class="directive">SSLCertificateFile</code> directive, as they 588are applied independently of the authentication algorithm type.</p> 589 590<div class="note"> 591<h3>DH parameter interoperability with primes > 1024 bit</h3> 592<p> 593Beginning with version 2.4.7, mod_ssl makes use of 594standardized DH parameters with prime lengths of 2048, 3072 and 4096 bits 595(from <a href="http://www.ietf.org/rfc/rfc3526.txt">RFC 3526</a>), and hands 596them out to clients based on the length of the certificate's RSA/DSA key. 597With Java-based clients in particular (Java 7 or earlier), this may lead 598to handshake failures - see this 599<a href="/ssl/ssl_faq.html#javadh">FAQ answer</a> for working around 600such issues. 601</p> 602</div> 603 604<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt</pre> 605</div> 606 607</div> 608<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 609<div class="directive-section"><h2><a name="SSLCertificateKeyFile" id="SSLCertificateKeyFile">SSLCertificateKeyFile</a> <a name="sslcertificatekeyfile" id="sslcertificatekeyfile">Directive</a></h2> 610<table class="directive"> 611<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded private key file</td></tr> 612<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateKeyFile <em>file-path</em></code></td></tr> 613<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 614<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 615<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 616</table> 617<p> 618This directive points to the PEM-encoded private key file for the 619server (the private key may also be combined with the certificate in the 620<code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code>, but this practice 621is discouraged). If the contained private key is encrypted, the pass phrase 622dialog is forced at startup time.</p> 623 624<p> 625The directive can be used multiple times (referencing different filenames) 626to support multiple algorithms for server authentication. For each 627<code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code> 628directive, there must be a matching <code class="directive">SSLCertificateFile</code> 629directive.</p> 630 631<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key</pre> 632</div> 633 634</div> 635<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 636<div class="directive-section"><h2><a name="SSLCipherSuite" id="SSLCipherSuite">SSLCipherSuite</a> <a name="sslciphersuite" id="sslciphersuite">Directive</a></h2> 637<table class="directive"> 638<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL 639handshake</td></tr> 640<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCipherSuite <em>cipher-spec</em></code></td></tr> 641<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCipherSuite DEFAULT (depends on OpenSSL version)</code></td></tr> 642<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 643<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 644<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 645<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 646</table> 647<p> 648This complex directive uses a colon-separated <em>cipher-spec</em> string 649consisting of OpenSSL cipher specifications to configure the Cipher Suite the 650client is permitted to negotiate in the SSL handshake phase. Notice that this 651directive can be used both in per-server and per-directory context. In 652per-server context it applies to the standard SSL handshake when a connection 653is established. In per-directory context it forces a SSL renegotiation with the 654reconfigured Cipher Suite after the HTTP request was read but before the HTTP 655response is sent.</p> 656<p> 657An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major 658attributes plus a few extra minor ones:</p> 659<ul> 660<li><em>Key Exchange Algorithm</em>:<br /> 661 RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password 662</li> 663<li><em>Authentication Algorithm</em>:<br /> 664 RSA, Diffie-Hellman, DSS, ECDSA, or none. 665</li> 666<li><em>Cipher/Encryption Algorithm</em>:<br /> 667 AES, DES, Triple-DES, RC4, RC2, IDEA, etc. 668</li> 669<li><em>MAC Digest Algorithm</em>:<br /> 670 MD5, SHA or SHA1, SHA256, SHA384. 671</li> 672</ul> 673<p>An SSL cipher can also be an export cipher. SSLv2 ciphers are no longer 674supported. To specify which ciphers to use, one can either specify all the 675Ciphers, one at a time, or use aliases to specify the preference and order 676for the ciphers (see <a href="#table1">Table 6771</a>). The actually available ciphers and aliases depends on the used 678openssl version. Newer openssl versions may include additional ciphers.</p> 679 680<table class="bordered"> 681 682<tr><th><a name="table1">Tag</a></th> <th>Description</th></tr> 683<tr><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> 684<tr><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> 685<tr><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> 686<tr><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> 687<tr><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> 688<tr><td><code>kSRP</code></td> <td>Secure Remote Password (SRP) key exchange</td></tr> 689<tr><td colspan="2"><em>Authentication Algorithm:</em></td></tr> 690<tr><td><code>aNULL</code></td> <td>No authentication</td></tr> 691<tr><td><code>aRSA</code></td> <td>RSA authentication</td></tr> 692<tr><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> 693<tr><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> 694<tr><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr> 695<tr><td><code>eNULL</code></td> <td>No encryption</td> </tr> 696<tr><td><code>NULL</code></td> <td>alias for eNULL</td> </tr> 697<tr><td><code>AES</code></td> <td>AES encryption</td> </tr> 698<tr><td><code>DES</code></td> <td>DES encryption</td> </tr> 699<tr><td><code>3DES</code></td> <td>Triple-DES encryption</td> </tr> 700<tr><td><code>RC4</code></td> <td>RC4 encryption</td> </tr> 701<tr><td><code>RC2</code></td> <td>RC2 encryption</td> </tr> 702<tr><td><code>IDEA</code></td> <td>IDEA encryption</td> </tr> 703<tr><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> 704<tr><td><code>MD5</code></td> <td>MD5 hash function</td></tr> 705<tr><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> 706<tr><td><code>SHA</code></td> <td>alias for SHA1</td> </tr> 707<tr><td><code>SHA256</code></td> <td>SHA256 hash function</td> </tr> 708<tr><td><code>SHA384</code></td> <td>SHA384 hash function</td> </tr> 709<tr><td colspan="2"><em>Aliases:</em></td></tr> 710<tr><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> 711<tr><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> 712<tr><td><code>EXP</code></td> <td>all export ciphers</td> </tr> 713<tr><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> 714<tr><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> 715<tr><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> 716<tr><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> 717<tr><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> 718<tr><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> 719<tr><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> 720<tr><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> 721<tr><td><code>ECDH</code></td> <td>Elliptic Curve Diffie-Hellman key exchange</td> </tr> 722<tr><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> 723<tr><td><code>AECDH</code></td> <td>all ciphers using Anonymous Elliptic Curve Diffie-Hellman key exchange</td> </tr> 724<tr><td><code>SRP</code></td> <td>all ciphers using Secure Remote Password (SRP) key exchange</td> </tr> 725<tr><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> 726<tr><td><code>ECDSA</code></td> <td>all ciphers using ECDSA authentication</td> </tr> 727<tr><td><code>aNULL</code></td> <td>all ciphers using no authentication</td> </tr> 728</table> 729<p> 730Now where this becomes interesting is that these can be put together 731to specify the order and ciphers you wish to use. To speed this up 732there are also aliases (<code>SSLv3, TLSv1, EXP, LOW, MEDIUM, 733HIGH</code>) for certain groups of ciphers. These tags can be joined 734together with prefixes to form the <em>cipher-spec</em>. Available 735prefixes are:</p> 736<ul> 737<li>none: add cipher to list</li> 738<li><code>+</code>: move matching ciphers to the current location in list</li> 739<li><code>-</code>: remove cipher from list (can be added later again)</li> 740<li><code>!</code>: kill cipher from list completely (can <strong>not</strong> be added later again)</li> 741</ul> 742 743<div class="note"> 744<h3><code>aNULL</code>, <code>eNULL</code> and <code>EXP</code> 745ciphers are always disabled</h3> 746<p>Beginning with version 2.4.7, null and export-grade 747ciphers are always disabled, as mod_ssl unconditionally prepends any supplied 748cipher suite string with <code>!aNULL:!eNULL:!EXP:</code> at initialization.</p> 749</div> 750 751<p>A simpler way to look at all of this is to use the ``<code>openssl ciphers 752-v</code>'' command which provides a nice way to successively create the 753correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string 754depends on the version of the OpenSSL libraries used. Let's suppose it is 755``<code>RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5</code>'' which 756means the following: Put <code>RC4-SHA</code> and <code>AES128-SHA</code> at 757the beginning. We do this, because these ciphers offer a good compromise 758between speed and security. Next, include high and medium security ciphers. 759Finally, remove all ciphers which do not authenticate, i.e. for SSL the 760Anonymous Diffie-Hellman ciphers, as well as all ciphers which use 761<code>MD5</code> as hash algorithm, because it has been proven insufficient.</p> 762<div class="example"><pre>$ openssl ciphers -v 'RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5' 763RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 764AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1 765DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1 766... ... ... ... ... 767SEED-SHA SSLv3 Kx=RSA Au=RSA Enc=SEED(128) Mac=SHA1 768PSK-RC4-SHA SSLv3 Kx=PSK Au=PSK Enc=RC4(128) Mac=SHA1 769KRB5-RC4-SHA SSLv3 Kx=KRB5 Au=KRB5 Enc=RC4(128) Mac=SHA1</pre></div> 770<p>The complete list of particular RSA & DH ciphers for SSL is given in <a href="#table2">Table 2</a>.</p> 771<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW</pre> 772</div> 773<table class="bordered"> 774 775<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> 776<tr><td colspan="7"><em>RSA Ciphers:</em></td></tr> 777<tr><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr> 778<tr><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td /> </tr> 779<tr><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td /> </tr> 780<tr><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td /> </tr> 781<tr><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr> 782<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> 783<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> 784<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> 785<tr><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td /> </tr> 786<tr><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td /> </tr> 787<tr><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> 788<tr><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr> 789<tr><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr> 790<tr><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td /> </tr> 791<tr><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr> 792<tr><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td /> </tr> 793<tr><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr> 794<tr><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td /> </tr> 795<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> 796<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> 797<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> 798<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> 799</table> 800 801</div> 802<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 803<div class="directive-section"><h2><a name="SSLCompression" id="SSLCompression">SSLCompression</a> <a name="sslcompression" id="sslcompression">Directive</a></h2> 804<table class="directive"> 805<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable compression on the SSL level</td></tr> 806<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCompression on|off</code></td></tr> 807<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCompression off</code></td></tr> 808<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 809<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 810<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 811<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.3 and later, if using OpenSSL 0.9.8 or later; 812virtual host scope available if using OpenSSL 1.0.0 or later. 813The default used to be <code>on</code> in version 2.4.3.</td></tr> 814</table> 815<p>This directive allows to enable compression on the SSL level.</p> 816<div class="warning"> 817<p>Enabling compression causes security issues in most setups (the so called 818CRIME attack).</p> 819</div> 820 821</div> 822<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 823<div class="directive-section"><h2><a name="SSLCryptoDevice" id="SSLCryptoDevice">SSLCryptoDevice</a> <a name="sslcryptodevice" id="sslcryptodevice">Directive</a></h2> 824<table class="directive"> 825<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable use of a cryptographic hardware accelerator</td></tr> 826<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCryptoDevice <em>engine</em></code></td></tr> 827<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCryptoDevice builtin</code></td></tr> 828<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 829<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 830<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 831</table> 832<p> 833This directive enables use of a cryptographic hardware accelerator 834board to offload some of the SSL processing overhead. This directive 835can only be used if the SSL toolkit is built with "engine" support; 836OpenSSL 0.9.7 and later releases have "engine" support by default, the 837separate "-engine" releases of OpenSSL 0.9.6 must be used.</p> 838 839<p>To discover which engine names are supported, run the command 840"<code>openssl engine</code>".</p> 841 842<div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># For a Broadcom accelerator: 843SSLCryptoDevice ubsec</pre> 844</div> 845 846</div> 847<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 848<div class="directive-section"><h2><a name="SSLEngine" id="SSLEngine">SSLEngine</a> <a name="sslengine" id="sslengine">Directive</a></h2> 849<table class="directive"> 850<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Engine Operation Switch</td></tr> 851<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLEngine on|off|optional</code></td></tr> 852<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLEngine off</code></td></tr> 853<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 854<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 855<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 856</table> 857<p> 858This directive toggles the usage of the SSL/TLS Protocol Engine. This 859is should be used inside a <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> section to enable SSL/TLS for a 860that virtual host. By default the SSL/TLS Protocol Engine is 861disabled for both the main server and all configured virtual hosts.</p> 862<div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><VirtualHost _default_:443> 863SSLEngine on 864#... 865</VirtualHost></pre> 866</div> 867<p>In Apache 2.1 and later, <code class="directive">SSLEngine</code> can be set to 868<code>optional</code>. This enables support for 869<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS 870Within HTTP/1.1. At this time no web browsers support RFC 2817.</p> 871 872</div> 873<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 874<div class="directive-section"><h2><a name="SSLFIPS" id="SSLFIPS">SSLFIPS</a> <a name="sslfips" id="sslfips">Directive</a></h2> 875<table class="directive"> 876<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL FIPS mode Switch</td></tr> 877<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLFIPS on|off</code></td></tr> 878<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLFIPS off</code></td></tr> 879<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 880<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 881<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 882</table> 883<p> 884This directive toggles the usage of the SSL library FIPS_mode flag. 885It must be set in the global server context and cannot be configured 886with conflicting settings (SSLFIPS on followed by SSLFIPS off or 887similar). The mode applies to all SSL library operations. 888</p> 889<p> 890If httpd was compiled against an SSL library which did not support 891the FIPS_mode flag, <code>SSLFIPS on</code> will fail. Refer to the 892FIPS 140-2 Security Policy document of the SSL provider library for 893specific requirements to use mod_ssl in a FIPS 140-2 approved mode 894of operation; note that mod_ssl itself is not validated, but may be 895described as using FIPS 140-2 validated cryptographic module, when 896all components are assembled and operated under the guidelines imposed 897by the applicable Security Policy. 898</p> 899 900</div> 901<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 902<div class="directive-section"><h2><a name="SSLHonorCipherOrder" id="SSLHonorCipherOrder">SSLHonorCipherOrder</a> <a name="sslhonorcipherorder" id="sslhonorcipherorder">Directive</a></h2> 903<table class="directive"> 904<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Option to prefer the server's cipher preference order</td></tr> 905<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLHonorCipherOrder on|off</code></td></tr> 906<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLHonorCipherOrder off</code></td></tr> 907<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 908<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 909<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 910<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later, if using OpenSSL 0.9.7 or later</td></tr> 911</table> 912<p>When choosing a cipher during an SSLv3 or TLSv1 handshake, normally 913the client's preference is used. If this directive is enabled, the 914server's preference will be used instead.</p> 915<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLHonorCipherOrder on</pre> 916</div> 917 918</div> 919<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 920<div class="directive-section"><h2><a name="SSLInsecureRenegotiation" id="SSLInsecureRenegotiation">SSLInsecureRenegotiation</a> <a name="sslinsecurerenegotiation" id="sslinsecurerenegotiation">Directive</a></h2> 921<table class="directive"> 922<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Option to enable support for insecure renegotiation</td></tr> 923<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLInsecureRenegotiation on|off</code></td></tr> 924<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLInsecureRenegotiation off</code></td></tr> 925<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 926<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 927<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 928<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.2.15 and later, if using OpenSSL 0.9.8m or later</td></tr> 929</table> 930<p>As originally specified, all versions of the SSL and TLS protocols 931(up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle 932attack 933(<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555">CVE-2009-3555</a>) 934during a renegotiation. This vulnerability allowed an attacker to 935"prefix" a chosen plaintext to the HTTP request as seen by the web 936server. A protocol extension was developed which fixed this 937vulnerability if supported by both client and server.</p> 938 939<p>If <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is linked against OpenSSL version 0.9.8m 940or later, by default renegotiation is only supported with 941clients supporting the new protocol extension. If this directive is 942enabled, renegotiation will be allowed with old (unpatched) clients, 943albeit insecurely.</p> 944 945<div class="warning"><h3>Security warning</h3> 946<p>If this directive is enabled, SSL connections will be vulnerable to 947the Man-in-the-Middle prefix attack as described 948in <a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555">CVE-2009-3555</a>.</p> 949</div> 950 951<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLInsecureRenegotiation on</pre> 952</div> 953 954<p>The <code>SSL_SECURE_RENEG</code> environment variable can be used 955from an SSI or CGI script to determine whether secure renegotiation is 956supported for a given SSL connection.</p> 957 958 959</div> 960<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 961<div class="directive-section"><h2><a name="SSLOCSPDefaultResponder" id="SSLOCSPDefaultResponder">SSLOCSPDefaultResponder</a> <a name="sslocspdefaultresponder" id="sslocspdefaultresponder">Directive</a></h2> 962<table class="directive"> 963<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the default responder URI for OCSP validation</td></tr> 964<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSDefaultResponder <em>uri</em></code></td></tr> 965<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 966<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 967<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 968<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 969</table> 970<p>This option sets the default OCSP responder to use. If <code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code> is not enabled, 971the URI given will be used only if no responder URI is specified in 972the certificate being verified.</p> 973 974</div> 975<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 976<div class="directive-section"><h2><a name="SSLOCSPEnable" id="SSLOCSPEnable">SSLOCSPEnable</a> <a name="sslocspenable" id="sslocspenable">Directive</a></h2> 977<table class="directive"> 978<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable OCSP validation of the client certificate chain</td></tr> 979<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPEnable on|off</code></td></tr> 980<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPEnable off</code></td></tr> 981<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 982<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 983<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 984<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 985</table> 986<p>This option enables OCSP validation of the client certificate 987chain. If this option is enabled, certificates in the client's 988certificate chain will be validated against an OCSP responder after 989normal verification (including CRL checks) have taken place.</p> 990 991<p>The OCSP responder used is either extracted from the certificate 992itself, or derived by configuration; see the 993<code class="directive"><a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></code> and 994<code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code> 995directives.</p> 996 997<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyClient on 998SSLOCSPEnable on 999SSLOCSPDefaultResponder http://responder.example.com:8888/responder 1000SSLOCSPOverrideResponder on</pre> 1001</div> 1002 1003</div> 1004<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1005<div class="directive-section"><h2><a name="SSLOCSPOverrideResponder" id="SSLOCSPOverrideResponder">SSLOCSPOverrideResponder</a> <a name="sslocspoverrideresponder" id="sslocspoverrideresponder">Directive</a></h2> 1006<table class="directive"> 1007<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Force use of the default responder URI for OCSP validation</td></tr> 1008<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPOverrideResponder on|off</code></td></tr> 1009<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPOverrideResponder off</code></td></tr> 1010<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1011<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1012<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1013<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 1014</table> 1015<p>This option forces the configured default OCSP responder to be used 1016during OCSP certificate validation, regardless of whether the 1017certificate being validated references an OCSP responder.</p> 1018 1019</div> 1020<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1021<div class="directive-section"><h2><a name="SSLOCSPResponderTimeout" id="SSLOCSPResponderTimeout">SSLOCSPResponderTimeout</a> <a name="sslocsprespondertimeout" id="sslocsprespondertimeout">Directive</a></h2> 1022<table class="directive"> 1023<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout for OCSP queries</td></tr> 1024<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponderTimeout <em>seconds</em></code></td></tr> 1025<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponderTimeout 10</code></td></tr> 1026<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1027<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1028<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1029<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 1030</table> 1031<p>This option sets the timeout for queries to OCSP responders, when 1032<code class="directive"><a href="#sslocspenable">SSLOCSPEnable</a></code> is turned on.</p> 1033 1034</div> 1035<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1036<div class="directive-section"><h2><a name="SSLOCSPResponseMaxAge" id="SSLOCSPResponseMaxAge">SSLOCSPResponseMaxAge</a> <a name="sslocspresponsemaxage" id="sslocspresponsemaxage">Directive</a></h2> 1037<table class="directive"> 1038<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable age for OCSP responses</td></tr> 1039<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponseMaxAge <em>seconds</em></code></td></tr> 1040<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponseMaxAge -1</code></td></tr> 1041<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1042<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1043<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1044<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 1045</table> 1046<p>This option sets the maximum allowable age ("freshness") for OCSP responses. 1047The default value (<code>-1</code>) does not enforce a maximum age, 1048which means that OCSP responses are considered valid as long as their 1049<code>nextUpdate</code> field is in the future.</p> 1050 1051</div> 1052<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1053<div class="directive-section"><h2><a name="SSLOCSPResponseTimeSkew" id="SSLOCSPResponseTimeSkew">SSLOCSPResponseTimeSkew</a> <a name="sslocspresponsetimeskew" id="sslocspresponsetimeskew">Directive</a></h2> 1054<table class="directive"> 1055<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable time skew for OCSP response validation</td></tr> 1056<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponseTimeSkew <em>seconds</em></code></td></tr> 1057<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponseTimeSkew 300</code></td></tr> 1058<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1059<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1060<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1061<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</td></tr> 1062</table> 1063<p>This option sets the maximum allowable time skew for OCSP responses 1064(when checking their <code>thisUpdate</code> and <code>nextUpdate</code> fields).</p> 1065 1066</div> 1067<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1068<div class="directive-section"><h2><a name="SSLOpenSSLConfCmd" id="SSLOpenSSLConfCmd">SSLOpenSSLConfCmd</a> <a name="sslopensslconfcmd" id="sslopensslconfcmd">Directive</a></h2> 1069<table class="directive"> 1070<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure OpenSSL parameters through its <em>SSL_CONF</em> API</td></tr> 1071<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOpenSSLConfCmd <em>command-name</em> <em>command-value</em></code></td></tr> 1072<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1073<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1074<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1075<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.8 and later, if using OpenSSL 1.0.2 or later</td></tr> 1076</table> 1077<p>This directive exposes OpenSSL's <em>SSL_CONF</em> API to mod_ssl, 1078allowing a flexible configuration of OpenSSL parameters without the need 1079of implementing additional <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> directives when new 1080features are added to OpenSSL.</p> 1081 1082<p>The set of available <code class="directive">SSLOpenSSLConfCmd</code> commands 1083depends on the OpenSSL version being used for <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> 1084(at least version 1.0.2 is required). For a list of supported command 1085names, see the section <em>Supported configuration file commands</em> in the 1086<a href="http://www.openssl.org/docs/ssl/SSL_CONF_cmd.html#SUPPORTED_CONFIGURATION_FILE_COM">SSL_CONF_cmd(3)</a> manual page for OpenSSL.</p> 1087 1088<p>Some of the <code class="directive">SSLOpenSSLConfCmd</code> commands can be used 1089as an alternative to existing directives (such as 1090<code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code> or 1091<code class="directive"><a href="#sslprotocol">SSLProtocol</a></code>), 1092though it should be noted that the syntax / allowable values for the parameters 1093may sometimes differ.</p> 1094 1095<div class="example"><h3>Examples</h3><pre class="prettyprint lang-config">SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference 1096SSLOpenSSLConfCmd ECDHParameters brainpoolP256r1 1097SSLOpenSSLConfCmd ServerInfoFile /usr/local/apache2/conf/server-info.pem 1098SSLOpenSSLConfCmd Protocol "-ALL, TLSv1.2" 1099SSLOpenSSLConfCmd SignatureAlgorithms RSA+SHA384:ECDSA+SHA256</pre> 1100</div> 1101 1102</div> 1103<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1104<div class="directive-section"><h2><a name="SSLOptions" id="SSLOptions">SSLOptions</a> <a name="ssloptions" id="ssloptions">Directive</a></h2> 1105<table class="directive"> 1106<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure various SSL engine run-time options</td></tr> 1107<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOptions [+|-]<em>option</em> ...</code></td></tr> 1108<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1109<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 1110<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1111<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1112</table> 1113<p> 1114This directive can be used to control various run-time options on a 1115per-directory basis. Normally, if multiple <code>SSLOptions</code> 1116could apply to a directory, then the most specific one is taken 1117completely; the options are not merged. However if <em>all</em> the 1118options on the <code>SSLOptions</code> directive are preceded by a 1119plus (<code>+</code>) or minus (<code>-</code>) symbol, the options 1120are merged. Any options preceded by a <code>+</code> are added to the 1121options currently in force, and any options preceded by a 1122<code>-</code> are removed from the options currently in force.</p> 1123<p> 1124The available <em>option</em>s are:</p> 1125<ul> 1126<li><code>StdEnvVars</code> 1127 <p> 1128 When this option is enabled, the standard set of SSL related CGI/SSI 1129 environment variables are created. This per default is disabled for 1130 performance reasons, because the information extraction step is a 1131 rather expensive operation. So one usually enables this option for 1132 CGI and SSI requests only.</p> 1133</li> 1134<li><code>ExportCertData</code> 1135 <p> 1136 When this option is enabled, additional CGI/SSI environment variables are 1137 created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and 1138 <code>SSL_CLIENT_CERT_CHAIN_</code><em>n</em> (with <em>n</em> = 0,1,2,..). 1139 These contain the PEM-encoded X.509 Certificates of server and client for 1140 the current HTTPS connection and can be used by CGI scripts for deeper 1141 Certificate checking. Additionally all other certificates of the client 1142 certificate chain are provided, too. This bloats up the environment a 1143 little bit which is why you have to use this option to enable it on 1144 demand.</p> 1145</li> 1146<li><code>FakeBasicAuth</code> 1147 <p> 1148 When this option is enabled, the Subject Distinguished Name (DN) of the 1149 Client X509 Certificate is translated into a HTTP Basic Authorization 1150 username. This means that the standard Apache authentication methods can 1151 be used for access control. The user name is just the Subject of the 1152 Client's X509 Certificate (can be determined by running OpenSSL's 1153 <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in 1154 </code><em>certificate</em><code>.crt</code>). Note that no password is 1155 obtained from the user. Every entry in the user file needs this password: 1156 ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the 1157 word `<code>password</code>''. Those who live under MD5-based encryption 1158 (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 1159 hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.</p> 1160 1161 <p>Note that the <code class="directive"><a href="/mod/mod_auth_basic.html#authbasicfake">AuthBasicFake</a></code> 1162 directive within <code class="module"><a href="/mod/mod_auth_basic.html">mod_auth_basic</a></code> can be used as a more 1163 general mechanism for faking basic authentication, giving control over the 1164 structure of both the username and password.</p> 1165</li> 1166<li><code>StrictRequire</code> 1167 <p> 1168 This <em>forces</em> forbidden access when <code>SSLRequireSSL</code> or 1169 <code>SSLRequire</code> successfully decided that access should be 1170 forbidden. Usually the default is that in the case where a ``<code>Satisfy 1171 any</code>'' directive is used, and other access restrictions are passed, 1172 denial of access due to <code>SSLRequireSSL</code> or 1173 <code>SSLRequire</code> is overridden (because that's how the Apache 1174 <code>Satisfy</code> mechanism should work.) But for strict access restriction 1175 you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in 1176 combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an 1177 additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has 1178 decided to deny access.</p> 1179</li> 1180<li><code>OptRenegotiate</code> 1181 <p> 1182 This enables optimized SSL connection renegotiation handling when SSL 1183 directives are used in per-directory context. By default a strict 1184 scheme is enabled where <em>every</em> per-directory reconfiguration of 1185 SSL parameters causes a <em>full</em> SSL renegotiation handshake. When this 1186 option is used mod_ssl tries to avoid unnecessary handshakes by doing more 1187 granular (but still safe) parameter checks. Nevertheless these granular 1188 checks sometimes may not be what the user expects, so enable this on a 1189 per-directory basis only, please.</p> 1190</li> 1191<li><code>LegacyDNStringFormat</code> 1192 <p> 1193 This option influences how values of the 1194 <code>SSL_{CLIENT,SERVER}_{I,S}_DN</code> variables are formatted. Since 1195 version 2.3.11, Apache HTTPD uses a RFC 2253 compatible format by 1196 default. This uses commas as delimiters between the attributes, allows the 1197 use of non-ASCII characters (which are converted to UTF8), escapes 1198 various special characters with backslashes, and sorts the attributes 1199 with the "C" attribute last.</p> 1200 1201 <p>If <code>LegacyDNStringFormat</code> is set, the old format will be 1202 used which sorts the "C" attribute first, uses slashes as separators, and 1203 does not handle non-ASCII and special characters in any consistent way. 1204 </p> 1205</li> 1206</ul> 1207<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLOptions +FakeBasicAuth -StrictRequire 1208<Files ~ "\.(cgi|shtml)$"> 1209 SSLOptions +StdEnvVars -ExportCertData 1210<Files></pre> 1211</div> 1212 1213</div> 1214<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1215<div class="directive-section"><h2><a name="SSLPassPhraseDialog" id="SSLPassPhraseDialog">SSLPassPhraseDialog</a> <a name="sslpassphrasedialog" id="sslpassphrasedialog">Directive</a></h2> 1216<table class="directive"> 1217<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of pass phrase dialog for encrypted private 1218keys</td></tr> 1219<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLPassPhraseDialog <em>type</em></code></td></tr> 1220<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLPassPhraseDialog builtin</code></td></tr> 1221<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1222<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1223<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1224</table> 1225<p> 1226When Apache starts up it has to read the various Certificate (see 1227<code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code>) and 1228Private Key (see <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>) files of the 1229SSL-enabled virtual servers. Because for security reasons the Private 1230Key files are usually encrypted, mod_ssl needs to query the 1231administrator for a Pass Phrase in order to decrypt those files. This 1232query can be done in two ways which can be configured by 1233<em>type</em>:</p> 1234<ul> 1235<li><code>builtin</code> 1236 <p> 1237 This is the default where an interactive terminal dialog occurs at startup 1238 time just before Apache detaches from the terminal. Here the administrator 1239 has to manually enter the Pass Phrase for each encrypted Private Key file. 1240 Because a lot of SSL-enabled virtual hosts can be configured, the 1241 following reuse-scheme is used to minimize the dialog: When a Private Key 1242 file is encrypted, all known Pass Phrases (at the beginning there are 1243 none, of course) are tried. If one of those known Pass Phrases succeeds no 1244 dialog pops up for this particular Private Key file. If none succeeded, 1245 another Pass Phrase is queried on the terminal and remembered for the next 1246 round (where it perhaps can be reused).</p> 1247 <p> 1248 This scheme allows mod_ssl to be maximally flexible (because for N encrypted 1249 Private Key files you <em>can</em> use N different Pass Phrases - but then 1250 you have to enter all of them, of course) while minimizing the terminal 1251 dialog (i.e. when you use a single Pass Phrase for all N Private Key files 1252 this Pass Phrase is queried only once).</p></li> 1253 1254<li><code>|/path/to/program [args...]</code> 1255 1256 <p>This mode allows an external program to be used which acts as a 1257 pipe to a particular input device; the program is sent the standard 1258 prompt text used for the <code>builtin</code> mode on 1259 <code>stdin</code>, and is expected to write password strings on 1260 <code>stdout</code>. If several passwords are needed (or an 1261 incorrect password is entered), additional prompt text will be 1262 written subsequent to the first password being returned, and more 1263 passwords must then be written back.</p></li> 1264 1265<li><code>exec:/path/to/program</code> 1266 <p> 1267 Here an external program is configured which is called at startup for each 1268 encrypted Private Key file. It is called with two arguments (the first is 1269 of the form ``<code>servername:portnumber</code>'', the second is either 1270 ``<code>RSA</code>'', ``<code>DSA</code>'', or ``<code>ECC</code>''), which 1271 indicate for which server and algorithm it has to print the corresponding 1272 Pass Phrase to <code>stdout</code>. The intent is that this external 1273 program first runs security checks to make sure that the system is not 1274 compromised by an attacker, and only when these checks were passed 1275 successfully it provides the Pass Phrase.</p> 1276 <p> 1277 Both these security checks, and the way the Pass Phrase is determined, can 1278 be as complex as you like. Mod_ssl just defines the interface: an 1279 executable program which provides the Pass Phrase on <code>stdout</code>. 1280 Nothing more or less! So, if you're really paranoid about security, here 1281 is your interface. Anything else has to be left as an exercise to the 1282 administrator, because local security requirements are so different.</p> 1283 <p> 1284 The reuse-algorithm above is used here, too. In other words: The external 1285 program is called only once per unique Pass Phrase.</p></li> 1286</ul> 1287<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter</pre> 1288</div> 1289 1290</div> 1291<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1292<div class="directive-section"><h2><a name="SSLProtocol" id="SSLProtocol">SSLProtocol</a> <a name="sslprotocol" id="sslprotocol">Directive</a></h2> 1293<table class="directive"> 1294<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL/TLS protocol versions</td></tr> 1295<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProtocol [+|-]<em>protocol</em> ...</code></td></tr> 1296<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProtocol all</code></td></tr> 1297<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1298<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1299<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1300</table> 1301<p> 1302This directive can be used to control which versions of the SSL/TLS protocol 1303will be accepted in new connections.</p> 1304<p> 1305The available (case-insensitive) <em>protocol</em>s are:</p> 1306<ul> 1307<li><code>SSLv3</code> 1308 <p> 1309 This is the Secure Sockets Layer (SSL) protocol, version 3.0, from 1310 the Netscape Corporation. 1311 It is the successor to SSLv2 and the predecessor to TLSv1.</p></li> 1312 1313<li><code>TLSv1</code> 1314 <p> 1315 This is the Transport Layer Security (TLS) protocol, version 1.0. 1316 It is the successor to SSLv3 and is defined in 1317 <a href="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</a>. 1318 It is supported by nearly every client.</p></li> 1319 1320<li><code>TLSv1.1</code> (when using OpenSSL 1.0.1 and later) 1321 <p> 1322 A revision of the TLS 1.0 protocol, as defined in 1323 <a href="http://www.ietf.org/rfc/rfc4346.txt">RFC 4346</a>.</p></li> 1324 1325<li><code>TLSv1.2</code> (when using OpenSSL 1.0.1 and later) 1326 <p> 1327 A revision of the TLS 1.1 protocol, as defined in 1328 <a href="http://www.ietf.org/rfc/rfc5246.txt">RFC 5246</a>.</p></li> 1329 1330<li><code>all</code> 1331 <p> 1332 This is a shortcut for ``<code>+SSLv3 +TLSv1</code>'' or 1333 - when using OpenSSL 1.0.1 and later - 1334 ``<code>+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2</code>, respectively.</p></li> 1335</ul> 1336<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProtocol TLSv1</pre> 1337</div> 1338 1339</div> 1340<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1341<div class="directive-section"><h2><a name="SSLProxyCACertificateFile" id="SSLProxyCACertificateFile">SSLProxyCACertificateFile</a> <a name="sslproxycacertificatefile" id="sslproxycacertificatefile">Directive</a></h2> 1342<table class="directive"> 1343<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates 1344for Remote Server Auth</td></tr> 1345<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificateFile <em>file-path</em></code></td></tr> 1346<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1347<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1348<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1349</table> 1350<p> 1351This directive sets the <em>all-in-one</em> file where you can assemble the 1352Certificates of Certification Authorities (CA) whose <em>remote servers</em> you deal 1353with. These are used for Remote Server Authentication. Such a file is simply the 1354concatenation of the various PEM-encoded Certificate files, in order of 1355preference. This can be used alternatively and/or additionally to 1356<code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>.</p> 1357<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt</pre> 1358</div> 1359 1360</div> 1361<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1362<div class="directive-section"><h2><a name="SSLProxyCACertificatePath" id="SSLProxyCACertificatePath">SSLProxyCACertificatePath</a> <a name="sslproxycacertificatepath" id="sslproxycacertificatepath">Directive</a></h2> 1363<table class="directive"> 1364<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for 1365Remote Server Auth</td></tr> 1366<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificatePath <em>directory-path</em></code></td></tr> 1367<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1368<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1369<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1370</table> 1371<p> 1372This directive sets the directory where you keep the Certificates of 1373Certification Authorities (CAs) whose remote servers you deal with. These are used to 1374verify the remote server certificate on Remote Server Authentication.</p> 1375<p> 1376The files in this directory have to be PEM-encoded and are accessed through 1377hash filenames. So usually you can't just place the Certificate files 1378there: you also have to create symbolic links named 1379<em>hash-value</em><code>.N</code>. And you should always make sure this directory 1380contains the appropriate symbolic links.</p> 1381<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/</pre> 1382</div> 1383 1384</div> 1385<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1386<div class="directive-section"><h2><a name="SSLProxyCARevocationCheck" id="SSLProxyCARevocationCheck">SSLProxyCARevocationCheck</a> <a name="sslproxycarevocationcheck" id="sslproxycarevocationcheck">Directive</a></h2> 1387<table class="directive"> 1388<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable CRL-based revocation checking for Remote Server Auth</td></tr> 1389<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationCheck chain|leaf|none</code></td></tr> 1390<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCARevocationCheck none</code></td></tr> 1391<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1392<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1393<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1394</table> 1395<p> 1396Enables certificate revocation list (CRL) checking for the 1397<em>remote servers</em> you deal with. At least one of 1398<code class="directive"><a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></code> 1399or <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code> must be 1400configured. When set to <code>chain</code> (recommended setting), 1401CRL checks are applied to all certificates in the chain, while setting it to 1402<code>leaf</code> limits the checks to the end-entity cert. 1403</p> 1404<div class="note"> 1405<h3>When set to <code>chain</code> or <code>leaf</code>, 1406CRLs <em>must</em> be available for successful validation</h3> 1407<p> 1408Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when 1409no CRL(s) were found in any of the locations configured with 1410<code class="directive"><a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></code> 1411or <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code>. 1412With the introduction of this directive, the behavior has been changed: 1413when checking is enabled, CRLs <em>must</em> be present for the validation 1414to succeed - otherwise it will fail with an 1415<code>"unable to get certificate CRL"</code> error. 1416</p> 1417</div> 1418<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationCheck chain</pre> 1419</div> 1420 1421</div> 1422<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1423<div class="directive-section"><h2><a name="SSLProxyCARevocationFile" id="SSLProxyCARevocationFile">SSLProxyCARevocationFile</a> <a name="sslproxycarevocationfile" id="sslproxycarevocationfile">Directive</a></h2> 1424<table class="directive"> 1425<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for 1426Remote Server Auth</td></tr> 1427<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationFile <em>file-path</em></code></td></tr> 1428<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1429<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1430<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1431</table> 1432<p> 1433This directive sets the <em>all-in-one</em> file where you can 1434assemble the Certificate Revocation Lists (CRL) of Certification 1435Authorities (CA) whose <em>remote servers</em> you deal with. These are used 1436for Remote Server Authentication. Such a file is simply the concatenation of 1437the various PEM-encoded CRL files, in order of preference. This can be 1438used alternatively and/or additionally to <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code>.</p> 1439<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl</pre> 1440</div> 1441 1442</div> 1443<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1444<div class="directive-section"><h2><a name="SSLProxyCARevocationPath" id="SSLProxyCARevocationPath">SSLProxyCARevocationPath</a> <a name="sslproxycarevocationpath" id="sslproxycarevocationpath">Directive</a></h2> 1445<table class="directive"> 1446<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for 1447Remote Server Auth</td></tr> 1448<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationPath <em>directory-path</em></code></td></tr> 1449<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1450<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1451<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1452</table> 1453<p> 1454This directive sets the directory where you keep the Certificate Revocation 1455Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. 1456These are used to revoke the remote server certificate on Remote Server Authentication.</p> 1457<p> 1458The files in this directory have to be PEM-encoded and are accessed through 1459hash filenames. So usually you have not only to place the CRL files there. 1460Additionally you have to create symbolic links named 1461<em>hash-value</em><code>.rN</code>. And you should always make sure this directory 1462contains the appropriate symbolic links.</p> 1463<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/</pre> 1464</div> 1465 1466</div> 1467<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1468<div class="directive-section"><h2><a name="SSLProxyCheckPeerCN" id="SSLProxyCheckPeerCN">SSLProxyCheckPeerCN</a> <a name="sslproxycheckpeercn" id="sslproxycheckpeercn">Directive</a></h2> 1469<table class="directive"> 1470<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check the remote server certificate's CN field 1471</td></tr> 1472<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerCN on|off</code></td></tr> 1473<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerCN on</code></td></tr> 1474<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1475<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1476<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1477</table> 1478<p> 1479This directive sets whether the remote server certificate's CN field is 1480compared against the hostname of the request URL. If both are not equal 1481a 502 status code (Bad Gateway) is sent. 1482</p> 1483<p> 1484In 2.4.5 and later, SSLProxyCheckPeerCN has been superseded by 1485<code class="directive"><a href="#sslproxycheckpeername">SSLProxyCheckPeerName</a></code>, and its 1486setting is only taken into account when 1487<code>SSLProxyCheckPeerName off</code> is specified at the same time. 1488</p> 1489<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCheckPeerCN on</pre> 1490</div> 1491 1492</div> 1493<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1494<div class="directive-section"><h2><a name="SSLProxyCheckPeerExpire" id="SSLProxyCheckPeerExpire">SSLProxyCheckPeerExpire</a> <a name="sslproxycheckpeerexpire" id="sslproxycheckpeerexpire">Directive</a></h2> 1495<table class="directive"> 1496<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check if remote server certificate is expired 1497</td></tr> 1498<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerExpire on|off</code></td></tr> 1499<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerExpire on</code></td></tr> 1500<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1501<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1502<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1503</table> 1504<p> 1505This directive sets whether it is checked if the remote server certificate 1506is expired or not. If the check fails a 502 status code (Bad Gateway) is 1507sent. 1508</p> 1509<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCheckPeerExpire on</pre> 1510</div> 1511 1512</div> 1513<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1514<div class="directive-section"><h2><a name="SSLProxyCheckPeerName" id="SSLProxyCheckPeerName">SSLProxyCheckPeerName</a> <a name="sslproxycheckpeername" id="sslproxycheckpeername">Directive</a></h2> 1515<table class="directive"> 1516<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure host name checking for remote server certificates 1517</td></tr> 1518<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerName on|off</code></td></tr> 1519<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerName on</code></td></tr> 1520<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1521<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1522<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1523<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.4.5 and later</td></tr> 1524</table> 1525<p> 1526This directive configures host name checking for server certificates 1527when mod_ssl is acting as an SSL client. The check will 1528succeed if the host name from the request URI is found in 1529either the subjectAltName extension or (one of) the CN attribute(s) 1530in the certificate's subject. If the check fails, the SSL request 1531is aborted and a 502 status code (Bad Gateway) is returned. 1532The directive supersedes <code class="directive"><a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></code>, 1533which only checks for the expected host name in the first CN attribute. 1534</p> 1535<p> 1536Wildcard matching is supported in one specific flavor: subjectAltName entries 1537of type dNSName or CN attributes starting with <code>*.</code> will match 1538for any DNS name with the same number of labels and the same suffix 1539(i.e., <code>*.example.org</code> matches for <code>foo.example.org</code>, 1540but not for <code>foo.bar.example.org</code>). 1541</p> 1542 1543</div> 1544<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1545<div class="directive-section"><h2><a name="SSLProxyCipherSuite" id="SSLProxyCipherSuite">SSLProxyCipherSuite</a> <a name="sslproxyciphersuite" id="sslproxyciphersuite">Directive</a></h2> 1546<table class="directive"> 1547<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL 1548proxy handshake</td></tr> 1549<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCipherSuite <em>cipher-spec</em></code></td></tr> 1550<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP</code></td></tr> 1551<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1552<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 1553<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1554<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1555</table> 1556<p>Equivalent to <code>SSLCipherSuite</code>, but for the proxy connection. 1557Please refer to <code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code> 1558for additional information.</p> 1559 1560</div> 1561<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1562<div class="directive-section"><h2><a name="SSLProxyEngine" id="SSLProxyEngine">SSLProxyEngine</a> <a name="sslproxyengine" id="sslproxyengine">Directive</a></h2> 1563<table class="directive"> 1564<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Proxy Engine Operation Switch</td></tr> 1565<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyEngine on|off</code></td></tr> 1566<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyEngine off</code></td></tr> 1567<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1568<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1569<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1570</table> 1571<p> 1572This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This 1573is usually used inside a <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> section to enable SSL/TLS for proxy 1574usage in a particular virtual host. By default the SSL/TLS Protocol Engine is 1575disabled for proxy both for the main server and all configured virtual hosts.</p> 1576 1577<p>Note that the SSLProxyEngine directive should not, in 1578general, be included in a virtual host that will be acting as a 1579forward proxy (using <Proxy> or <ProxyRequest> directives. 1580SSLProxyEngine is not required to enable a forward proxy server to 1581proxy SSL/TLS requests.</p> 1582 1583<div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><VirtualHost _default_:443> 1584 SSLProxyEngine on 1585 #... 1586</VirtualHost></pre> 1587</div> 1588 1589</div> 1590<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1591<div class="directive-section"><h2><a name="SSLProxyMachineCertificateChainFile" id="SSLProxyMachineCertificateChainFile">SSLProxyMachineCertificateChainFile</a> <a name="sslproxymachinecertificatechainfile" id="sslproxymachinecertificatechainfile">Directive</a></h2> 1592<table class="directive"> 1593<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate</td></tr> 1594<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificateChainFile <em>filename</em></code></td></tr> 1595<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1596<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Not applicable</td></tr> 1597<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1598<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1599</table> 1600<p> 1601This directive sets the all-in-one file where you keep the certificate chain 1602for all of the client certs in use. This directive will be needed if the 1603remote server presents a list of CA certificates that are not direct signers 1604of one of the configured client certificates. 1605</p> 1606<p> 1607This referenced file is simply the concatenation of the various PEM-encoded 1608certificate files. Upon startup, each client certificate configured will 1609be examined and a chain of trust will be constructed. 1610</p> 1611<div class="warning"><h3>Security warning</h3> 1612<p>If this directive is enabled, all of the certificates in the file will be 1613trusted as if they were also in <code class="directive"><a href="#sslproxycacertificatefile"> 1614SSLProxyCACertificateFile</a></code>.</p> 1615</div> 1616<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificateChainFile /usr/local/apache2/conf/ssl.crt/proxyCA.pem</pre> 1617</div> 1618 1619</div> 1620<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1621<div class="directive-section"><h2><a name="SSLProxyMachineCertificateFile" id="SSLProxyMachineCertificateFile">SSLProxyMachineCertificateFile</a> <a name="sslproxymachinecertificatefile" id="sslproxymachinecertificatefile">Directive</a></h2> 1622<table class="directive"> 1623<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded client certificates and keys to be used by the proxy</td></tr> 1624<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificateFile <em>filename</em></code></td></tr> 1625<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1626<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Not applicable</td></tr> 1627<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1628<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1629</table> 1630<p> 1631This directive sets the all-in-one file where you keep the certificates and 1632keys used for authentication of the proxy server to remote servers. 1633</p> 1634<p> 1635This referenced file is simply the concatenation of the various PEM-encoded 1636certificate files, in order of preference. Use this directive alternatively 1637or additionally to <code>SSLProxyMachineCertificatePath</code>. 1638</p> 1639<div class="warning"> 1640<p>Currently there is no support for encrypted private keys</p> 1641</div> 1642<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem</pre> 1643</div> 1644 1645</div> 1646<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1647<div class="directive-section"><h2><a name="SSLProxyMachineCertificatePath" id="SSLProxyMachineCertificatePath">SSLProxyMachineCertificatePath</a> <a name="sslproxymachinecertificatepath" id="sslproxymachinecertificatepath">Directive</a></h2> 1648<table class="directive"> 1649<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded client certificates and keys to be used by the proxy</td></tr> 1650<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificatePath <em>directory</em></code></td></tr> 1651<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1652<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Not applicable</td></tr> 1653<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1654<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1655</table> 1656<p> 1657This directive sets the directory where you keep the certificates and 1658keys used for authentication of the proxy server to remote servers. 1659</p> 1660<p>The files in this directory must be PEM-encoded and are accessed through 1661hash filenames. Additionally, you must create symbolic links named 1662<code><em>hash-value</em>.N</code>. And you should always make sure this 1663directory contains the appropriate symbolic links.</p> 1664<div class="warning"> 1665<p>Currently there is no support for encrypted private keys</p> 1666</div> 1667<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/</pre> 1668</div> 1669 1670</div> 1671<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1672<div class="directive-section"><h2><a name="SSLProxyProtocol" id="SSLProxyProtocol">SSLProxyProtocol</a> <a name="sslproxyprotocol" id="sslproxyprotocol">Directive</a></h2> 1673<table class="directive"> 1674<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL protocol flavors for proxy usage</td></tr> 1675<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyProtocol [+|-]<em>protocol</em> ...</code></td></tr> 1676<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyProtocol all</code></td></tr> 1677<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1678<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 1679<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1680<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1681</table> 1682 1683<p> 1684This directive can be used to control the SSL protocol flavors mod_ssl should 1685use when establishing its server environment for proxy . It will only connect 1686to servers using one of the provided protocols.</p> 1687<p>Please refer to <code class="directive"><a href="#sslprotocol">SSLProtocol</a></code> 1688for additional information. 1689</p> 1690 1691</div> 1692<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1693<div class="directive-section"><h2><a name="SSLProxyVerify" id="SSLProxyVerify">SSLProxyVerify</a> <a name="sslproxyverify" id="sslproxyverify">Directive</a></h2> 1694<table class="directive"> 1695<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of remote server Certificate verification</td></tr> 1696<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerify <em>level</em></code></td></tr> 1697<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerify none</code></td></tr> 1698<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1699<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1700<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1701</table> 1702 1703<p>When a proxy is configured to forward requests to a remote SSL 1704server, this directive can be used to configure certificate 1705verification of the remote server. </p> 1706<p> 1707The following levels are available for <em>level</em>:</p> 1708<ul> 1709<li><strong>none</strong>: 1710 no remote server Certificate is required at all</li> 1711<li><strong>optional</strong>: 1712 the remote server <em>may</em> present a valid Certificate</li> 1713<li><strong>require</strong>: 1714 the remote server <em>has to</em> present a valid Certificate</li> 1715<li><strong>optional_no_ca</strong>: 1716 the remote server may present a valid Certificate<br /> 1717 but it need not to be (successfully) verifiable.</li> 1718</ul> 1719<p>In practice only levels <strong>none</strong> and 1720<strong>require</strong> are really interesting, because level 1721<strong>optional</strong> doesn't work with all servers and level 1722<strong>optional_no_ca</strong> is actually against the idea of 1723authentication (but can be used to establish SSL test pages, etc.)</p> 1724<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyVerify require</pre> 1725</div> 1726 1727</div> 1728<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1729<div class="directive-section"><h2><a name="SSLProxyVerifyDepth" id="SSLProxyVerifyDepth">SSLProxyVerifyDepth</a> <a name="sslproxyverifydepth" id="sslproxyverifydepth">Directive</a></h2> 1730<table class="directive"> 1731<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Remote Server 1732Certificate verification</td></tr> 1733<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerifyDepth <em>number</em></code></td></tr> 1734<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerifyDepth 1</code></td></tr> 1735<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 1736<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1737<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1738</table> 1739<p> 1740This directive sets how deeply mod_ssl should verify before deciding that the 1741remote server does not have a valid certificate. </p> 1742<p> 1743The depth actually is the maximum number of intermediate certificate issuers, 1744i.e. the number of CA certificates which are max allowed to be followed while 1745verifying the remote server certificate. A depth of 0 means that self-signed 1746remote server certificates are accepted only, the default depth of 1 means 1747the remote server certificate can be self-signed or has to be signed by a CA 1748which is directly known to the server (i.e. the CA's certificate is under 1749<code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>), etc.</p> 1750<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyVerifyDepth 10</pre> 1751</div> 1752 1753</div> 1754<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1755<div class="directive-section"><h2><a name="SSLRandomSeed" id="SSLRandomSeed">SSLRandomSeed</a> <a name="sslrandomseed" id="sslrandomseed">Directive</a></h2> 1756<table class="directive"> 1757<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pseudo Random Number Generator (PRNG) seeding 1758source</td></tr> 1759<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRandomSeed <em>context</em> <em>source</em> 1760[<em>bytes</em>]</code></td></tr> 1761<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 1762<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1763<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1764</table> 1765<p> 1766This configures one or more sources for seeding the Pseudo Random Number 1767Generator (PRNG) in OpenSSL at startup time (<em>context</em> is 1768<code>startup</code>) and/or just before a new SSL connection is established 1769(<em>context</em> is <code>connect</code>). This directive can only be used 1770in the global server context because the PRNG is a global facility.</p> 1771<p> 1772The following <em>source</em> variants are available:</p> 1773<ul> 1774<li><code>builtin</code> 1775 <p> This is the always available builtin seeding source. Its usage 1776 consumes minimum CPU cycles under runtime and hence can be always used 1777 without drawbacks. The source used for seeding the PRNG contains of the 1778 current time, the current process id and (when applicable) a randomly 1779 chosen 1KB extract of the inter-process scoreboard structure of Apache. 1780 The drawback is that this is not really a strong source and at startup 1781 time (where the scoreboard is still not available) this source just 1782 produces a few bytes of entropy. So you should always, at least for the 1783 startup, use an additional seeding source.</p></li> 1784<li><code>file:/path/to/source</code> 1785 <p> 1786 This variant uses an external file <code>/path/to/source</code> as the 1787 source for seeding the PRNG. When <em>bytes</em> is specified, only the 1788 first <em>bytes</em> number of bytes of the file form the entropy (and 1789 <em>bytes</em> is given to <code>/path/to/source</code> as the first 1790 argument). When <em>bytes</em> is not specified the whole file forms the 1791 entropy (and <code>0</code> is given to <code>/path/to/source</code> as 1792 the first argument). Use this especially at startup time, for instance 1793 with an available <code>/dev/random</code> and/or 1794 <code>/dev/urandom</code> devices (which usually exist on modern Unix 1795 derivatives like FreeBSD and Linux).</p> 1796 <p> 1797 <em>But be careful</em>: Usually <code>/dev/random</code> provides only as 1798 much entropy data as it actually has, i.e. when you request 512 bytes of 1799 entropy, but the device currently has only 100 bytes available two things 1800 can happen: On some platforms you receive only the 100 bytes while on 1801 other platforms the read blocks until enough bytes are available (which 1802 can take a long time). Here using an existing <code>/dev/urandom</code> is 1803 better, because it never blocks and actually gives the amount of requested 1804 data. The drawback is just that the quality of the received data may not 1805 be the best.</p></li> 1806 1807<li><code>exec:/path/to/program</code> 1808 <p> 1809 This variant uses an external executable 1810 <code>/path/to/program</code> as the source for seeding the 1811 PRNG. When <em>bytes</em> is specified, only the first 1812 <em>bytes</em> number of bytes of its <code>stdout</code> contents 1813 form the entropy. When <em>bytes</em> is not specified, the 1814 entirety of the data produced on <code>stdout</code> form the 1815 entropy. Use this only at startup time when you need a very strong 1816 seeding with the help of an external program (for instance as in 1817 the example above with the <code>truerand</code> utility you can 1818 find in the mod_ssl distribution which is based on the AT&T 1819 <em>truerand</em> library). Using this in the connection context 1820 slows down the server too dramatically, of course. So usually you 1821 should avoid using external programs in that context.</p></li> 1822<li><code>egd:/path/to/egd-socket</code> (Unix only) 1823 <p> 1824 This variant uses the Unix domain socket of the 1825 external Entropy Gathering Daemon (EGD) (see <a href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech 1826 /crypto/</a>) to seed the PRNG. Use this if no random device exists 1827 on your platform.</p></li> 1828</ul> 1829<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRandomSeed startup builtin 1830SSLRandomSeed startup file:/dev/random 1831SSLRandomSeed startup file:/dev/urandom 1024 1832SSLRandomSeed startup exec:/usr/local/bin/truerand 16 1833SSLRandomSeed connect builtin 1834SSLRandomSeed connect file:/dev/random 1835SSLRandomSeed connect file:/dev/urandom 1024</pre> 1836</div> 1837 1838</div> 1839<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1840<div class="directive-section"><h2><a name="SSLRenegBufferSize" id="SSLRenegBufferSize">SSLRenegBufferSize</a> <a name="sslrenegbuffersize" id="sslrenegbuffersize">Directive</a></h2> 1841<table class="directive"> 1842<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the size for the SSL renegotiation buffer</td></tr> 1843<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRenegBufferSize <var>bytes</var></code></td></tr> 1844<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLRenegBufferSize 131072</code></td></tr> 1845<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 1846<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 1847<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1848<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1849</table> 1850 1851<p>If an SSL renegotiation is required in per-location context, for 1852example, any use of <code class="directive"><a href="#sslverifyclient">SSLVerifyClient</a></code> in a Directory or 1853Location block, then <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> must buffer any HTTP 1854request body into memory until the new SSL handshake can be performed. 1855This directive can be used to set the amount of memory that will be 1856used for this buffer. </p> 1857 1858<div class="warning"><p> 1859Note that in many configurations, the client sending the request body 1860will be untrusted so a denial of service attack by consumption of 1861memory must be considered when changing this configuration setting. 1862</p></div> 1863 1864<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRenegBufferSize 262144</pre> 1865</div> 1866 1867</div> 1868<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1869<div class="directive-section"><h2><a name="SSLRequire" id="SSLRequire">SSLRequire</a> <a name="sslrequire" id="sslrequire">Directive</a></h2> 1870<table class="directive"> 1871<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow access only when an arbitrarily complex 1872boolean expression is true</td></tr> 1873<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequire <em>expression</em></code></td></tr> 1874<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 1875<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 1876<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1877<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 1878</table> 1879 1880<div class="note"><h3>SSLRequire is deprecated</h3> 1881<p><code>SSLRequire</code> is deprecated and should in general be replaced 1882by <a href="mod_authz_core.html#reqexpr">Require expr</a>. The so called 1883<a href="/expr.html">ap_expr</a> syntax of <code>Require expr</code> is 1884a superset of the syntax of <code>SSLRequire</code>, with the following 1885exception:</p> 1886 1887<p>In <code>SSLRequire</code>, the comparison operators <code><</code>, 1888<code><=</code>, ... are completely equivalent to the operators 1889<code>lt</code>, <code>le</code>, ... and work in a somewhat peculiar way that 1890first compares the length of two strings and then the lexical order. 1891On the other hand, <a href="/expr.html">ap_expr</a> has two sets of 1892comparison operators: The operators <code><</code>, 1893<code><=</code>, ... do lexical string comparison, while the operators 1894<code>-lt</code>, <code>-le</code>, ... do integer comparison. 1895For the latter, there are also aliases without the leading dashes: 1896<code>lt</code>, <code>le</code>, ... 1897</p> 1898 1899</div> 1900 1901<p> 1902This directive specifies a general access requirement which has to be 1903fulfilled in order to allow access. It is a very powerful directive because the 1904requirement specification is an arbitrarily complex boolean expression 1905containing any number of access checks.</p> 1906<p> 1907The <em>expression</em> must match the following syntax (given as a BNF 1908grammar notation):</p> 1909<blockquote> 1910<pre>expr ::= "<strong>true</strong>" | "<strong>false</strong>" 1911 | "<strong>!</strong>" expr 1912 | expr "<strong>&&</strong>" expr 1913 | expr "<strong>||</strong>" expr 1914 | "<strong>(</strong>" expr "<strong>)</strong>" 1915 | comp 1916 1917comp ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word 1918 | word "<strong>!=</strong>" word | word "<strong>ne</strong>" word 1919 | word "<strong><</strong>" word | word "<strong>lt</strong>" word 1920 | word "<strong><=</strong>" word | word "<strong>le</strong>" word 1921 | word "<strong>></strong>" word | word "<strong>gt</strong>" word 1922 | word "<strong>>=</strong>" word | word "<strong>ge</strong>" word 1923 | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>" 1924 | word "<strong>in</strong>" "<strong>PeerExtList(</strong>" word "<strong>)</strong>" 1925 | word "<strong>=~</strong>" regex 1926 | word "<strong>!~</strong>" regex 1927 1928wordlist ::= word 1929 | wordlist "<strong>,</strong>" word 1930 1931word ::= digit 1932 | cstring 1933 | variable 1934 | function 1935 1936digit ::= [0-9]+ 1937cstring ::= "..." 1938variable ::= "<strong>%{</strong>" varname "<strong>}</strong>" 1939function ::= funcname "<strong>(</strong>" funcargs "<strong>)</strong>"</pre> 1940</blockquote> 1941<p>For <code>varname</code> any of the variables described in <a href="#envvars">Environment Variables</a> can be used. For 1942<code>funcname</code> the available functions are listed in 1943the <a href="/expr.html#functions">ap_expr documentation</a>.</p> 1944 1945<p>The <em>expression</em> is parsed into an internal machine 1946representation when the configuration is loaded, and then evaluated 1947during request processing. In .htaccess context, the <em>expression</em> is 1948both parsed and executed each time the .htaccess file is encountered during 1949request processing.</p> 1950 1951<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ 1952 and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ 1953 and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ 1954 and %{TIME_WDAY} -ge 1 and %{TIME_WDAY} -le 5 \ 1955 and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20 ) \ 1956 or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/</pre> 1957</div> 1958 1959<p>The <code>PeerExtList(<em>object-ID</em>)</code> function expects 1960to find zero or more instances of the X.509 certificate extension 1961identified by the given <em>object ID</em> (OID) in the client certificate. 1962The expression evaluates to true if the left-hand side string matches 1963exactly against the value of an extension identified with this OID. 1964(If multiple extensions with the same OID are present, at least one 1965extension must match).</p> 1966 1967<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")</pre> 1968</div> 1969 1970<div class="note"><h3>Notes on the PeerExtList function</h3> 1971 1972<ul> 1973 1974<li><p>The object ID can be specified either as a descriptive 1975name recognized by the SSL library, such as <code>"nsComment"</code>, 1976or as a numeric OID, such as <code>"1.2.3.4.5.6"</code>.</p></li> 1977 1978<li><p>Expressions with types known to the SSL library are rendered to 1979a string before comparison. For an extension with a type not 1980recognized by the SSL library, mod_ssl will parse the value if it is 1981one of the primitive ASN.1 types UTF8String, IA5String, VisibleString, 1982or BMPString. For an extension of one of these types, the string 1983value will be converted to UTF-8 if necessary, then compared against 1984the left-hand-side expression.</p></li> 1985 1986</ul> 1987</div> 1988 1989 1990<h3>See also</h3> 1991<ul> 1992<li><a href="/env.html">Environment Variables in Apache HTTP Server</a>, 1993for additional examples. 1994</li> 1995<li><a href="mod_authz_core.html#reqexpr">Require expr</a></li> 1996<li><a href="/expr.html">Generic expression syntax in Apache HTTP Server</a> 1997</li> 1998</ul> 1999</div> 2000<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2001<div class="directive-section"><h2><a name="SSLRequireSSL" id="SSLRequireSSL">SSLRequireSSL</a> <a name="sslrequiressl" id="sslrequiressl">Directive</a></h2> 2002<table class="directive"> 2003<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deny access when SSL is not used for the 2004HTTP request</td></tr> 2005<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequireSSL</code></td></tr> 2006<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> 2007<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 2008<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2009<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2010</table> 2011<p> 2012This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for 2013the current connection. This is very handy inside the SSL-enabled virtual 2014host or directories for defending against configuration errors that expose 2015stuff that should be protected. When this directive is present all requests 2016are denied which are not using SSL.</p> 2017<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequireSSL</pre> 2018</div> 2019 2020</div> 2021<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2022<div class="directive-section"><h2><a name="SSLSessionCache" id="SSLSessionCache">SSLSessionCache</a> <a name="sslsessioncache" id="sslsessioncache">Directive</a></h2> 2023<table class="directive"> 2024<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of the global/inter-process SSL Session 2025Cache</td></tr> 2026<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCache <em>type</em></code></td></tr> 2027<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCache none</code></td></tr> 2028<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 2029<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2030<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2031</table> 2032<p> 2033This configures the storage type of the global/inter-process SSL Session 2034Cache. This cache is an optional facility which speeds up parallel request 2035processing. For requests to the same server process (via HTTP keep-alive), 2036OpenSSL already caches the SSL session information locally. But because modern 2037clients request inlined images and other data via parallel requests (usually 2038up to four parallel requests are common) those requests are served by 2039<em>different</em> pre-forked server processes. Here an inter-process cache 2040helps to avoid unnecessary session handshakes.</p> 2041<p> 2042The following five storage <em>type</em>s are currently supported:</p> 2043<ul> 2044<li><code>none</code> 2045 2046 <p>This disables the global/inter-process Session Cache. This 2047 will incur a noticeable speed penalty and may cause problems if 2048 using certain browsers, particularly if client certificates are 2049 enabled. This setting is not recommended.</p></li> 2050 2051<li><code>nonenotnull</code> 2052 2053 <p>This disables any global/inter-process Session Cache. However 2054 it does force OpenSSL to send a non-null session ID to 2055 accommodate buggy clients that require one.</p></li> 2056 2057<li><code>dbm:/path/to/datafile</code> 2058 2059 <p>This makes use of a DBM hashfile on the local disk to 2060 synchronize the local OpenSSL memory caches of the server 2061 processes. This session cache may suffer reliability issues under 2062 high load. To use this, ensure that 2063 <code class="module"><a href="/mod/mod_socache_dbm.html">mod_socache_dbm</a></code> is loaded.</p></li> 2064 2065<li><code>shmcb:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>] 2066 2067 <p>This makes use of a high-performance cyclic buffer 2068 (approx. <em>size</em> bytes in size) inside a shared memory 2069 segment in RAM (established via <code>/path/to/datafile</code>) to 2070 synchronize the local OpenSSL memory caches of the server 2071 processes. This is the recommended session cache. To use this, 2072 ensure that <code class="module"><a href="/mod/mod_socache_shmcb.html">mod_socache_shmcb</a></code> is loaded.</p></li> 2073 2074<li><code>dc:UNIX:/path/to/socket</code> 2075 2076 <p>This makes use of the <a href="http://www.distcache.org/">distcache</a> distributed session 2077 caching libraries. The argument should specify the location of 2078 the server or proxy to be used using the distcache address syntax; 2079 for example, <code>UNIX:/path/to/socket</code> specifies a UNIX 2080 domain socket (typically a local dc_client proxy); 2081 <code>IP:server.example.com:9001</code> specifies an IP 2082 address. To use this, ensure that 2083 <code class="module"><a href="/mod/mod_socache_dc.html">mod_socache_dc</a></code> is loaded.</p></li> 2084 2085</ul> 2086 2087<div class="example"><h3>Examples</h3><pre class="prettyprint lang-config">SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data 2088SSLSessionCache shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)</pre> 2089</div> 2090 2091<p>The <code>ssl-cache</code> mutex is used to serialize access to 2092the session cache to prevent corruption. This mutex can be configured 2093using the <code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p> 2094 2095</div> 2096<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2097<div class="directive-section"><h2><a name="SSLSessionCacheTimeout" id="SSLSessionCacheTimeout">SSLSessionCacheTimeout</a> <a name="sslsessioncachetimeout" id="sslsessioncachetimeout">Directive</a></h2> 2098<table class="directive"> 2099<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before an SSL session expires 2100in the Session Cache</td></tr> 2101<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCacheTimeout <em>seconds</em></code></td></tr> 2102<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCacheTimeout 300</code></td></tr> 2103<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2104<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2105<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2106</table> 2107<p> 2108This directive sets the timeout in seconds for the information stored in the 2109global/inter-process SSL Session Cache and the OpenSSL internal memory cache. 2110It can be set as low as 15 for testing, but should be set to higher 2111values like 300 in real life.</p> 2112<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLSessionCacheTimeout 600</pre> 2113</div> 2114 2115</div> 2116<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2117<div class="directive-section"><h2><a name="SSLSessionTicketKeyFile" id="SSLSessionTicketKeyFile">SSLSessionTicketKeyFile</a> <a name="sslsessionticketkeyfile" id="sslsessionticketkeyfile">Directive</a></h2> 2118<table class="directive"> 2119<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Persistent encryption/decryption key for TLS session tickets</td></tr> 2120<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionTicketKeyFile <em>file-path</em></code></td></tr> 2121<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2122<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2123<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2124<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later</td></tr> 2125</table> 2126<p>Optionally configures a secret key for encrypting and decrypting 2127TLS session tickets, as defined in 2128<a href="http://www.ietf.org/rfc/rfc5077.txt">RFC 5077</a>. 2129Primarily suitable for clustered environments where TLS sessions information 2130should be shared between multiple nodes. For single-instance httpd setups, 2131it is recommended to <em>not</em> configure a ticket key file, but to 2132rely on (random) keys generated by mod_ssl at startup, instead.</p> 2133<p>The ticket key file must contain 48 bytes of random data, 2134preferrably created from a high-entropy source. On a Unix-based system, 2135a ticket key file can be created as follows:</p> 2136 2137<div class="example"><p><code> 2138dd if=/dev/random of=/path/to/file.tkey bs=1 count=48 2139</code></p></div> 2140 2141<p>Ticket keys should be rotated (replaced) on a frequent basis, 2142as this is the only way to invalidate an existing session ticket - 2143OpenSSL currently doesn't allow to specify a limit for ticket lifetimes.</p> 2144 2145<div class="warning"> 2146<p>The ticket key file contains sensitive keying material and should 2147be protected with file permissions similar to those used for 2148<code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>.</p> 2149</div> 2150 2151</div> 2152<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2153<div class="directive-section"><h2><a name="SSLSRPUnknownUserSeed" id="SSLSRPUnknownUserSeed">SSLSRPUnknownUserSeed</a> <a name="sslsrpunknownuserseed" id="sslsrpunknownuserseed">Directive</a></h2> 2154<table class="directive"> 2155<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SRP unknown user seed</td></tr> 2156<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSRPUnknownUserSeed <em>secret-string</em></code></td></tr> 2157<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2158<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2159<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2160<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or 2161later</td></tr> 2162</table> 2163<p> 2164This directive sets the seed used to fake SRP user parameters for unknown 2165users, to avoid leaking whether a given user exists. Specify a secret 2166string. If this directive is not used, then Apache will return the 2167UNKNOWN_PSK_IDENTITY alert to clients who specify an unknown username. 2168</p> 2169<div class="example"><h3>Example</h3><p><code> 2170SSLSRPUnknownUserSeed "secret" 2171</code></p></div> 2172 2173</div> 2174<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2175<div class="directive-section"><h2><a name="SSLSRPVerifierFile" id="SSLSRPVerifierFile">SSLSRPVerifierFile</a> <a name="sslsrpverifierfile" id="sslsrpverifierfile">Directive</a></h2> 2176<table class="directive"> 2177<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Path to SRP verifier file</td></tr> 2178<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSRPVerifierFile <em>file-path</em></code></td></tr> 2179<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2180<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2181<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2182<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or 2183later</td></tr> 2184</table> 2185<p> 2186This directive enables TLS-SRP and sets the path to the OpenSSL SRP (Secure 2187Remote Password) verifier file containing TLS-SRP usernames, verifiers, salts, 2188and group parameters.</p> 2189<div class="example"><h3>Example</h3><p><code> 2190SSLSRPVerifierFile "/path/to/file.srpv" 2191</code></p></div> 2192<p> 2193The verifier file can be created with the <code>openssl</code> command line 2194utility:</p> 2195<div class="example"><h3>Creating the SRP verifier file</h3><p><code> 2196openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username 2197</code></p></div> 2198<p> The value given with the optional <code>-userinfo</code> parameter is 2199avalable in the <code>SSL_SRP_USERINFO</code> request environment variable.</p> 2200 2201 2202</div> 2203<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2204<div class="directive-section"><h2><a name="SSLStaplingCache" id="SSLStaplingCache">SSLStaplingCache</a> <a name="sslstaplingcache" id="sslstaplingcache">Directive</a></h2> 2205<table class="directive"> 2206<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the OCSP stapling cache</td></tr> 2207<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingCache <em>type</em></code></td></tr> 2208<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 2209<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2210<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2211<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2212</table> 2213<p>Configures the cache used to store OCSP responses which get included 2214in the TLS handshake if <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> 2215is enabled. Configuration of a cache is mandatory for OCSP stapling. 2216With the exception of <code>none</code> and <code>nonenotnull</code>, 2217the same storage types are supported as with 2218<code class="directive"><a href="#sslsessioncache">SSLSessionCache</a></code>.</p> 2219 2220</div> 2221<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2222<div class="directive-section"><h2><a name="SSLStaplingErrorCacheTimeout" id="SSLStaplingErrorCacheTimeout">SSLStaplingErrorCacheTimeout</a> <a name="sslstaplingerrorcachetimeout" id="sslstaplingerrorcachetimeout">Directive</a></h2> 2223<table class="directive"> 2224<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before expiring invalid responses in the OCSP stapling cache</td></tr> 2225<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingErrorCacheTimeout <em>seconds</em></code></td></tr> 2226<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingErrorCacheTimeout 600</code></td></tr> 2227<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2228<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2229<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2230<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2231</table> 2232<p>Sets the timeout in seconds before <em>invalid</em> responses 2233in the OCSP stapling cache (configured through <code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code>) will expire. 2234To set the cache timeout for valid responses, see 2235<code class="directive"><a href="#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout</a></code>.</p> 2236 2237</div> 2238<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2239<div class="directive-section"><h2><a name="SSLStaplingFakeTryLater" id="SSLStaplingFakeTryLater">SSLStaplingFakeTryLater</a> <a name="sslstaplingfaketrylater" id="sslstaplingfaketrylater">Directive</a></h2> 2240<table class="directive"> 2241<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Synthesize "tryLater" responses for failed OCSP stapling queries</td></tr> 2242<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingFakeTryLater on|off</code></td></tr> 2243<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingFakeTryLater on</code></td></tr> 2244<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2245<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2246<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2247<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2248</table> 2249<p>When enabled and a query to an OCSP responder for stapling 2250purposes fails, mod_ssl will synthesize a "tryLater" response for the 2251client. Only effective if <code class="directive"><a href="#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors</a></code> 2252is also enabled.</p> 2253 2254</div> 2255<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2256<div class="directive-section"><h2><a name="SSLStaplingForceURL" id="SSLStaplingForceURL">SSLStaplingForceURL</a> <a name="sslstaplingforceurl" id="sslstaplingforceurl">Directive</a></h2> 2257<table class="directive"> 2258<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override the OCSP responder URI specified in the certificate's AIA extension</td></tr> 2259<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingForceURL <em>uri</em></code></td></tr> 2260<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2261<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2262<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2263<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2264</table> 2265<p>This directive overrides the URI of an OCSP responder as obtained from 2266the authorityInfoAccess (AIA) extension of the certificate. 2267Of potential use when going through a proxy for retrieving OCSP queries.</p> 2268 2269</div> 2270<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2271<div class="directive-section"><h2><a name="SSLStaplingResponderTimeout" id="SSLStaplingResponderTimeout">SSLStaplingResponderTimeout</a> <a name="sslstaplingrespondertimeout" id="sslstaplingrespondertimeout">Directive</a></h2> 2272<table class="directive"> 2273<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout for OCSP stapling queries</td></tr> 2274<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponderTimeout <em>seconds</em></code></td></tr> 2275<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponderTimeout 10</code></td></tr> 2276<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2277<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2278<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2279<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2280</table> 2281<p>This option sets the timeout for queries to OCSP responders when 2282<code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is enabled 2283and mod_ssl is querying a responder for OCSP stapling purposes.</p> 2284 2285</div> 2286<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2287<div class="directive-section"><h2><a name="SSLStaplingResponseMaxAge" id="SSLStaplingResponseMaxAge">SSLStaplingResponseMaxAge</a> <a name="sslstaplingresponsemaxage" id="sslstaplingresponsemaxage">Directive</a></h2> 2288<table class="directive"> 2289<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable age for OCSP stapling responses</td></tr> 2290<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponseMaxAge <em>seconds</em></code></td></tr> 2291<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponseMaxAge -1</code></td></tr> 2292<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2293<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2294<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2295<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2296</table> 2297<p>This option sets the maximum allowable age ("freshness") when 2298considering OCSP responses for stapling purposes, i.e. when 2299<code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is turned on. 2300The default value (<code>-1</code>) does not enforce a maximum age, 2301which means that OCSP responses are considered valid as long as their 2302<code>nextUpdate</code> field is in the future.</p> 2303 2304</div> 2305<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2306<div class="directive-section"><h2><a name="SSLStaplingResponseTimeSkew" id="SSLStaplingResponseTimeSkew">SSLStaplingResponseTimeSkew</a> <a name="sslstaplingresponsetimeskew" id="sslstaplingresponsetimeskew">Directive</a></h2> 2307<table class="directive"> 2308<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable time skew for OCSP stapling response validation</td></tr> 2309<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponseTimeSkew <em>seconds</em></code></td></tr> 2310<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponseTimeSkew 300</code></td></tr> 2311<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2312<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2313<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2314<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2315</table> 2316<p>This option sets the maximum allowable time skew when mod_ssl checks the 2317<code>thisUpdate</code> and <code>nextUpdate</code> fields of OCSP responses 2318which get included in the TLS handshake (OCSP stapling). Only applicable 2319if <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is turned on.</p> 2320 2321</div> 2322<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2323<div class="directive-section"><h2><a name="SSLStaplingReturnResponderErrors" id="SSLStaplingReturnResponderErrors">SSLStaplingReturnResponderErrors</a> <a name="sslstaplingreturnrespondererrors" id="sslstaplingreturnrespondererrors">Directive</a></h2> 2324<table class="directive"> 2325<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pass stapling related OCSP errors on to client</td></tr> 2326<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingReturnResponderErrors on|off</code></td></tr> 2327<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingReturnResponderErrors on</code></td></tr> 2328<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2329<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2330<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2331<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2332</table> 2333<p>When enabled, mod_ssl will pass responses from unsuccessful 2334stapling related OCSP queries (such as status errors, expired responses etc.) 2335on to the client. If set to <code>off</code>, no stapled responses 2336for failed queries will be included in the TLS handshake.</p> 2337 2338</div> 2339<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2340<div class="directive-section"><h2><a name="SSLStaplingStandardCacheTimeout" id="SSLStaplingStandardCacheTimeout">SSLStaplingStandardCacheTimeout</a> <a name="sslstaplingstandardcachetimeout" id="sslstaplingstandardcachetimeout">Directive</a></h2> 2341<table class="directive"> 2342<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before expiring responses in the OCSP stapling cache</td></tr> 2343<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingStandardCacheTimeout <em>seconds</em></code></td></tr> 2344<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingStandardCacheTimeout 3600</code></td></tr> 2345<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2346<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2347<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2348<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2349</table> 2350<p>Sets the timeout in seconds before responses in the OCSP stapling cache 2351(configured through <code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code>) 2352will expire. This directive applies to <em>valid</em> responses, while 2353<code class="directive"><a href="#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout</a></code> is 2354used for controlling the timeout for invalid/unavailable responses. 2355</p> 2356 2357</div> 2358<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2359<div class="directive-section"><h2><a name="SSLStrictSNIVHostCheck" id="SSLStrictSNIVHostCheck">SSLStrictSNIVHostCheck</a> <a name="sslstrictsnivhostcheck" id="sslstrictsnivhostcheck">Directive</a></h2> 2360<table class="directive"> 2361<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to allow non-SNI clients to access a name-based virtual 2362host. 2363</td></tr> 2364<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStrictSNIVHostCheck on|off</code></td></tr> 2365<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStrictSNIVHostCheck off</code></td></tr> 2366<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2367<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2368<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2369<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.2.12 and later</td></tr> 2370</table> 2371<p> 2372This directive sets whether a non-SNI client is allowed to access a name-based 2373virtual host. If set to <code>on</code> in the default name-based virtual 2374host, clients that are SNI unaware will not be allowed to access <em>any</em> 2375virtual host, belonging to this particular IP / port combination. 2376If set to <code>on</code> in any other virtual host, SNI unaware clients 2377are not allowed to access this particular virtual host. 2378</p> 2379 2380<div class="warning"><p> 2381This option is only available if httpd was compiled against an SNI capable 2382version of OpenSSL. 2383</p></div> 2384 2385<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLStrictSNIVHostCheck on</pre> 2386</div> 2387 2388</div> 2389<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2390<div class="directive-section"><h2><a name="SSLUserName" id="SSLUserName">SSLUserName</a> <a name="sslusername" id="sslusername">Directive</a></h2> 2391<table class="directive"> 2392<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Variable name to determine user name</td></tr> 2393<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLUserName <em>varname</em></code></td></tr> 2394<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, directory, .htaccess</td></tr> 2395<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 2396<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2397<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2398</table> 2399<p> 2400This directive sets the "user" field in the Apache request object. 2401This is used by lower modules to identify the user with a character 2402string. In particular, this may cause the environment variable 2403<code>REMOTE_USER</code> to be set. The <em>varname</em> can be 2404any of the <a href="#envvars">SSL environment variables</a>.</p> 2405 2406<p>Note that this directive has no effect if the 2407<code>FakeBasicAuth</code> option is used (see <a href="#ssloptions">SSLOptions</a>).</p> 2408 2409<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLUserName SSL_CLIENT_S_DN_CN</pre> 2410</div> 2411 2412</div> 2413<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2414<div class="directive-section"><h2><a name="SSLUseStapling" id="SSLUseStapling">SSLUseStapling</a> <a name="sslusestapling" id="sslusestapling">Directive</a></h2> 2415<table class="directive"> 2416<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable stapling of OCSP responses in the TLS handshake</td></tr> 2417<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLUseStapling on|off</code></td></tr> 2418<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLUseStapling off</code></td></tr> 2419<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 2420<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2421<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2422<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.3.3 and later, if using OpenSSL 0.9.8h or later</td></tr> 2423</table> 2424<p>This option enables OCSP stapling, as defined by the "Certificate 2425Status Request" TLS extension specified in RFC 6066. If enabled (and 2426requested by the client), mod_ssl will include an OCSP response 2427for its own certificate in the TLS handshake. Configuring an 2428<code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code> is a 2429prerequisite for enabling OCSP stapling.</p> 2430 2431<p>OCSP stapling relieves the client of querying the OCSP responder 2432on its own, but it should be noted that with the RFC 6066 specification, 2433the server's <code>CertificateStatus</code> reply may only include an 2434OCSP response for a single cert. For server certificates with intermediate 2435CA certificates in their chain (the typical case nowadays), 2436stapling in its current implementation therefore only partially achieves the 2437stated goal of "saving roundtrips and resources" - see also 2438<a href="http://www.ietf.org/rfc/rfc6961.txt">RFC 6961</a> 2439(TLS Multiple Certificate Status Extension). 2440</p> 2441 2442</div> 2443<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2444<div class="directive-section"><h2><a name="SSLVerifyClient" id="SSLVerifyClient">SSLVerifyClient</a> <a name="sslverifyclient" id="sslverifyclient">Directive</a></h2> 2445<table class="directive"> 2446<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of Client Certificate verification</td></tr> 2447<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyClient <em>level</em></code></td></tr> 2448<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyClient none</code></td></tr> 2449<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 2450<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 2451<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2452<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2453</table> 2454<p> 2455This directive sets the Certificate verification level for the Client 2456Authentication. Notice that this directive can be used both in per-server and 2457per-directory context. In per-server context it applies to the client 2458authentication process used in the standard SSL handshake when a connection is 2459established. In per-directory context it forces a SSL renegotiation with the 2460reconfigured client verification level after the HTTP request was read but 2461before the HTTP response is sent.</p> 2462<p> 2463The following levels are available for <em>level</em>:</p> 2464<ul> 2465<li><strong>none</strong>: 2466 no client Certificate is required at all</li> 2467<li><strong>optional</strong>: 2468 the client <em>may</em> present a valid Certificate</li> 2469<li><strong>require</strong>: 2470 the client <em>has to</em> present a valid Certificate</li> 2471<li><strong>optional_no_ca</strong>: 2472 the client may present a valid Certificate<br /> 2473 but it need not to be (successfully) verifiable.</li> 2474</ul> 2475<p>In practice only levels <strong>none</strong> and 2476<strong>require</strong> are really interesting, because level 2477<strong>optional</strong> doesn't work with all browsers and level 2478<strong>optional_no_ca</strong> is actually against the idea of 2479authentication (but can be used to establish SSL test pages, etc.)</p> 2480<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyClient require</pre> 2481</div> 2482 2483</div> 2484<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 2485<div class="directive-section"><h2><a name="SSLVerifyDepth" id="SSLVerifyDepth">SSLVerifyDepth</a> <a name="sslverifydepth" id="sslverifydepth">Directive</a></h2> 2486<table class="directive"> 2487<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Client 2488Certificate verification</td></tr> 2489<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyDepth <em>number</em></code></td></tr> 2490<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyDepth 1</code></td></tr> 2491<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 2492<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> 2493<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 2494<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> 2495</table> 2496<p> 2497This directive sets how deeply mod_ssl should verify before deciding that the 2498clients don't have a valid certificate. Notice that this directive can be 2499used both in per-server and per-directory context. In per-server context it 2500applies to the client authentication process used in the standard SSL 2501handshake when a connection is established. In per-directory context it forces 2502a SSL renegotiation with the reconfigured client verification depth after the 2503HTTP request was read but before the HTTP response is sent.</p> 2504<p> 2505The depth actually is the maximum number of intermediate certificate issuers, 2506i.e. the number of CA certificates which are max allowed to be followed while 2507verifying the client certificate. A depth of 0 means that self-signed client 2508certificates are accepted only, the default depth of 1 means the client 2509certificate can be self-signed or has to be signed by a CA which is directly 2510known to the server (i.e. the CA's certificate is under 2511<code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>), etc.</p> 2512<div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyDepth 10</pre> 2513</div> 2514 2515</div> 2516</div> 2517<div class="bottomlang"> 2518<p><span>Available Languages: </span><a href="/en/mod/mod_ssl.html" title="English"> en </a> | 2519<a href="/fr/mod/mod_ssl.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 2520</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 2521<script type="text/javascript"><!--//--><![CDATA[//><!-- 2522var comments_shortname = 'httpd'; 2523var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_ssl.html'; 2524(function(w, d) { 2525 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 2526 d.write('<div id="comments_thread"><\/div>'); 2527 var s = d.createElement('script'); 2528 s.type = 'text/javascript'; 2529 s.async = true; 2530 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 2531 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 2532 } 2533 else { 2534 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 2535 } 2536})(window, document); 2537//--><!]]></script></div><div id="footer"> 2538<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 2539<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 2540if (typeof(prettyPrint) !== 'undefined') { 2541 prettyPrint(); 2542} 2543//--><!]]></script> 2544</body></html>
