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