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