| <!DOCTYPE html SYSTEM "about:legacy-compat"> | |
| <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"> | |
| <meta content="width=device-width, initial-scale=1" name="viewport"> | |
| <!-- | |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | |
| This file is generated from xml source: DO NOT EDIT | |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | |
| --> | |
| <title>mod_ssl - Apache HTTP Server Version 2.5</title> | |
| <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet"> | |
| <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size"> | |
| <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"> | |
| <script src="../style/scripts/prettify.min.js"> | |
| </script> | |
| <link href="../images/favicon.png" rel="shortcut icon"></head> | |
| <body> | |
| <div id="page-header"> | |
| <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="https://cwiki.apache.org/confluence/display/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a> | <a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2">Report a bug</a></p> | |
| <p class="apache">Apache HTTP Server Version 2.5</p> | |
| <img alt="" src="../images/feather.png"></div> | |
| <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif"></a></div> | |
| <div id="path"> | |
| <a href="https://www.apache.org/">Apache</a> > <a href="https://httpd.apache.org/">HTTP Server</a> > <a href="https://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div> | |
| <div id="page-content"> | |
| <div id="preamble"><h1>Apache Module mod_ssl</h1> | |
| <button aria-label="Toggle language list" class="lang-toggle"><svg xmlns="http://www.w3.org/2000/svg" stroke-width="2" stroke="currentColor" fill="none" viewBox="0 0 24 24" height="16" width="16"><circle r="10" cy="12" cx="12"/><line y2="12" x2="22" y1="12" x1="2"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg></button> | |
| <div class="toplang"> | |
| <p><span>Available Languages: </span><a href="../en/mod/mod_ssl.html" title="English"> en </a> | | |
| <a href="../es/mod/mod_ssl.html" hreflang="es" rel="alternate" title="Español"> es </a> | | |
| <a href="../fr/mod/mod_ssl.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> | |
| </div> | |
| <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Strong cryptography using the Secure Sockets | |
| Layer (SSL) and Transport Layer Security (TLS) protocols</td></tr> | |
| <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>ssl_module</td></tr> | |
| <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_ssl.c</td></tr></table> | |
| <h3>Summary</h3> | |
| <p>This module provides SSL v3 and TLS v1.x support for the Apache | |
| HTTP Server. SSL v2 is no longer supported.</p> | |
| <p>This module relies on <a href="https://www.openssl.org/">OpenSSL</a> | |
| to provide the cryptographic engine.</p> | |
| <p>Further details, discussion, and examples are provided in the | |
| <a href="../ssl/">SSL documentation</a>.</p> | |
| </div> | |
| <div id="quickview"><h3>Topics</h3> | |
| <ul id="topics"> | |
| <li><img alt="" src="../images/down.gif"> <a href="#envvars">Environment Variables</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#logformats">Custom Log Formats</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#notes">Request Notes</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#expressionparser">Expression Parser Extension</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#authzproviders">Authorization providers for use with Require</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#timeouts">Connection and Handshake Timeouts</a></li> | |
| </ul><h3 class="directives">Directives</h3> | |
| <ul id="toc"> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcacertificatefile">SSLCACertificateFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcacertificatepath">SSLCACertificatePath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcadnrequestfile">SSLCADNRequestFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcadnrequestpath">SSLCADNRequestPath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcarevocationcheck">SSLCARevocationCheck</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcarevocationfile">SSLCARevocationFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcarevocationpath">SSLCARevocationPath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcertificatechainfile">SSLCertificateChainFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcertificatefile">SSLCertificateFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslciphersuite">SSLCipherSuite</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslclienthellovars">SSLClientHelloVars</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcompression">SSLCompression</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslcryptodevice">SSLCryptoDevice</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslechkeydir">SSLECHKeyDir</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslengine">SSLEngine</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslfips">SSLFIPS</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslhonorcipherorder">SSLHonorCipherOrder</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspenable">SSLOCSPEnable</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspnoverify">SSLOCSPNoverify</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspproxyurl">SSLOCSPProxyURL</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocsprespondercertificatefile">SSLOCSPResponderCertificateFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocsprespondertimeout">SSLOCSPResponderTimeout</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspresponsemaxage">SSLOCSPResponseMaxAge</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspresponsetimeskew">SSLOCSPResponseTimeSkew</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslocspuserequestnonce">SSLOCSPUseRequestNonce</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslopensslconfcmd">SSLOpenSSLConfCmd</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#ssloptions">SSLOptions</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslpassphrasedialog">SSLPassPhraseDialog</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslpolicy">SSLPolicy</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslprotocol">SSLProtocol</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycacertificatefile">SSLProxyCACertificateFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycarevocationcheck">SSLProxyCARevocationCheck</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycheckpeerexpire">SSLProxyCheckPeerExpire</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxycheckpeername">SSLProxyCheckPeerName</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxyciphersuite">SSLProxyCipherSuite</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxyengine">SSLProxyEngine</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxymachinecertificatepath">SSLProxyMachineCertificatePath</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxyprotocol">SSLProxyProtocol</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxystoreuri">SSLProxyStoreURI</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxytrusturi">SSLProxyTrustURI</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxyverify">SSLProxyVerify</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslproxyverifydepth">SSLProxyVerifyDepth</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslrandomseed">SSLRandomSeed</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslrenegbuffersize">SSLRenegBufferSize</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslrequire">SSLRequire</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslrequiressl">SSLRequireSSL</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsessioncache">SSLSessionCache</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsessioncachetimeout">SSLSessionCacheTimeout</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsessionticketkeyfile">SSLSessionTicketKeyFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsessiontickets">SSLSessionTickets</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsrpunknownuserseed">SSLSRPUnknownUserSeed</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslsrpverifierfile">SSLSRPVerifierFile</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingcache">SSLStaplingCache</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingfaketrylater">SSLStaplingFakeTryLater</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingforceurl">SSLStaplingForceURL</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingrespondertimeout">SSLStaplingResponderTimeout</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingresponsemaxage">SSLStaplingResponseMaxAge</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingresponsetimeskew">SSLStaplingResponseTimeSkew</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstoreuri">SSLStoreURI</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslstrictsnivhostcheck">SSLStrictSNIVHostCheck</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#ssltrustrequesturi">SSLTrustRequestURI</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#ssltrusturi">SSLTrustURI</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslusername">SSLUserName</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslusestapling">SSLUseStapling</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslverifyclient">SSLVerifyClient</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslverifydepth">SSLVerifyDepth</a></li> | |
| <li><img alt="" src="../images/down.gif"> <a href="#sslvhostsnipolicy">SSLVHostSNIPolicy</a></li> | |
| </ul> | |
| <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_ssl">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_ssl">Report a bug</a></li></ul><h3>See also</h3> | |
| <ul class="seealso"> | |
| <li><code class="directive"><a href="../mod/mod_reqtimeout.html#requestreadtimeout">RequestReadTimeout</a></code></li> | |
| </ul></div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="envvars">Environment Variables <a title="Permanent link" href="#envvars" class="permalink">¶</a></h2> | |
| <p>This module can be configured to provide several items of SSL information | |
| as additional environment variables to the SSI and CGI namespace. Except for | |
| <code>HTTPS</code> and <code>SSL_TLS_SNI</code> which are always defined, this | |
| information is not provided by default for performance reasons. (See | |
| <code class="directive"><a href="#ssloptions">SSLOptions</a></code> <code>StdEnvVars</code>, below) | |
| The generated variables | |
| are listed in the table below. For backward compatibility the information can | |
| be made available under different names, too. Look in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the | |
| compatibility variables.</p> | |
| <table class="bordered"><tr class="header"> | |
| <th><a name="table3">Variable Name</a></th> | |
| <th>Value Type</th> | |
| <th>Description</th> | |
| </tr> | |
| <tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> | |
| <tr class="odd"><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2)</td></tr> | |
| <tr><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> | |
| <tr class="odd"><td><code>SSL_SESSION_RESUMED</code></td> <td>string</td> <td>Initial or Resumed SSL Session. Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use</td></tr> | |
| <tr><td><code>SSL_SECURE_RENEG</code></td> <td>string</td> <td><code>true</code> if secure renegotiation is supported, else <code>false</code></td></tr> | |
| <tr class="odd"><td><code>SSL_SHARED_CIPHERS</code></td> <td>string</td> <td>Colon separated list of shared ciphers (i.e. the subset of ciphers that are configured on both server and on the client)</td></tr> | |
| <tr><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The name of the cipher agreed between client and server</td></tr> | |
| <tr class="odd"><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> | |
| <tr><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> | |
| <tr class="odd"><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> | |
| <tr><td><code>SSL_COMPRESS_METHOD</code></td> <td>string</td> <td>SSL compression method negotiated</td></tr> | |
| <tr class="odd"><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> | |
| <tr><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> | |
| <tr><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> | |
| <tr><td><code>SSL_CLIENT_S_DN_</code><var>x509</var></td> <td>string</td> <td>Component of client's Subject DN</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_SAN_Email_</code><var>n</var></td> <td>string</td> <td>Client certificate's subjectAltName extension entries of type rfc822Name</td></tr> | |
| <tr><td><code>SSL_CLIENT_SAN_DNS_</code><var>n</var></td> <td>string</td> <td>Client certificate's subjectAltName extension entries of type dNSName</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_SAN_OTHER_msUPN_</code><var>n</var></td> <td>string</td> <td>Client certificate's subjectAltName extension entries of type otherName, Microsoft User Principal Name form (OID 1.3.6.1.4.1.311.20.2.3)</td></tr> | |
| <tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_I_DN_</code><var>x509</var></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> | |
| <tr><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> | |
| <tr><td><code>SSL_CLIENT_V_REMAIN</code></td> <td>string</td> <td>Number of days until client's certificate expires</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> | |
| <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> | |
| <tr class="odd"><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> | |
| <tr><td><code>SSL_CLIENT_CERT_CHAIN_</code><var>n</var></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENT_CERT_RFC4523_CEA</code></td> <td>string</td> <td>Serial number and issuer of the certificate. The format matches that of the CertificateExactAssertion in RFC4523</td></tr> | |
| <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><var>reason</var></td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> | |
| <tr><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> | |
| <tr><td><code>SSL_SERVER_SAN_Email_</code><var>n</var></td> <td>string</td> <td>Server certificate's subjectAltName extension entries of type rfc822Name</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_SAN_DNS_</code><var>n</var></td> <td>string</td> <td>Server certificate's subjectAltName extension entries of type dNSName</td></tr> | |
| <tr><td><code>SSL_SERVER_SAN_OTHER_dnsSRV_</code><var>n</var></td> <td>string</td> <td>Server certificate's subjectAltName extension entries of type otherName, SRVName form (OID 1.3.6.1.5.5.7.8.7, RFC 4985)</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_S_DN_</code><var>x509</var></td> <td>string</td> <td>Component of server's Subject DN</td></tr> | |
| <tr><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_I_DN_</code><var>x509</var></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> | |
| <tr><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> | |
| <tr><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> | |
| <tr><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> | |
| <tr class="odd"><td><code>SSL_SRP_USER</code></td> <td>string</td> <td>SRP username</td></tr> | |
| <tr><td><code>SSL_SRP_USERINFO</code></td> <td>string</td> <td>SRP user info</td></tr> | |
| <tr class="odd"><td><code>SSL_TLS_SNI</code></td> <td>string</td> <td>Contents of the SNI TLS extension (if supplied with ClientHello)</td></tr> | |
| <tr><td><code>SSL_HANDSHAKE_RTT</code></td> <td>number</td> <td>Round-trip time of TLS handshake in microseconds including endpoint processing (set to empty string if OpenSSL version prior to 3.2 or if round-trip time can not be determined)</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENTHELLO_VERSION</code></td> <td>string</td> <td>Version field (legacy) from ClientHello as four hex encoded characters</td></tr> | |
| <tr><td><code>SSL_CLIENTHELLO_CIPHERS</code></td> <td>string</td> <td>Cipher Suites from ClientHello as four hex encoded characters per item</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENTHELLO_EXTENSIONS</code></td> <td>string</td> <td>Extension IDs from ClientHello as four hex encoded characters per item</td></tr> | |
| <tr><td><code>SSL_CLIENTHELLO_GROUPS</code></td> <td>string</td> <td>Value of Supported Groups extension (10) from ClientHello as four hex encoded characters per item</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENTHELLO_EC_FORMATS</code></td> <td>string</td> <td>Value of EC Point Formats extension (11) from ClientHello as two hex encoded characters per item</td></tr> | |
| <tr><td><code>SSL_CLIENTHELLO_SIG_ALGOS</code></td> <td>string</td> <td>Value of Signature Algorithms extension (13) from ClientHello as four hex encoded characters per item</td></tr> | |
| <tr class="odd"><td><code>SSL_CLIENTHELLO_ALPN</code></td> <td>string</td> <td>Value of ALPN extension (16) from ClientHello as hex encoded string including leading string lengths</td></tr> | |
| <tr><td><code>SSL_CLIENTHELLO_VERSIONS</code></td> <td>string</td> <td>Value of Supported Versions extension (43) from ClientHello as four hex encoded characters per item</td></tr> | |
| <tr class="odd"><td><code>SSL_ECH_STATUS</code></td> <td>string</td> <td><code>success</code> means that others also mean what they say</td></tr> | |
| <tr><td><code>SSL_ECH_INNER_SNI</code></td> <td>string</td> <td>SNI value that was encrypted in ECH (or `NONE`)</td></tr> | |
| <tr class="odd"><td><code>SSL_ECH_OUTER_SNI</code></td> <td>string</td> <td>SNI value that was seen in plaintext SNI (or `NONE`)</td></tr> | |
| </table> | |
| <p><var>x509</var> specifies a component of an X.509 DN; one of | |
| <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code>. In httpd 2.2.0 and | |
| later, <var>x509</var> may also include a numeric <code>_n</code> | |
| suffix. If the DN in question contains multiple attributes of the | |
| same name, this suffix is used as a zero-based index to select a | |
| particular attribute. For example, where the server certificate | |
| subject DN included two OU attributes, <code>SSL_SERVER_S_DN_OU_0</code> | |
| and | |
| <code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each. A | |
| variable name without a <code>_n</code> suffix is equivalent to that | |
| name with a <code>_0</code> suffix; the first (or only) attribute. | |
| When the environment table is populated using | |
| the <code>StdEnvVars</code> option of | |
| the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> directive, the | |
| first (or only) attribute of any DN is added only under a non-suffixed | |
| name; i.e. no <code>_0</code> suffixed entries are added.</p> | |
| <p>In httpd 2.4.32 and later, an optional <var>_RAW</var> suffix may be | |
| added to <var>x509</var> in a DN component, to suppress conversion of | |
| the attribute value to UTF-8. This must be placed after the index | |
| suffix (if any). For example, <code>SSL_SERVER_S_DN_OU_RAW</code> or | |
| <code>SSL_SERVER_S_DN_OU_0_RAW</code> could be used.</p> | |
| <p>The format of the <var>*_DN</var> variables has changed in Apache HTTPD | |
| 2.3.11. See the <code>LegacyDNStringFormat</code> option for | |
| <code class="directive"><a href="#ssloptions">SSLOptions</a></code> for details.</p> | |
| <p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1 | |
| and later.</p> | |
| <p>The <code>SSL_CLIENTHELLO_*</code> variables require the directive | |
| <code class="directive"><a href="#sslclienthellovars">SSLClientHelloVars</a></code> to be | |
| enabled or they will not be populated.</p> | |
| <p>A number of additional environment variables can also be used | |
| in <code class="directive">SSLRequire</code> expressions, or in custom log | |
| formats:</p> | |
| <div class="note"><pre>HTTP_USER_AGENT PATH_INFO AUTH_TYPE | |
| HTTP_REFERER QUERY_STRING SERVER_SOFTWARE | |
| HTTP_COOKIE REMOTE_HOST API_VERSION | |
| HTTP_FORWARDED REMOTE_IDENT TIME_YEAR | |
| HTTP_HOST IS_SUBREQ TIME_MON | |
| HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY | |
| HTTP_ACCEPT SERVER_ADMIN TIME_HOUR | |
| THE_REQUEST SERVER_NAME TIME_MIN | |
| REQUEST_FILENAME SERVER_PORT TIME_SEC | |
| REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY | |
| REQUEST_SCHEME REMOTE_ADDR TIME | |
| REQUEST_URI REMOTE_USER</pre></div> | |
| <p>In these contexts, two special formats can also be used:</p> | |
| <dl> | |
| <dt><code>ENV:<var>variablename</var></code></dt> | |
| <dd>This will expand to the standard environment | |
| variable <var>variablename</var>.</dd> | |
| <dt><code>HTTP:<var>headername</var></code></dt> | |
| <dd>This will expand to the value of the request header with name | |
| <var>headername</var>.</dd> | |
| </dl> | |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="logformats">Custom Log Formats <a title="Permanent link" href="#logformats" class="permalink">¶</a></h2> | |
| <p>When <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least | |
| loaded (under DSO situation) additional functions exist for the <a href="mod_log_config.html#formats">Custom Log Format</a> of | |
| <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>. First there is an | |
| additional ``<code>%{</code><var>varname</var><code>}x</code>'' | |
| eXtension format function which can be used to expand any variables | |
| provided by any module, especially those provided by mod_ssl which can | |
| you find in the above table.</p> | |
| <p> | |
| For backward compatibility there is additionally a special | |
| ``<code>%{</code><var>name</var><code>}c</code>'' cryptography format function | |
| provided. Information about this function is provided in the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"</pre> | |
| </div> | |
| <p>These formats even work without setting the <code>StdEnvVars</code> | |
| option of the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> | |
| directive.</p> | |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="notes">Request Notes <a title="Permanent link" href="#notes" class="permalink">¶</a></h2> | |
| <p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> sets "notes" for the request which can be | |
| used in logging with the <code>%{<var>name</var>}n</code> format | |
| string in <code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code>.</p> | |
| <p>The notes supported are as follows:</p> | |
| <dl> | |
| <dt><code>ssl-access-forbidden</code></dt> | |
| <dd>This note is set to the value <code>1</code> if access was | |
| denied due to an <code class="directive">SSLRequire</code> | |
| or <code class="directive">SSLRequireSSL</code> directive.</dd> | |
| <dt><code>ssl-secure-reneg</code></dt> | |
| <dd>If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built against a version of | |
| OpenSSL which supports the secure renegotiation extension, this note | |
| is set to the value <code>1</code> if SSL is in used for the current | |
| connection, and the client also supports the secure renegotiation | |
| extension. If the client does not support the secure renegotiation | |
| extension, the note is set to the value <code>0</code>. | |
| If <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is not built against a version of | |
| OpenSSL which supports secure renegotiation, or if SSL is not in use | |
| for the current connection, the note is not set.</dd> | |
| </dl> | |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="expressionparser">Expression Parser Extension <a title="Permanent link" href="#expressionparser" class="permalink">¶</a></h2> | |
| <p>When <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is built into Apache or at least | |
| loaded (under DSO situation) any <a name="envvars">variables</a> | |
| provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> can be used in expressions | |
| for the <a href="../expr.html">ap_expr Expression Parser</a>. | |
| The variables can be referenced using the syntax | |
| ``<code>%{</code><var>varname</var><code>}</code>''. Starting | |
| with version 2.4.18 one can also use the | |
| <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> style syntax | |
| ``<code>%{SSL:</code><var>varname</var><code>}</code>'' or | |
| the function style syntax | |
| ``<code>ssl(</code><var>varname</var><code>)</code>''.</p> | |
| <div class="example"><h3>Example (using <code class="module"><a href="../mod/mod_headers.html">mod_headers</a></code>)</h3><pre class="prettyprint lang-config">Header set X-SSL-PROTOCOL "expr=%{SSL_PROTOCOL}" | |
| Header set X-SSL-CIPHER "expr=%{SSL:SSL_CIPHER}"</pre> | |
| </div> | |
| <p>This feature even works without setting the <code>StdEnvVars</code> | |
| option of the <code class="directive"><a href="#ssloptions">SSLOptions</a></code> | |
| directive.</p> | |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="authzproviders">Authorization providers for use with Require <a title="Permanent link" href="#authzproviders" class="permalink">¶</a></h2> | |
| <p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> provides the following authorization providers | |
| for use with <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>'s | |
| <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive.</p> | |
| <h3 id="reqssl">Require ssl</h3> | |
| <p>The <code>ssl</code> provider denies access if a connection is not | |
| encrypted with SSL. Unlike the | |
| <code class="directive">SSLRequireSSL</code> directive, this can be | |
| combined with other <code class="directive">Require</code> directives in | |
| <code class="directive"><a href="../mod/mod_authz_core.html#requireany">RequireAny</a></code> or | |
| <code class="directive"><a href="../mod/mod_authz_core.html#requireall">RequireAll</a></code> blocks.</p> | |
| <pre class="prettyprint lang-config">Require ssl</pre> | |
| <h3 id="reqverifyclient">Require ssl-verify-client</h3> | |
| <p>The <code>ssl-verify-client</code> provider allows access if the | |
| user is authenticated with a valid client certificate. This is only | |
| useful if <code>SSLVerifyClient optional</code> is in effect.</p> | |
| <p>The following example grants access if the user is authenticated | |
| either with a client certificate or by username and password.</p> | |
| <pre class="prettyprint lang-config">Require ssl-verify-client | |
| Require valid-user</pre> | |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="section"> | |
| <h2 id="timeouts">Connection and Handshake Timeouts <a title="Permanent link" href="#timeouts" class="permalink">¶</a></h2> | |
| <p>A client may open a TLS connection, receive the server certificate, and | |
| then stall without completing the handshake or sending a request. The | |
| HTTP-level timeouts, such as <code class="directive"><a href="../mod/core.html#timeout">TimeOut</a></code>, | |
| do not reliably cover this situation, so the connection can be held open | |
| indefinitely.</p> | |
| <p>To limit the time a client may take to complete the TLS handshake, load | |
| <code class="module"><a href="../mod/mod_reqtimeout.html">mod_reqtimeout</a></code> and configure the <code>handshake</code> | |
| stage of <code class="directive"><a href="../mod/mod_reqtimeout.html#requestreadtimeout">RequestReadTimeout</a></code>:</p> | |
| <pre class="prettyprint lang-config">RequestReadTimeout handshake=5</pre> | |
| <p>The <code>handshake</code> stage is disabled by default and is available | |
| since httpd 2.4.39. See the | |
| <code class="directive"><a href="../mod/mod_reqtimeout.html#requestreadtimeout">RequestReadTimeout</a></code> | |
| documentation for details and more examples.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcacertificatefile"><span id="SSLCACertificateFile">SSLCACertificateFile</span> Directive <a title="Permanent link" href="#sslcacertificatefile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates | |
| for Client Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificateFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the <em>all-in-one</em> file where you can assemble the | |
| Certificates of Certification Authorities (CA) whose <em>clients</em> you deal | |
| with. These are used for Client Authentication. Such a file is simply the | |
| concatenation of the various PEM-encoded Certificate files, in order of | |
| preference. This can be used alternatively and/or additionally to | |
| <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The file is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcacertificatepath"><span id="SSLCACertificatePath">SSLCACertificatePath</span> Directive <a title="Permanent link" href="#sslcacertificatepath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for | |
| Client Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCACertificatePath <var>directory-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the directory where you keep the Certificates of | |
| Certification Authorities (CAs) whose clients you deal with. These are used to | |
| verify the client certificate on Client Authentication.</p> | |
| <p> | |
| The files in this directory have to be PEM-encoded and are accessed through | |
| hash filenames. So usually you can't just place the Certificate files | |
| there: you also have to create symbolic links named | |
| <var>hash-value</var><code>.N</code>. And you should always make sure this directory | |
| contains the appropriate symbolic links.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCACertificatePath "/usr/local/apache2/conf/ssl.crt/"</pre> | |
| </div> | |
| <p>The files in this directory are read at server startup, while the server | |
| is still running as <code>root</code> (before privilege dropping), so they | |
| may be owned by and readable only by <code>root</code>. The files are not | |
| re-read during normal operation; a server restart is required for changes | |
| to take effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcadnrequestfile"><span id="SSLCADNRequestFile">SSLCADNRequestFile</span> Directive <a title="Permanent link" href="#sslcadnrequestfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates | |
| for defining acceptable CA names</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>When a client certificate is requested by mod_ssl, a list of | |
| <em>acceptable Certificate Authority names</em> is sent to the client | |
| in the SSL handshake. These CA names can be used by the client to | |
| select an appropriate client certificate out of those it has | |
| available.</p> | |
| <p>If none of the directives <code class="directive">SSLCADNRequestFile</code>, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code>, or <code class="directive"><a href="#ssltrustrequesturi">SSLTrustRequestURI</a></code> are given, then the | |
| set of acceptable CA names sent to the client is the names of all the | |
| CA certificates given by the <code class="directive"><a href="#sslcacertificatefile">SSLCACertificateFile</a></code>, <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>, and <code class="directive"><a href="#ssltrusturi">SSLTrustURI</a></code> directives; in other | |
| words, the names of the CAs which will actually be used to verify the | |
| client certificate.</p> | |
| <p>In some circumstances, it is useful to be able to send a set of | |
| acceptable CA names which differs from the actual CAs used to verify | |
| the client certificate - for example, if the client certificates are | |
| signed by intermediate CAs. In such cases, <code class="directive">SSLCADNRequestFile</code>, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code>, and/or <code class="directive"><a href="#ssltrustrequesturi">SSLTrustRequestURI</a></code> can be used; the | |
| acceptable CA names are then taken from the complete set of | |
| certificates in the directory and/or file specified by this pair of | |
| directives.</p> | |
| <p><code class="directive">SSLCADNRequestFile</code> must | |
| specify an <em>all-in-one</em> file containing a concatenation of | |
| PEM-encoded CA certificates.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCADNRequestFile "/usr/local/apache2/conf/ca-names.crt"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The file is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcadnrequestpath"><span id="SSLCADNRequestPath">SSLCADNRequestPath</span> Directive <a title="Permanent link" href="#sslcadnrequestpath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for | |
| defining acceptable CA names</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCADNRequestPath <var>directory-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This optional directive can be used to specify the set of | |
| <em>acceptable CA names</em> which will be sent to the client when a | |
| client certificate is requested. See the <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code> directive for more | |
| details.</p> | |
| <p>The files in this directory have to be PEM-encoded and are accessed | |
| through hash filenames. So usually you can't just place the | |
| Certificate files there: you also have to create symbolic links named | |
| <var>hash-value</var><code>.N</code>. And you should always make sure | |
| this directory contains the appropriate symbolic links.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCADNRequestPath "/usr/local/apache2/conf/ca-names.crt/"</pre> | |
| </div> | |
| <p>The files in this directory are read at server startup, while the server | |
| is still running as <code>root</code> (before privilege dropping), so they | |
| may be owned by and readable only by <code>root</code>. The files are not | |
| re-read during normal operation; a server restart is required for changes | |
| to take effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcarevocationcheck"><span id="SSLCARevocationCheck">SSLCARevocationCheck</span> Directive <a title="Permanent link" href="#sslcarevocationcheck" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable CRL-based revocation checking</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationCheck chain|leaf|none [<var>flag</var>s ...]</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCARevocationCheck none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Optional <var>flag</var>s available in httpd 2.4.21 or | |
| later</td></tr> | |
| </table> | |
| <p> | |
| Enables certificate revocation list (CRL) checking. At least one of | |
| <code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code> | |
| or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code> must be | |
| configured. When set to <code>chain</code> (recommended setting), | |
| CRL checks are applied to all certificates in the chain, while setting it to | |
| <code>leaf</code> limits the checks to the end-entity cert. | |
| </p> | |
| <p>The available <var>flag</var>s are:</p> | |
| <ul> | |
| <li><code>no_crl_for_cert_ok</code> | |
| <p> | |
| Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when | |
| no CRL(s) for the checked certificate(s) were found in any of the locations | |
| configured with <code class="directive"><a href="#sslcarevocationfile">SSLCARevocationFile</a></code> | |
| or <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>. | |
| </p> | |
| <p> | |
| With the introduction of <code class="directive">SSLCARevocationFile</code>, | |
| the behavior has been changed: by default with <code>chain</code> or | |
| <code>leaf</code>, CRLs <strong>must</strong> be present for the | |
| validation to succeed - otherwise it will fail with an | |
| <code>"unable to get certificate CRL"</code> error. | |
| </p> | |
| <p> | |
| The <var>flag</var> <code>no_crl_for_cert_ok</code> allows to restore | |
| previous behavior. | |
| </p> | |
| </li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationCheck chain</pre> | |
| </div> | |
| <div class="example"><h3>Compatibility with versions 2.2</h3><pre class="prettyprint lang-config">SSLCARevocationCheck chain no_crl_for_cert_ok</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcarevocationfile"><span id="SSLCARevocationFile">SSLCARevocationFile</span> Directive <a title="Permanent link" href="#sslcarevocationfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for | |
| Client Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the <em>all-in-one</em> file where you can | |
| assemble the Certificate Revocation Lists (CRL) of Certification | |
| Authorities (CA) whose <em>clients</em> you deal with. These are used | |
| for Client Authentication. Such a file is simply the concatenation of | |
| the various PEM-encoded CRL files, in order of preference. This can be | |
| used alternatively and/or additionally to <code class="directive"><a href="#sslcarevocationpath">SSLCARevocationPath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The file is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcarevocationpath"><span id="SSLCARevocationPath">SSLCARevocationPath</span> Directive <a title="Permanent link" href="#sslcarevocationpath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for | |
| Client Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCARevocationPath <var>directory-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the directory where you keep the Certificate Revocation | |
| Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. | |
| These are used to revoke the client certificate on Client Authentication.</p> | |
| <p> | |
| The files in this directory have to be PEM-encoded and are accessed through | |
| hash filenames. So usually you have not only to place the CRL files there. | |
| Additionally you have to create symbolic links named | |
| <var>hash-value</var><code>.rN</code>. And you should always make sure this directory | |
| contains the appropriate symbolic links.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCARevocationPath "/usr/local/apache2/conf/ssl.crl/"</pre> | |
| </div> | |
| <p>The files in this directory are read at server startup, while the server | |
| is still running as <code>root</code> (before privilege dropping), so they | |
| may be owned by and readable only by <code>root</code>. The files are not | |
| re-read during normal operation; a server restart is required for changes | |
| to take effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcertificatechainfile"><span id="SSLCertificateChainFile">SSLCertificateChainFile</span> Directive <a title="Permanent link" href="#sslcertificatechainfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of PEM-encoded Server CA Certificates</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateChainFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <div class="note"><h3>SSLCertificateChainFile is deprecated</h3> | |
| <p><code>SSLCertificateChainFile</code> became obsolete with version 2.4.8, | |
| when <code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code> | |
| was extended to also load intermediate CA certificates from the server | |
| certificate file.</p> | |
| </div> | |
| <p> | |
| This directive sets the optional <em>all-in-one</em> file where you can | |
| assemble the certificates of Certification Authorities (CA) which form the | |
| certificate chain of the server certificate. This starts with the issuing CA | |
| certificate of the server certificate and can range up to the root CA | |
| certificate. Such a file is simply the concatenation of the various | |
| PEM-encoded CA Certificate files, usually in certificate chain order.</p> | |
| <p> | |
| This should be used alternatively and/or additionally to <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> for explicitly | |
| constructing the server certificate chain which is sent to the browser | |
| in addition to the server certificate. It is especially useful to | |
| avoid conflicts with CA certificates when using client | |
| authentication. Because although placing a CA certificate of the | |
| server certificate chain into <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code> has the same effect | |
| for the certificate chain construction, it has the side-effect that | |
| client certificates issued by this same CA certificate are also | |
| accepted on client authentication.</p> | |
| <p> | |
| But be careful: Providing the certificate chain works only if you are using a | |
| <em>single</em> RSA <em>or</em> DSA based server certificate. If you are | |
| using a coupled RSA+DSA certificate pair, this will work only if actually both | |
| certificates use the <em>same</em> certificate chain. Else the browsers will be | |
| confused in this situation.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCertificateChainFile "/usr/local/apache2/conf/ssl.crt/ca.crt"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The file is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcertificatefile"><span id="SSLCertificateFile">SSLCertificateFile</span> Directive <a title="Permanent link" href="#sslcertificatefile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded X.509 certificate data file or token identifier</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateFile <var>file-path</var>|<var>certid</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><var>certid</var> available in 2.4.42 and later.</td></tr> | |
| </table> | |
| <p> | |
| This directive points to a file with certificate data in PEM format, or the certificate identifier through a configured cryptographic token. | |
| If using a PEM file, at minimum, the file must include an end-entity (leaf) certificate. | |
| The directive can be used multiple times (referencing different filenames) | |
| to support multiple algorithms for server authentication - typically | |
| RSA, DSA, and ECC. The number of supported algorithms depends on the | |
| OpenSSL version being used for mod_ssl: with version 3.0 or later, | |
| <code>openssl list -public-key-algorithms</code> (or | |
| <code>openssl list-public-key-algorithms</code> with OpenSSL 1.0) will output a list | |
| of supported algorithms. See the note below about limitations | |
| of OpenSSL versions prior to 1.0.2 and the ways to work around them. | |
| </p> | |
| <p> | |
| The files may also include intermediate CA certificates, sorted from | |
| leaf to root. This is supported with version 2.4.8 and later, | |
| and obsoletes <code class="directive"><a href="#sslcertificatechainfile">SSLCertificateChainFile</a></code>. | |
| When running with OpenSSL 1.0.2 or later, this allows | |
| to configure the intermediate CA chain on a per-certificate basis. | |
| </p> | |
| <p> | |
| Custom DH parameters and an EC curve name for ephemeral keys, | |
| can also be added to end of the first file configured using | |
| <code class="directive">SSLCertificateFile</code>. | |
| This is supported in version 2.4.7 or later. | |
| Such parameters can be generated using the commands | |
| <code>openssl dhparam</code> and <code>openssl ecparam</code>. | |
| The parameters can be added as-is to the end of the first | |
| certificate file. Only the first file can be used for custom | |
| parameters, as they are applied independently of the authentication | |
| algorithm type. | |
| </p> | |
| <p> | |
| Finally the end-entity certificate's private key can also be | |
| added to the certificate file instead of using a separate | |
| <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code> | |
| directive.</p> | |
| <div class="warning"><h3>Do not combine key and certificate in one file</h3> | |
| <p>This practice is highly discouraged for the following reasons:</p> | |
| <ul> | |
| <li><strong>Security</strong>: Keeping the private key in a separate file | |
| allows stricter file permissions. The certificate file can be | |
| world-readable (it is public data), while the key file should be | |
| readable only by root. Combining them in one file means any | |
| misconfiguration or vulnerability that exposes the certificate file | |
| also exposes the private key.</li> | |
| <li><strong>Ordering constraint</strong>: If a combined file is used, | |
| all <code class="directive">SSLCertificateFile</code> directives referencing | |
| such combined files must appear <em>after</em> any | |
| <code class="directive">SSLCertificateFile</code> directives that use a | |
| separate key file. Violating this ordering will cause errors at | |
| startup.</li> | |
| <li><strong>Maintenance</strong>: Separate files make it immediately | |
| clear which file contains what, simplifying certificate rotation | |
| and audits.</li> | |
| </ul> | |
| <p>If the private key is encrypted, the pass phrase dialog is forced | |
| at startup time.</p> | |
| </div> | |
| <p>As an alternative to storing certificates and private keys in | |
| files, a certificate identifier can be used to identify a certificate | |
| stored in a token. Currently, only PKCS#11 URIs (<a href="https://www.rfc-editor.org/rfc/rfc7512">RFC 7512</a>) are | |
| recognized as certificate identifiers, and can be used in conjunction | |
| with the OpenSSL <code>pkcs11</code> engine or provider. If <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code> is omitted, the | |
| certificate and private key can be loaded through the single | |
| identifier specified with <code class="directive">SSLCertificateFile</code>.</p> | |
| <div class="note"> | |
| <h3>DH parameter interoperability with primes > 1024 bit</h3> | |
| <p> | |
| Beginning with version 2.4.7, mod_ssl makes use of | |
| standardized DH parameters with prime lengths of 2048, 3072 and 4096 bits | |
| and with additional prime lengths of 6144 and 8192 bits beginning with | |
| version 2.4.10 | |
| (from <a href="https://www.rfc-editor.org/rfc/rfc3526">RFC 3526</a>), and hands | |
| them out to clients based on the length of the certificate's RSA/DSA key. | |
| With Java-based clients in particular (Java 7 or earlier), this may lead | |
| to handshake failures - see this | |
| <a href="../ssl/ssl_faq.html#javadh">FAQ answer</a> for working around | |
| such issues. | |
| </p> | |
| </div> | |
| <div class="note"> | |
| <h3>Default DH parameters when using multiple certificates and OpenSSL | |
| versions prior to 1.0.2</h3> | |
| <p> | |
| When using multiple certificates to support different authentication algorithms | |
| (like RSA, DSA, but mainly ECC) and OpenSSL prior to 1.0.2, it is recommended | |
| to either use custom DH parameters (preferably) by adding them to the | |
| first certificate file (as described above), or to order the | |
| <code class="directive">SSLCertificateFile</code> directives such that RSA/DSA | |
| certificates are placed <strong>after</strong> the ECC one. | |
| </p> | |
| <p> | |
| This is due to a limitation in older versions of OpenSSL which don't let the | |
| Apache HTTP Server determine the currently selected certificate at handshake | |
| time (when the DH parameters must be sent to the peer) but instead always | |
| provide the last configured certificate. Consequently, the server may select | |
| default DH parameters based on the length of the wrong certificate's key (ECC | |
| keys are much smaller than RSA/DSA ones and their length is not relevant for | |
| selecting DH primes). | |
| </p> | |
| <p> | |
| Since custom DH parameters always take precedence over the default ones, this | |
| issue can be avoided by creating and configuring them (as described above), | |
| thus using a custom/suitable length. | |
| </p> | |
| </div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># Example using a PEM-encoded file. | |
| SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt" | |
| # Example use of a certificate and private key from a PKCS#11 token: | |
| SSLCertificateFile "pkcs11:token=My%20Token%20Name;id=45"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The file is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcertificatekeyfile"><span id="SSLCertificateKeyFile">SSLCertificateKeyFile</span> Directive <a title="Permanent link" href="#sslcertificatekeyfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server PEM-encoded private key file</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCertificateKeyFile <var>file-path</var>|<var>keyid</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><var>keyid</var> available in 2.4.42 and later.</td></tr> | |
| </table> | |
| <p> | |
| This directive points to the PEM-encoded private key file for the | |
| server, or the key ID through a configured cryptographic token. If the | |
| contained private key is encrypted, the pass phrase dialog is forced | |
| at startup time.</p> | |
| <p> | |
| The directive can be used multiple times (referencing different filenames) | |
| to support multiple algorithms for server authentication. For each | |
| <code class="directive">SSLCertificateKeyFile</code> | |
| directive, there must be a matching <code class="directive">SSLCertificateFile</code> | |
| directive.</p> | |
| <div class="warning"><h3>Do not combine key and certificate in one file</h3> | |
| <p>The private key may also be combined with the certificate in the | |
| file given by <code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code>, | |
| but this practice is highly discouraged. See the warning in the | |
| <code class="directive">SSLCertificateFile</code> documentation for a full | |
| explanation of the risks and constraints.</p> | |
| </div> | |
| <p>As an alternative to storing private keys in files, a key | |
| identifier can be used to identify a private key stored in a | |
| token. Currently, only PKCS#11 URIs (<a href="https://www.rfc-editor.org/rfc/rfc7512">RFC 7512</a>) are recognized as private key | |
| identifiers, and can be used in conjunction with the OpenSSL | |
| <code>pkcs11</code> engine or provider.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># To use a private key from a PEM-encoded file: | |
| SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key" | |
| # To use a private key from a PKCS#11 token: | |
| SSLCertificateKeyFile "pkcs11:token=My%20Token%20Name;id=45"</pre> | |
| </div> | |
| <p>This file is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it should be owned by | |
| and readable only by <code>root</code>, since it contains the private key. | |
| The file is not re-read during normal operation; a server restart is | |
| required for changes to take effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslciphersuite"><span id="SSLCipherSuite">SSLCipherSuite</span> Directive <a title="Permanent link" href="#sslciphersuite" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL | |
| handshake</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCipherSuite [<var>protocol</var>] <var>cipher-spec</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCipherSuite DEFAULT (depends on OpenSSL version)</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This complex directive uses a colon-separated <var>cipher-spec</var> string | |
| consisting of OpenSSL cipher specifications to configure the Cipher Suite the | |
| client is permitted to negotiate in the SSL handshake phase. The optional | |
| protocol specifier can configure the Cipher Suite for a specific SSL version. | |
| Possible values include "SSL" for all SSL Protocols up to and including TLSv1.2. | |
| </p> | |
| <p> | |
| Notice that this | |
| directive can be used both in per-server and per-directory context. | |
| In per-server context it applies to the standard SSL handshake when a connection | |
| is established. In per-directory context it forces a SSL renegotiation with the | |
| reconfigured Cipher Suite after the HTTP request was read but before the HTTP | |
| response is sent.</p> | |
| <p> | |
| If the SSL library supports TLSv1.3 (OpenSSL 1.1.1 and later), the protocol | |
| specifier "TLSv1.3" can be used to configure the cipher suites for that protocol. | |
| Since TLSv1.3 does not offer renegotiations, specifying ciphers for it in | |
| a directory context is not allowed.</p> | |
| <p> | |
| For a list of TLSv1.3 cipher names, see | |
| <a href="https://docs.openssl.org/master/man3/SSL_CTX_set_ciphersuites/">the OpenSSL | |
| documentation</a>.</p> | |
| <p> | |
| An SSL cipher specification in <var>cipher-spec</var> is composed of 4 major | |
| attributes plus a few extra minor ones:</p> | |
| <ul> | |
| <li><em>Key Exchange Algorithm</em>:<br> | |
| RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password | |
| </li> | |
| <li><em>Authentication Algorithm</em>:<br> | |
| RSA, Diffie-Hellman, DSS, ECDSA, or none. | |
| </li> | |
| <li><em>Cipher/Encryption Algorithm</em>:<br> | |
| AES, DES, Triple-DES, RC4, RC2, IDEA, etc. | |
| </li> | |
| <li><em>MAC Digest Algorithm</em>:<br> | |
| MD5, SHA or SHA1, SHA256, SHA384. | |
| </li> | |
| </ul> | |
| <p>An SSL cipher can also be an export cipher. SSLv2 ciphers are no longer | |
| supported. To specify which ciphers to use, one can either specify all the | |
| Ciphers, one at a time, or use aliases to specify the preference and order | |
| for the ciphers (see <a href="#table1">Table | |
| 1</a>). The actually available ciphers and aliases depends on the used | |
| openssl version. Newer openssl versions may include additional ciphers.</p> | |
| <table class="bordered"> | |
| <tr><th><a name="table1">Tag</a></th> <th>Description</th></tr> | |
| <tr><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> | |
| <tr><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> | |
| <tr><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> | |
| <tr><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> | |
| <tr><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> | |
| <tr><td><code>kSRP</code></td> <td>Secure Remote Password (SRP) key exchange</td></tr> | |
| <tr><td colspan="2"><em>Authentication Algorithm:</em></td></tr> | |
| <tr><td><code>aNULL</code></td> <td>No authentication</td></tr> | |
| <tr><td><code>aRSA</code></td> <td>RSA authentication</td></tr> | |
| <tr><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> | |
| <tr><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> | |
| <tr><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr> | |
| <tr><td><code>eNULL</code></td> <td>No encryption</td> </tr> | |
| <tr><td><code>NULL</code></td> <td>alias for eNULL</td> </tr> | |
| <tr><td><code>AES</code></td> <td>AES encryption</td> </tr> | |
| <tr><td><code>DES</code></td> <td>DES encryption</td> </tr> | |
| <tr><td><code>3DES</code></td> <td>Triple-DES encryption</td> </tr> | |
| <tr><td><code>RC4</code></td> <td>RC4 encryption</td> </tr> | |
| <tr><td><code>RC2</code></td> <td>RC2 encryption</td> </tr> | |
| <tr><td><code>IDEA</code></td> <td>IDEA encryption</td> </tr> | |
| <tr><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> | |
| <tr><td><code>MD5</code></td> <td>MD5 hash function</td></tr> | |
| <tr><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> | |
| <tr><td><code>SHA</code></td> <td>alias for SHA1</td> </tr> | |
| <tr><td><code>SHA256</code></td> <td>SHA256 hash function</td> </tr> | |
| <tr><td><code>SHA384</code></td> <td>SHA384 hash function</td> </tr> | |
| <tr><td colspan="2"><em>Aliases:</em></td></tr> | |
| <tr><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> | |
| <tr><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> | |
| <tr><td><code>EXP</code></td> <td>all export ciphers</td> </tr> | |
| <tr><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> | |
| <tr><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> | |
| <tr><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> | |
| <tr><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> | |
| <tr><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> | |
| <tr><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> | |
| <tr><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> | |
| <tr><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> | |
| <tr><td><code>ECDH</code></td> <td>Elliptic Curve Diffie-Hellman key exchange</td> </tr> | |
| <tr><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> | |
| <tr><td><code>AECDH</code></td> <td>all ciphers using Anonymous Elliptic Curve Diffie-Hellman key exchange</td> </tr> | |
| <tr><td><code>SRP</code></td> <td>all ciphers using Secure Remote Password (SRP) key exchange</td> </tr> | |
| <tr><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> | |
| <tr><td><code>ECDSA</code></td> <td>all ciphers using ECDSA authentication</td> </tr> | |
| <tr><td><code>aNULL</code></td> <td>all ciphers using no authentication</td> </tr> | |
| </table> | |
| <p> | |
| Now where this becomes interesting is that these can be put together | |
| to specify the order and ciphers you wish to use. To speed this up | |
| there are also aliases (<code>SSLv3, TLSv1, EXP, LOW, MEDIUM, | |
| HIGH</code>) for certain groups of ciphers. These tags can be joined | |
| together with prefixes to form the <var>cipher-spec</var>. Available | |
| prefixes are:</p> | |
| <ul> | |
| <li>none: add cipher to list</li> | |
| <li><code>+</code>: move matching ciphers to the current location in list</li> | |
| <li><code>-</code>: remove cipher from list (can be added later again)</li> | |
| <li><code>!</code>: kill cipher from list completely (can <strong>not</strong> be added later again)</li> | |
| </ul> | |
| <div class="note"> | |
| <h3><code>aNULL</code>, <code>eNULL</code> and <code>EXP</code> | |
| ciphers are always disabled</h3> | |
| <p>Beginning with version 2.4.7, null and export-grade | |
| ciphers are always disabled, as mod_ssl unconditionally adds | |
| <code>!aNULL:!eNULL:!EXP</code> to any cipher string at initialization.</p> | |
| </div> | |
| <p>A simpler way to look at all of this is to use the ``<code>openssl ciphers | |
| -v</code>'' command which provides a nice way to successively create the | |
| correct <var>cipher-spec</var> string. The default <var>cipher-spec</var> string | |
| depends on the version of the OpenSSL libraries used. Let's suppose it is | |
| ``<code>RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5</code>'' which | |
| means the following: Put <code>RC4-SHA</code> and <code>AES128-SHA</code> at | |
| the beginning. We do this, because these ciphers offer a good compromise | |
| between speed and security. Next, include high and medium security ciphers. | |
| Finally, remove all ciphers which do not authenticate, i.e. for SSL the | |
| Anonymous Diffie-Hellman ciphers, as well as all ciphers which use | |
| <code>MD5</code> as hash algorithm, because it has been proven insufficient.</p> | |
| <div class="example"><pre>$ openssl ciphers -v 'RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5' | |
| RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 | |
| AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1 | |
| DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1 | |
| ... ... ... ... ... | |
| SEED-SHA SSLv3 Kx=RSA Au=RSA Enc=SEED(128) Mac=SHA1 | |
| PSK-RC4-SHA SSLv3 Kx=PSK Au=PSK Enc=RC4(128) Mac=SHA1 | |
| KRB5-RC4-SHA SSLv3 Kx=KRB5 Au=KRB5 Enc=RC4(128) Mac=SHA1</pre></div> | |
| <p>The complete list of particular RSA & DH ciphers for SSL is given in <a href="#table2">Table 2</a>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW</pre> | |
| </div> | |
| <table class="bordered"> | |
| <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> | |
| <tr><td colspan="7"><em>RSA Ciphers:</em></td></tr> | |
| <tr><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr> | |
| <tr><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr> | |
| <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> | |
| <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> | |
| <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> | |
| <tr><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td></td> </tr> | |
| <tr><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> | |
| <tr><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr> | |
| <tr><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr> | |
| <tr><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td></td> </tr> | |
| <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> | |
| <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> | |
| <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> | |
| <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> | |
| </table> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslclienthellovars"><span id="SSLClientHelloVars">SSLClientHelloVars</span> Directive <a title="Permanent link" href="#sslclienthellovars" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable collection of ClientHello variables</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLClientHelloVars on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLClientHelloVars off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.2 and later, requires OpenSSL 1.1.1 or later</td></tr> | |
| </table> | |
| <p>This directive enables collection of ClientHello data during the handshake that is retained for | |
| the length of the connection so it can be exposed as <code>SSL_CLIENTHELLO_*</code> environment | |
| variables for requests depending upon the <code>StdEnvVars</code> setting. The variables are | |
| formatted as the hex-encoded raw buffers seen in the raw network protocol and as provided | |
| by OpenSSL. GREASE (RFC 8701) values are filtered by OpenSSL when enumerating extension IDs, but | |
| otherwise, are passed through unchanged for other variables. If this directive is not enabled or | |
| if OpenSSL prior to version 1.1.1 is used, these variables will not have a value set.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcompression"><span id="SSLCompression">SSLCompression</span> Directive <a title="Permanent link" href="#sslcompression" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable compression on the SSL level</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCompression on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCompression off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.3 and later, if using OpenSSL 0.9.8 or later; | |
| virtual host scope available if using OpenSSL 1.0.0 or later. | |
| The default used to be <code>on</code> in version 2.4.3.</td></tr> | |
| </table> | |
| <p>This directive allows to enable compression on the SSL level.</p> | |
| <div class="warning"> | |
| <p>Enabling compression causes security issues in most setups (the so called | |
| CRIME attack).</p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslcryptodevice"><span id="SSLCryptoDevice">SSLCryptoDevice</span> Directive <a title="Permanent link" href="#sslcryptodevice" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable use of a cryptographic hardware accelerator</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLCryptoDevice <var>engine</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLCryptoDevice builtin</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive enables use of a cryptographic hardware accelerator | |
| board to offload some of the SSL processing overhead. This directive | |
| can only be used if the SSL toolkit is built with "engine" support; | |
| OpenSSL 0.9.7 and later releases have "engine" support by default, the | |
| separate "-engine" releases of OpenSSL 0.9.6 must be used.</p> | |
| <p>To discover which engine names are supported, run the command | |
| "<code>openssl engine</code>".</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># For a Broadcom accelerator: | |
| SSLCryptoDevice ubsec</pre> | |
| </div> | |
| <p> | |
| With OpenSSL 3.0 or later, if no engine is specified but the key or certificate | |
| is specified using a PKCS#11 URIs (<a href="https://www.rfc-editor.org/rfc/rfc7512">RFC 7512</a>) | |
| then it is tried to load the key and certificate from an OpenSSL provider. | |
| The OpenSSL provider to use must be defined and configured in the OpenSSL config file, | |
| and it must support the <a href="https://docs.openssl.org/3.0/man7/provider-storemgmt/">STORE method</a> | |
| for PKCS#11 URIs (<a href="https://www.rfc-editor.org/rfc/rfc7512">RFC 7512</a>). | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslechkeydir"><span id="SSLECHKeyDir">SSLECHKeyDir</span> Directive <a title="Permanent link" href="#sslechkeydir" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Load the set of Encrypted Client Hello (ECH) PEM files in the named directory</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLECHKeyDir <var>dirname</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache HTTP Server 2.5.1 and later</td></tr> | |
| </table> | |
| <p> | |
| ECH is specified in | |
| <a href="https://www.rfc-editor.org/rfc/rfc9849">RFC 9849</a> | |
| httpd supports ECH "shared-mode" where the httpd instance does the | |
| ECH decryption and also hosts both the ECH `public-name` and `backend` web | |
| sites. | |
| </p> | |
| <p> | |
| The <code>SSLECHKeyDir</code> directive | |
| names the directory where ECH PEM files (named <code>*.ech</code>) are stored. | |
| Once an ECH PEM file is successfully loaded, httpd will perform ECH decryption | |
| and, if that succeeds, will process the relevant TLS session using the | |
| SNI from the inner ClientHello. | |
| </p> | |
| <div class="example"><h3>Example ECH Config</h3><pre class="prettyprint lang-config">... | |
| SSLEngine On | |
| SSLProtocol TLSv1.3 | |
| SSLECHKeyDir /etc/apache2/echkeydir | |
| ... | |
| # virtual hosts | |
| <VirtualHost *:443> | |
| SSLEngine On | |
| SSLProtocol TLSv1.3 | |
| ServerName example.com | |
| DocumentRoot "/var/www/dir-example.com" | |
| </VirtualHost> | |
| <VirtualHost *:443> | |
| SSLEngine On | |
| SSLProtocol TLSv1.3 | |
| ServerName foo.example.com | |
| DocumentRoot "/var/www/dir-foo.example.com" | |
| </VirtualHost> | |
| ...</pre> | |
| </div> | |
| <div class="note"><h3>ECH Key Generation and Publication</h3> | |
| <p> | |
| In the above, we describe a configuration that uses <code>example.com</code> as the | |
| ECH <code>public-name</code> and where <code>foo.example.com</code> is a web-site for which we want | |
| ECH to be used, with both hosted on the same httpd instance. | |
| </p> | |
| <p> | |
| Using ECH requires that httpd load an ECH key pair with a private value for ECH | |
| decryption. Browsers will require that the public component of that key pair be | |
| published in the DNS. With OpenSSL we generate and store that key pair in an ECH PEM | |
| formatted file as shown below. | |
| </p> | |
| <p> | |
| To generate ECH PEM files, use the ECH-enabled openssl command line | |
| to generate an ECH key pair and store the result in an ECH PEM file. | |
| You must also supply the <code>public-name</code> required by the ECH protocol. | |
| </p> | |
| <p> | |
| Key generation operations should be carried out under whatever local account is | |
| used for httpd configuration. | |
| </p> | |
| <div class="example"><h3>Example: ECH Key Generation</h3><pre class="prettyprint lang-config">~# OSSL=/home/user/code/openssl/apps/openssl | |
| ~# mkdir -p /etc/apache2/echkeydir | |
| ~# chmod 700 /etc/apache2/echkeydir | |
| ~# cd /etc/apache2/echkeydir | |
| ~# $OSSL ech -public-name example.com -o example.com.pem.ech | |
| ~# cat example.com.pem.ech | |
| -----BEGIN PRIVATE KEY----- | |
| MC4CAQAwBQYDK2VuBCIEIJi22Im2rJ/lJqzNFZdGfsVfmknXAc8xz3fYPhD0Na5I | |
| -----END PRIVATE KEY----- | |
| -----BEGIN ECHCONFIG----- | |
| AD7+DQA6QwAgACA8mxkEsSTp2xXC/RUFCC6CZMMgdM4x1iTWKu3EONjbMAAEAAEA | |
| AQALZXhhbXBsZS5vcmcAAA== | |
| -----END ECHCONFIG-----</pre> | |
| </div> | |
| <p> | |
| The ECHConfig value then needs to be published in an HTTPS resource record in | |
| the DNS, so as to be accessible as shown below: | |
| </p> | |
| <div class="example"><h3>Accessing an ECH config from DNS</h3><pre class="prettyprint lang-config">$ dig +short HTTPS foo.example.com | |
| 1 . ech=AD7+DQA6QwAgACA8mxkEsSTp2xXC/RUFCC6CZMMgdM4x1iTWKu3EONjbMAAEAAEAAQALZXhhbXBsZS5vcmcAAA==</pre> | |
| </div> | |
| <p> | |
| Various other fields may be included in an HTTPS resource record. For many | |
| httpd deployments, existing methods for publishing DNS records may be used to | |
| achieve the above. In some cases, one might use | |
| <a href="https://datatracker.ietf.org/doc/html/draft-ietf-tls-wkech"> | |
| A well-known URI for publishing service parameters</a> | |
| designed to assist web servers in handling e.g. frequent ECH key rotation. | |
| </p> | |
| </div> | |
| <div class="note"><h3>Reloading ECH Keys</h3> | |
| <p> | |
| Giving httpd a command line argument of <code>-k graceful</code> causes a graceful reload | |
| of the configuration, without dropping existing connections. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslengine"><span id="SSLEngine">SSLEngine</span> Directive <a title="Permanent link" href="#sslengine" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Engine Operation Switch</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLEngine on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLEngine off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td> | |
| Support for the "optional" argument was removed in 2.4.64. It enabled | |
| RFC 2817 (TLS Upgrade) support. | |
| </td></tr> | |
| </table> | |
| <p> | |
| This directive toggles the usage of the SSL/TLS Protocol Engine. This | |
| is should be used inside a <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> section to enable SSL/TLS for a | |
| that virtual host. By default the SSL/TLS Protocol Engine is | |
| disabled for both the main server and all configured virtual hosts.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><VirtualHost _default_:443> | |
| SSLEngine on | |
| #... | |
| </VirtualHost></pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslfips"><span id="SSLFIPS">SSLFIPS</span> Directive <a title="Permanent link" href="#sslfips" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL FIPS mode Switch</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLFIPS on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLFIPS off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive toggles the usage of the SSL library FIPS_mode flag. | |
| It must be set in the global server context and cannot be configured | |
| with conflicting settings (SSLFIPS on followed by SSLFIPS off or | |
| similar). The mode applies to all SSL library operations. | |
| </p> | |
| <p> | |
| If httpd was compiled against an SSL library which did not support | |
| the FIPS_mode flag, <code>SSLFIPS on</code> will fail. Refer to the | |
| FIPS 140-2 Security Policy document of the SSL provider library for | |
| specific requirements to use mod_ssl in a FIPS 140-2 approved mode | |
| of operation; note that mod_ssl itself is not validated, but may be | |
| described as using FIPS 140-2 validated cryptographic module, when | |
| all components are assembled and operated under the guidelines imposed | |
| by the applicable Security Policy. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslhonorcipherorder"><span id="SSLHonorCipherOrder">SSLHonorCipherOrder</span> Directive <a title="Permanent link" href="#sslhonorcipherorder" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Option to prefer the server's cipher preference order</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLHonorCipherOrder on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLHonorCipherOrder off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later</td></tr> | |
| </table> | |
| <p>When choosing a cipher during an SSLv3 or TLSv1 handshake, normally | |
| the client's preference is used. If this directive is enabled, the | |
| server's preference will be used instead.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLHonorCipherOrder on</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspdefaultresponder"><span id="SSLOCSPDefaultResponder">SSLOCSPDefaultResponder</span> Directive <a title="Permanent link" href="#sslocspdefaultresponder" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the default responder URI for OCSP validation</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPDefaultResponder <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This option sets the default OCSP responder to use. If <code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code> is not enabled, | |
| the URI given will be used only if no responder URI is specified in | |
| the certificate being verified.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspenable"><span id="SSLOCSPEnable">SSLOCSPEnable</span> Directive <a title="Permanent link" href="#sslocspenable" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable OCSP validation of the client certificate chain</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPEnable on|leaf|off [<var>flags</var>]</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPEnable off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Mode <em>leaf</em> available in httpd 2.4.34 and later. Flag <em>no_ocsp_for_cert_ok</em> available in 2.4.29 and later.</td></tr> | |
| </table> | |
| <p>This option enables OCSP validation of the client certificate | |
| chain. If this option is enabled, certificates in the client's | |
| certificate chain will be validated against an OCSP responder after | |
| normal verification (including CRL checks) have taken place. In | |
| mode 'leaf', only the client certificate itself will be validated.</p> | |
| <p>The OCSP responder used is either extracted from the certificate | |
| itself, or derived by configuration; see the | |
| <code class="directive"><a href="#sslocspdefaultresponder">SSLOCSPDefaultResponder</a></code> and | |
| <code class="directive"><a href="#sslocspoverrideresponder">SSLOCSPOverrideResponder</a></code> | |
| directives.</p> | |
| <p>The following optional flags are available:</p> | |
| <ul> | |
| <li><code>no_ocsp_for_cert_ok</code> | |
| <p>When OCSP validation is enabled, a certificate that does not | |
| contain an OCSP responder URL will normally cause validation to fail. | |
| Adding this flag allows such certificates to pass validation. This | |
| is useful in environments where some certificates in the chain do | |
| not include OCSP responder information.</p> | |
| </li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyClient on | |
| SSLOCSPEnable on | |
| SSLOCSPDefaultResponder "http://responder.example.com:8888/responder" | |
| SSLOCSPOverrideResponder on</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspnoverify"><span id="SSLOCSPNoverify">SSLOCSPNoverify</span> Directive <a title="Permanent link" href="#sslocspnoverify" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>skip the OCSP responder certificates verification</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPNoverify on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPNoverify off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.26 and later, if using OpenSSL 0.9.7 or later</td></tr> | |
| </table> | |
| <p>Skip the OCSP responder certificates verification, mostly useful when | |
| testing an OCSP server.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspoverrideresponder"><span id="SSLOCSPOverrideResponder">SSLOCSPOverrideResponder</span> Directive <a title="Permanent link" href="#sslocspoverrideresponder" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Force use of the default responder URI for OCSP validation</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPOverrideResponder on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPOverrideResponder off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This option forces the configured default OCSP responder to be used | |
| during OCSP certificate validation, regardless of whether the | |
| certificate being validated references an OCSP responder.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspproxyurl"><span id="SSLOCSPProxyURL">SSLOCSPProxyURL</span> Directive <a title="Permanent link" href="#sslocspproxyurl" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Proxy URL to use for OCSP requests</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPProxyURL <var>url</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.19 and later</td></tr> | |
| </table> | |
| <p>This option allows to set the URL of a HTTP proxy that should be used for | |
| all queries to OCSP responders.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocsprespondercertificatefile"><span id="SSLOCSPResponderCertificateFile">SSLOCSPResponderCertificateFile</span> Directive <a title="Permanent link" href="#sslocsprespondercertificatefile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set of trusted PEM encoded OCSP responder certificates</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponderCertificateFile <var>file</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.26 and later, if using OpenSSL 0.9.7 or later</td></tr> | |
| </table> | |
| <p>This supplies a list of trusted OCSP responder certificates to be used | |
| during OCSP responder certificate validation. The supplied certificates are | |
| implicitly trusted without any further validation. This is typically used | |
| where the OCSP responder certificate is self signed or omitted from the OCSP | |
| response.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocsprespondertimeout"><span id="SSLOCSPResponderTimeout">SSLOCSPResponderTimeout</span> Directive <a title="Permanent link" href="#sslocsprespondertimeout" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout for OCSP queries</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponderTimeout <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponderTimeout 10</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This option sets the timeout for queries to OCSP responders, when | |
| <code class="directive"><a href="#sslocspenable">SSLOCSPEnable</a></code> is turned on.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspresponsemaxage"><span id="SSLOCSPResponseMaxAge">SSLOCSPResponseMaxAge</span> Directive <a title="Permanent link" href="#sslocspresponsemaxage" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable age for OCSP responses</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponseMaxAge <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponseMaxAge -1</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This option sets the maximum allowable age ("freshness") for OCSP responses. | |
| The default value (<code>-1</code>) does not enforce a maximum age, | |
| which means that OCSP responses are considered valid as long as their | |
| <code>nextUpdate</code> field is in the future.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspresponsetimeskew"><span id="SSLOCSPResponseTimeSkew">SSLOCSPResponseTimeSkew</span> Directive <a title="Permanent link" href="#sslocspresponsetimeskew" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable time skew for OCSP response validation</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPResponseTimeSkew <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPResponseTimeSkew 300</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>This option sets the maximum allowable time skew for OCSP responses | |
| (when checking their <code>thisUpdate</code> and <code>nextUpdate</code> fields).</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslocspuserequestnonce"><span id="SSLOCSPUseRequestNonce">SSLOCSPUseRequestNonce</span> Directive <a title="Permanent link" href="#sslocspuserequestnonce" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a nonce within OCSP queries</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOCSPUseRequestNonce on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLOCSPUseRequestNonce on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.10 and later</td></tr> | |
| </table> | |
| <p>This option determines whether queries to OCSP responders should contain | |
| a nonce or not. By default, a query nonce is always used and checked against | |
| the response's one. When the responder does not use nonces (e.g. Microsoft OCSP | |
| Responder), this option should be turned <code>off</code>.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslopensslconfcmd"><span id="SSLOpenSSLConfCmd">SSLOpenSSLConfCmd</span> Directive <a title="Permanent link" href="#sslopensslconfcmd" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure OpenSSL parameters through its <em>SSL_CONF</em> API</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOpenSSLConfCmd <var>command-name</var> <var>command-value</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.8 and later, if using OpenSSL 1.0.2 or later</td></tr> | |
| </table> | |
| <p>This directive exposes OpenSSL's <em>SSL_CONF</em> API to mod_ssl, | |
| allowing a flexible configuration of OpenSSL parameters without the need | |
| of implementing additional <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> directives when new | |
| features are added to OpenSSL.</p> | |
| <p>The set of available <code class="directive">SSLOpenSSLConfCmd</code> commands | |
| depends on the OpenSSL version being used for <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> | |
| (at least version 1.0.2 is required). For a list of supported command | |
| names, see the section <em>Supported configuration file commands</em> in the | |
| <a href="https://docs.openssl.org/master/man3/SSL_CONF_cmd/#supported-configuration-file-commands">SSL_CONF_cmd(3)</a> manual page for OpenSSL.</p> | |
| <div class="example"><h3>Examples</h3><pre class="prettyprint lang-config">SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference | |
| SSLOpenSSLConfCmd ECDHParameters brainpoolP256r1 | |
| SSLOpenSSLConfCmd ServerInfoFile "/usr/local/apache2/conf/server-info.pem" | |
| SSLOpenSSLConfCmd Protocol "-ALL, TLSv1.2" | |
| SSLOpenSSLConfCmd SignatureAlgorithms RSA+SHA384:ECDSA+SHA256</pre> | |
| </div> | |
| <div class="warning"><h3>Compatibility and Stability | |
| warning</h3> | |
| <p>Some of the <code class="directive">SSLOpenSSLConfCmd</code> commands can be used | |
| as an alternative to existing directives (such as | |
| <code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code> or | |
| <code class="directive"><a href="#sslprotocol">SSLProtocol</a></code>), | |
| though the syntax / allowable values for the parameters may sometimes differ.</p> | |
| <p>It is recommended that directives provided by mod_ssl are used | |
| where available to configure OpenSSL, and | |
| <code class="directive">SSLOpenSSLConfCmd</code> is only used for features of | |
| OpenSSL which are not configurable by mod_ssl. It is possible that | |
| mod_ssl behavior will change across versions of httpd where | |
| <code class="directive">SSLOpenSSLConfCmd</code> is used.</p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="ssloptions"><span id="SSLOptions">SSLOptions</span> Directive <a title="Permanent link" href="#ssloptions" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure various SSL engine run-time options</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLOptions [+|-]<var>option</var> ...</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive can be used to control various run-time options on a | |
| per-directory basis. Normally, if multiple <code class="directive">SSLOptions</code> | |
| could apply to a directory, then the most specific one is taken | |
| completely; the options are not merged. However if <em>all</em> the | |
| options on the <code class="directive">SSLOptions</code> directive are preceded by a | |
| plus (<code>+</code>) or minus (<code>-</code>) symbol, the options | |
| are merged. Any options preceded by a <code>+</code> are added to the | |
| options currently in force, and any options preceded by a | |
| <code>-</code> are removed from the options currently in force.</p> | |
| <p> | |
| The available <var>option</var>s are:</p> | |
| <ul> | |
| <li><code>StdEnvVars</code> | |
| <p> | |
| When this option is enabled, the standard set of SSL related CGI/SSI | |
| environment variables are created. This per default is disabled for | |
| performance reasons, because the information extraction step is a | |
| rather expensive operation. So one usually enables this option for | |
| CGI and SSI requests only.</p> | |
| </li> | |
| <li><code>ExportCertData</code> | |
| <p> | |
| When this option is enabled, additional CGI/SSI environment variables are | |
| created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and | |
| <code>SSL_CLIENT_CERT_CHAIN_</code><var>n</var> (with <var>n</var> = 0,1,2,..). | |
| These contain the PEM-encoded X.509 Certificates of server and client for | |
| the current HTTPS connection and can be used by CGI scripts for deeper | |
| Certificate checking. Additionally all other certificates of the client | |
| certificate chain are provided, too. This bloats up the environment a | |
| little bit which is why you have to use this option to enable it on | |
| demand.</p> | |
| </li> | |
| <li><code>FakeBasicAuth</code> | |
| <p> | |
| When this option is enabled, the Subject Distinguished Name (DN) of the | |
| Client X509 Certificate is translated into a HTTP Basic Authorization | |
| username. This means that the standard Apache authentication methods can | |
| be used for access control. The user name is just the Subject of the | |
| Client's X509 Certificate (can be determined by running OpenSSL's | |
| <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in | |
| </code><var>certificate</var><code>.crt</code>). The optional <code class="directive"><a href="#sslusername">SSLUserName</a></code> directive can be used to | |
| specify which part of the certificate Subject is embedded in the username. | |
| Note that no password is obtained from the user. Every entry in the user | |
| file needs this password: ``<code>xxj31ZMTZzkVA</code>'', which is the | |
| DES-encrypted version of the word `<code>password</code>''. Those who | |
| live under MD5-based encryption (for instance under FreeBSD or BSD/OS, | |
| etc.) should use the following MD5 hash of the same word: | |
| ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.</p> | |
| <p>Note that the <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicfake">AuthBasicFake</a></code> | |
| directive within <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> can be used as a more | |
| general mechanism for faking basic authentication, giving control over the | |
| structure of both the username and password. </p> | |
| <div class="note">Unlike the <code>FakeBasicAuth</code> | |
| option, the <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicfake">AuthBasicFake</a></code> directive | |
| does not set an Authorization header early enough to be processed by authentication | |
| and authorization in the local server, it is only intended for upstream servers. | |
| </div> | |
| <div class="warning"> | |
| <p>The usernames used for <code>FakeBasicAuth</code> must not | |
| include any non-ASCII characters, ASCII escape characters (such | |
| a newline), or a colon. If a colon is found, a 403 Forbidden | |
| error will be generated with httpd 2.5.1 and later.</p> | |
| </div> | |
| </li> | |
| <li><code>StrictRequire</code> | |
| <p> | |
| This <em>forces</em> forbidden access when | |
| <code class="directive"><a href="#sslrequiressl">SSLRequireSSL</a></code> or | |
| <code class="directive"><a href="#sslrequire">SSLRequire</a></code> has decided | |
| that access should be denied. Without | |
| <code>StrictRequire</code>, it is possible for other | |
| authorization directives (such as <code class="directive"><a href="../mod/mod_authz_core.html#requireany"><RequireAny></a></code>) to override the SSL | |
| access denial and grant access anyway. With | |
| <code>SSLOptions +StrictRequire</code>, the denial by | |
| <code>SSLRequireSSL</code> or <code>SSLRequire</code> is | |
| enforced unconditionally, regardless of other authorization | |
| settings.</p> | |
| </li> | |
| <li><code>OptRenegotiate</code> | |
| <p> | |
| This enables optimized SSL connection renegotiation handling when SSL | |
| directives are used in per-directory context. By default a strict | |
| scheme is enabled where <em>every</em> per-directory reconfiguration of | |
| SSL parameters causes a <em>full</em> SSL renegotiation handshake. When this | |
| option is used mod_ssl tries to avoid unnecessary handshakes by doing more | |
| granular (but still safe) parameter checks. Nevertheless these granular | |
| checks sometimes may not be what the user expects, so enable this on a | |
| per-directory basis only, please.</p> | |
| </li> | |
| <li><code>LegacyDNStringFormat</code> | |
| <p> | |
| This option influences how values of the | |
| <code>SSL_{CLIENT,SERVER}_{I,S}_DN</code> variables are formatted. Since | |
| version 2.3.11, Apache HTTPD uses a RFC 2253 compatible format by | |
| default. This uses commas as delimiters between the attributes, allows the | |
| use of non-ASCII characters (which are converted to UTF8), escapes | |
| various special characters with backslashes, and sorts the attributes | |
| with the "C" attribute last.</p> | |
| <p>If <code>LegacyDNStringFormat</code> is set, the old format will be | |
| used which sorts the "C" attribute first, uses slashes as separators, and | |
| does not handle non-ASCII and special characters in any consistent way. | |
| </p> | |
| </li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLOptions +FakeBasicAuth -StrictRequire | |
| <Files ~ "\.(cgi|shtml)$"> | |
| SSLOptions +StdEnvVars -ExportCertData | |
| </Files></pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslpassphrasedialog"><span id="SSLPassPhraseDialog">SSLPassPhraseDialog</span> Directive <a title="Permanent link" href="#sslpassphrasedialog" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of pass phrase dialog for encrypted private | |
| keys</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLPassPhraseDialog <var>type</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLPassPhraseDialog builtin</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| When Apache starts up it has to read the various Certificate (see | |
| <code class="directive"><a href="#sslcertificatefile">SSLCertificateFile</a></code>) and | |
| Private Key (see <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>) files of the | |
| SSL-enabled virtual servers. Because for security reasons the Private | |
| Key files are usually encrypted, mod_ssl needs to query the | |
| administrator for a Pass Phrase in order to decrypt those files. This | |
| query can be done in two ways which can be configured by | |
| <var>type</var>:</p> | |
| <ul> | |
| <li><code>builtin</code> | |
| <p> | |
| This is the default where an interactive terminal dialog occurs at startup | |
| time just before Apache detaches from the terminal. Here the administrator | |
| has to manually enter the Pass Phrase for each encrypted Private Key file. | |
| Because a lot of SSL-enabled virtual hosts can be configured, the | |
| following reuse-scheme is used to minimize the dialog: When a Private Key | |
| file is encrypted, all known Pass Phrases (at the beginning there are | |
| none, of course) are tried. If one of those known Pass Phrases succeeds no | |
| dialog pops up for this particular Private Key file. If none succeeded, | |
| another Pass Phrase is queried on the terminal and remembered for the next | |
| round (where it perhaps can be reused).</p> | |
| <p> | |
| This scheme allows mod_ssl to be maximally flexible (because for N encrypted | |
| Private Key files you <em>can</em> use N different Pass Phrases - but then | |
| you have to enter all of them, of course) while minimizing the terminal | |
| dialog (i.e. when you use a single Pass Phrase for all N Private Key files | |
| this Pass Phrase is queried only once).</p></li> | |
| <li><code>|/path/to/program [args...]</code> | |
| <p>This mode allows an external program to be used which acts as a | |
| pipe to a particular input device; the program is sent the standard | |
| prompt text used for the <code>builtin</code> mode on | |
| <code>stdin</code>, and is expected to write password strings on | |
| <code>stdout</code>. If several passwords are needed (or an | |
| incorrect password is entered), additional prompt text will be | |
| written subsequent to the first password being returned, and more | |
| passwords must then be written back.</p></li> | |
| <li><code>exec:/path/to/program</code> | |
| <p> | |
| Here an external program is configured which is called at startup for each | |
| encrypted Private Key file. It is called with one argument, a string of the | |
| form ``<code>servername:portnumber:index</code>'' (with <code>index</code> | |
| being a zero-based sequence number), which indicates for which server, | |
| TCP port and certificate number it has to print the corresponding | |
| Pass Phrase to <code>stdout</code>. The intent is that this external | |
| program first runs security checks to make sure that the system is not | |
| compromised by an attacker, and only when these checks were passed | |
| successfully it provides the Pass Phrase.</p> | |
| <p> | |
| Both these security checks, and the way the Pass Phrase is determined, can | |
| be as complex as you like. Mod_ssl just defines the interface: an | |
| executable program which provides the Pass Phrase on <code>stdout</code>. | |
| Nothing more or less! So, if you're really paranoid about security, here | |
| is your interface. Anything else has to be left as an exercise to the | |
| administrator, because local security requirements are so different.</p> | |
| <p> | |
| The reuse-algorithm above is used here, too. In other words: The external | |
| program is called only once per unique Pass Phrase.</p></li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLPassPhraseDialog "exec:/usr/local/apache/sbin/pp-filter"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslpolicy"><span id="SSLPolicy">SSLPolicy</span> Directive <a title="Permanent link" href="#sslpolicy" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Apply a SSLPolicy by name</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLPolicy <var>name</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.0 and later</td></tr> | |
| </table> | |
| <p>This directive applies the set of SSL* directives defined | |
| under 'name' as the <em>base</em> settings in the current context. Apache comes with the | |
| following pre-defined policies from Mozilla, the makers of the Firefox browser | |
| (<a href="https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations">see here | |
| for a detailed description by them.</a>): | |
| </p> | |
| <ul> | |
| <li><code>modern</code>: recommended when your server is accessible on the open Internet. Works with all modern browsers, but old devices might be unable to connect.</li> | |
| <li><code>intermediate</code>: the fallback if you need to support old (but not very old) clients.</li> | |
| <li><code>old</code>: when you need to give Windows XP/Internet Explorer 6 access. The last resort.</li> | |
| </ul> | |
| <p>SSLPolicy applies configuration settings in place, meaning previous values are | |
| overwritten. Configuration directives following an SSLPolicy may overwrite it. | |
| </p> | |
| <p>You can check the detailed description of all defined policies via the command line:</p> | |
| <div class="example"><h3>List all Defined Policies</h3><pre class="prettyprint lang-sh">httpd -t -D DUMP_SSL_POLICIES</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslprotocol"><span id="SSLProtocol">SSLProtocol</span> Directive <a title="Permanent link" href="#sslprotocol" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL/TLS protocol versions</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProtocol [+|-]<var>protocol</var> ...</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProtocol all -SSLv3</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive can be used to control which versions of the SSL/TLS protocol | |
| will be accepted in new connections.</p> | |
| <p> | |
| The available (case-insensitive) <var>protocol</var>s are:</p> | |
| <ul> | |
| <li><code>SSLv3</code> | |
| <p> | |
| This is the Secure Sockets Layer (SSL) protocol, version 3.0, from | |
| the Netscape Corporation. | |
| It is the successor to SSLv2 and the predecessor to TLSv1, but is | |
| deprecated in <a href="https://www.rfc-editor.org/rfc/rfc7568">RFC 7568</a>.</p></li> | |
| <li><code>TLSv1</code> | |
| <p> | |
| This is the Transport Layer Security (TLS) protocol, version 1.0. | |
| It is the successor to SSLv3 and is defined in | |
| <a href="https://www.rfc-editor.org/rfc/rfc2246">RFC 2246</a>. | |
| It is supported by nearly every client.</p></li> | |
| <li><code>TLSv1.1</code> (when using OpenSSL 1.0.1 and later) | |
| <p> | |
| A revision of the TLS 1.0 protocol, as defined in | |
| <a href="https://www.rfc-editor.org/rfc/rfc4346">RFC 4346</a>.</p></li> | |
| <li><code>TLSv1.2</code> (when using OpenSSL 1.0.1 and later) | |
| <p> | |
| A revision of the TLS 1.1 protocol, as defined in | |
| <a href="https://www.rfc-editor.org/rfc/rfc5246">RFC 5246</a>.</p></li> | |
| <li><code>TLSv1.3</code> (when using OpenSSL 1.1.1 and later) | |
| <p> | |
| A new version of the TLS protocol, as defined in | |
| <a href="https://www.rfc-editor.org/rfc/rfc8446">RFC 8446</a>.</p></li> | |
| <li><code>all</code> | |
| <p> | |
| This is a shortcut for ``<code>+SSLv3 +TLSv1</code>'' or | |
| - when using OpenSSL 1.0.1 and later - | |
| ``<code>+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2 +TLSv1.3</code>'', respectively | |
| (except for OpenSSL versions compiled with the ``no-ssl3'' configuration | |
| option, where <code>all</code> does not include <code>+SSLv3</code>).</p></li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProtocol TLSv1</pre> | |
| </div> | |
| <div class="note"> | |
| <h3><code class="directive">SSLProtocol</code> for name-based virtual hosts</h3> | |
| <p> | |
| Before OpenSSL 1.1.1, even though the Server Name Indication (SNI) allowed to | |
| determine the targeted virtual host early in the TLS handshake, it was not | |
| possible to switch the TLS protocol version of the connection at this point, | |
| and thus the <code class="directive">SSLProtocol</code> negotiated was always based off | |
| the one of the <em>base virtual host</em> (first virtual host declared on the | |
| listening <code>IP:port</code> of the connection). | |
| </p> | |
| <p> | |
| Beginning with Apache HTTP server version 2.5.1, when built/linked against | |
| OpenSSL 1.1.1 or later, and when the SNI is provided by the client in the TLS | |
| handshake, the <code class="directive">SSLProtocol</code> of each (name-based) virtual | |
| host can and will be honored. | |
| </p> | |
| <p> | |
| For compatibility with previous versions, if no | |
| <code class="directive">SSLProtocol</code> is configured in a name-based virtual host, | |
| the one from the base virtual host still applies, <strong>unless</strong> | |
| <code class="directive">SSLProtocol</code> is configured globally in which case the | |
| global value applies (this latter exception is more sensible than compatible, | |
| though). | |
| </p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycacertificatefile"><span id="SSLProxyCACertificateFile">SSLProxyCACertificateFile</span> Directive <a title="Permanent link" href="#sslproxycacertificatefile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA Certificates | |
| for Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificateFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the <em>all-in-one</em> file where you can assemble the | |
| Certificates of Certification Authorities (CA) whose <em>remote servers</em> you deal | |
| with. These are used for Remote Server Authentication. Such a file is simply the | |
| concatenation of the various PEM-encoded Certificate files, in order of | |
| preference. This can be used alternatively and/or additionally to | |
| <code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycacertificatepath"><span id="SSLProxyCACertificatePath">SSLProxyCACertificatePath</span> Directive <a title="Permanent link" href="#sslproxycacertificatepath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA Certificates for | |
| Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCACertificatePath <var>directory-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the directory where you keep the Certificates of | |
| Certification Authorities (CAs) whose remote servers you deal with. These are used to | |
| verify the remote server certificate on Remote Server Authentication.</p> | |
| <p> | |
| The files in this directory have to be PEM-encoded and are accessed through | |
| hash filenames. So usually you can't just place the Certificate files | |
| there: you also have to create symbolic links named | |
| <var>hash-value</var><code>.N</code>. And you should always make sure this directory | |
| contains the appropriate symbolic links.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCACertificatePath "/usr/local/apache2/conf/ssl.crt/"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycarevocationcheck"><span id="SSLProxyCARevocationCheck">SSLProxyCARevocationCheck</span> Directive <a title="Permanent link" href="#sslproxycarevocationcheck" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable CRL-based revocation checking for Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationCheck chain|leaf|none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCARevocationCheck none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| Enables certificate revocation list (CRL) checking for the | |
| <em>remote servers</em> you deal with. At least one of | |
| <code class="directive"><a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></code> | |
| or <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code> must be | |
| configured. When set to <code>chain</code> (recommended setting), | |
| CRL checks are applied to all certificates in the chain, while setting it to | |
| <code>leaf</code> limits the checks to the end-entity cert. | |
| </p> | |
| <div class="note"> | |
| <h3>When set to <code>chain</code> or <code>leaf</code>, | |
| CRLs <em>must</em> be available for successful validation</h3> | |
| <p> | |
| Prior to version 2.3.15, CRL checking in mod_ssl also succeeded when | |
| no CRL(s) were found in any of the locations configured with | |
| <code class="directive"><a href="#sslproxycarevocationfile">SSLProxyCARevocationFile</a></code> | |
| or <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code>. | |
| With the introduction of this directive, the behavior has been changed: | |
| when checking is enabled, CRLs <em>must</em> be present for the validation | |
| to succeed - otherwise it will fail with an | |
| <code>"unable to get certificate CRL"</code> error. | |
| </p> | |
| </div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationCheck chain</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycarevocationfile"><span id="SSLProxyCARevocationFile">SSLProxyCARevocationFile</span> Directive <a title="Permanent link" href="#sslproxycarevocationfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File of concatenated PEM-encoded CA CRLs for | |
| Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the <em>all-in-one</em> file where you can | |
| assemble the Certificate Revocation Lists (CRL) of Certification | |
| Authorities (CA) whose <em>remote servers</em> you deal with. These are used | |
| for Remote Server Authentication. Such a file is simply the concatenation of | |
| the various PEM-encoded CRL files, in order of preference. This can be | |
| used alternatively and/or additionally to <code class="directive"><a href="#sslproxycarevocationpath">SSLProxyCARevocationPath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationFile "/usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycarevocationpath"><span id="SSLProxyCARevocationPath">SSLProxyCARevocationPath</span> Directive <a title="Permanent link" href="#sslproxycarevocationpath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Directory of PEM-encoded CA CRLs for | |
| Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCARevocationPath <var>directory-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the directory where you keep the Certificate Revocation | |
| Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. | |
| These are used to revoke the remote server certificate on Remote Server Authentication.</p> | |
| <p> | |
| The files in this directory have to be PEM-encoded and are accessed through | |
| hash filenames. So usually you have not only to place the CRL files there. | |
| Additionally you have to create symbolic links named | |
| <var>hash-value</var><code>.rN</code>. And you should always make sure this directory | |
| contains the appropriate symbolic links.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCARevocationPath "/usr/local/apache2/conf/ssl.crl/"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycheckpeercn"><span id="SSLProxyCheckPeerCN">SSLProxyCheckPeerCN</span> Directive <a title="Permanent link" href="#sslproxycheckpeercn" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check the remote server certificate's CN field | |
| </td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerCN on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerCN on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets whether the remote server certificate's CN field is | |
| compared against the hostname of the request URL. If both are not equal | |
| a 502 status code (Bad Gateway) is sent. <code>SSLProxyCheckPeerCN</code> is | |
| superseded by <code class="directive"><a href="#sslproxycheckpeername">SSLProxyCheckPeerName</a></code> | |
| in release 2.4.5 and later. | |
| </p> | |
| <p> | |
| In all releases 2.4.5 through 2.4.20, setting | |
| <code>SSLProxyCheckPeerName off</code> was sufficient to enable this behavior | |
| (as the <code>SSLProxyCheckPeerCN</code> default was <code>on</code>.) In | |
| these releases, both directives must be set to <code>off</code> to completely | |
| avoid remote server certificate name validation. Many users reported this | |
| to be very confusing. | |
| </p> | |
| <p> | |
| As of release 2.4.21, all configurations which enable either one of the | |
| <code>SSLProxyCheckPeerName</code> or <code>SSLProxyCheckPeerCN</code> options | |
| will use the new <code class="directive"><a href="#sslproxycheckpeername">SSLProxyCheckPeerName</a></code> | |
| behavior, and all configurations which disable either one of the | |
| <code>SSLProxyCheckPeerName</code> or <code>SSLProxyCheckPeerCN</code> options | |
| will suppress all remote server certificate name validation. Only the following | |
| configuration will trigger the legacy certificate CN comparison in 2.4.21 and | |
| later releases; | |
| </p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCheckPeerCN on | |
| SSLProxyCheckPeerName off</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycheckpeerexpire"><span id="SSLProxyCheckPeerExpire">SSLProxyCheckPeerExpire</span> Directive <a title="Permanent link" href="#sslproxycheckpeerexpire" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to check if remote server certificate is expired | |
| </td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerExpire on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerExpire on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets whether it is checked if the remote server certificate | |
| is expired or not. If the check fails a 502 status code (Bad Gateway) is | |
| sent. | |
| </p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyCheckPeerExpire on</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxycheckpeername"><span id="SSLProxyCheckPeerName">SSLProxyCheckPeerName</span> Directive <a title="Permanent link" href="#sslproxycheckpeername" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure host name checking for remote server certificates | |
| </td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCheckPeerName on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCheckPeerName on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.4.5 and later<br> | |
| The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive configures host name checking for server certificates when | |
| mod_ssl is acting as an SSL client. The check will succeed if the host name | |
| from the request URI matches one of the CN attribute(s) of the certificate's | |
| subject, or matches the subjectAltName extension. If the check fails, the SSL | |
| request is aborted and a 502 status code (Bad Gateway) is returned. | |
| </p> | |
| <p> | |
| Wildcard matching is supported for specific cases: an subjectAltName entry | |
| of type dNSName, or CN attributes starting with <code>*.</code> will match | |
| with any host name of the same number of name elements and the same suffix. | |
| E.g. <code>*.example.org</code> will match <code>foo.example.org</code>, | |
| but will not match <code>foo.bar.example.org</code>, because the number of | |
| elements in the respective host names differs. | |
| </p> | |
| <p> | |
| This feature was introduced in 2.4.5 and superseded the behavior of the | |
| <code class="directive"><a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></code> directive, which | |
| only tested the exact value in the first CN attribute against the host name. | |
| However, many users were confused by the behavior of using these directives | |
| individually, so the mutual behavior of <code>SSLProxyCheckPeerName</code> | |
| and <code>SSLProxyCheckPeerCN</code> directives were improved in release | |
| 2.4.21. See the <code class="directive"><a href="#sslproxycheckpeercn">SSLProxyCheckPeerCN</a></code> | |
| directive description for the original behavior and details of these | |
| improvements. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxyciphersuite"><span id="SSLProxyCipherSuite">SSLProxyCipherSuite</span> Directive <a title="Permanent link" href="#sslproxyciphersuite" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Cipher Suite available for negotiation in SSL | |
| proxy handshake</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyCipherSuite [<var>protocol</var>] <var>cipher-spec</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p>Equivalent to <code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code>, but | |
| for the proxy connection. | |
| Please refer to <code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code> | |
| for additional information.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxyengine"><span id="SSLProxyEngine">SSLProxyEngine</span> Directive <a title="Permanent link" href="#sslproxyengine" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SSL Proxy Engine Operation Switch</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyEngine on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyEngine off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This | |
| is usually used inside a <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> section to enable SSL/TLS for proxy | |
| usage in a particular virtual host. By default the SSL/TLS Protocol Engine is | |
| disabled for proxy both for the main server and all configured virtual hosts.</p> | |
| <p>Note that the <code class="directive">SSLProxyEngine</code> directive should not, in | |
| general, be included in a virtual host that will be acting as a | |
| forward proxy (using <code class="directive"><a href="../mod/mod_proxy.html#proxy"><Proxy></a></code> | |
| or <code class="directive"><a href="../mod/mod_proxy.html#proxyrequests">ProxyRequests</a></code> directives). | |
| <code class="directive">SSLProxyEngine</code> is not required to enable a forward proxy | |
| server to proxy SSL/TLS requests.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><VirtualHost _default_:443> | |
| SSLProxyEngine on | |
| #... | |
| </VirtualHost></pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxymachinecertificatechainfile"><span id="SSLProxyMachineCertificateChainFile">SSLProxyMachineCertificateChainFile</span> Directive <a title="Permanent link" href="#sslproxymachinecertificatechainfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <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> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificateChainFile <var>filename</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the all-in-one file where you keep the certificate chain | |
| for all of the client certs in use. This directive will be needed if the | |
| remote server presents a list of CA certificates that are not direct signers | |
| of one of the configured client certificates. | |
| </p> | |
| <p> | |
| This referenced file is simply the concatenation of the various PEM-encoded | |
| certificate files. Upon startup, each client certificate configured will | |
| be examined and a chain of trust will be constructed. | |
| </p> | |
| <div class="warning"><h3>Security warning</h3> | |
| <p>If this directive is enabled, all of the certificates in the file will be | |
| trusted as if they were also in <code class="directive"><a href="#sslproxycacertificatefile"> | |
| SSLProxyCACertificateFile</a></code>.</p> | |
| </div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificateChainFile "/usr/local/apache2/conf/ssl.crt/proxyCA.pem"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxymachinecertificatefile"><span id="SSLProxyMachineCertificateFile">SSLProxyMachineCertificateFile</span> Directive <a title="Permanent link" href="#sslproxymachinecertificatefile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <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> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificateFile <var>filename</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later<br> | |
| Inclusion of non-leaf (CA) certificates is permitted only in httpd 2.4.59 and later.</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the all-in-one file where you keep the certificates and | |
| keys used for authentication of the proxy server to remote servers. | |
| </p> | |
| <p> | |
| This referenced file is simply the concatenation of the various | |
| PEM-encoded certificate files. Use this directive alternatively or | |
| additionally to <code>SSLProxyMachineCertificatePath</code>. The referenced file can contain any number of pairs of client | |
| certificate and associated private key. Each pair can be specified in | |
| either (certificate, key) or (key, certificate) order. Non-leaf (CA) certificates can | |
| also be included in the file, and are treated as if configured with <code class="directive"><a href="#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile</a></code>.</p> | |
| <p>When challenged to provide a client certificate by a remote server, | |
| the server should provide a list of <em>acceptable certificate | |
| authority names</em> in the challenge. If such a list is <em>not</em> | |
| provided, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will use the first configured | |
| client cert/key. If a list of CA names <em>is</em> provided, | |
| <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will iterate through that list, and attempt | |
| to find a configured client cert which was issued either directly by | |
| that CA, or indirectly via any number of intermediary CA certificates. | |
| The chain of intermediate CA certificates can be built from those | |
| included in the file, or configured with <code class="directive"><a href="#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile</a></code>. The | |
| first configured matching certificate will then be supplied in | |
| response to the challenge.</p> | |
| <p>If the list of CA names <em>is</em> provided by the remote server, | |
| and <em>no</em> matching client certificate can be found, no client | |
| certificate will be provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>, which will | |
| likely fail the SSL/TLS handshake (depending on the remote server | |
| configuration).</p> | |
| <div class="warning"> | |
| <p>Currently there is no support for encrypted private keys</p> | |
| </div> | |
| <div class="warning"> | |
| <p>Only keys encoded in PKCS1 RSA, DSA or EC format are supported. | |
| Keys encoded in PKCS8 format, ie. starting with | |
| "<code>-----BEGIN PRIVATE KEY-----</code>", | |
| must be converted, eg. using | |
| "<code>openssl rsa -in private-pkcs8.pem -outform pem</code>".</p> | |
| </div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificateFile "/usr/local/apache2/conf/ssl.crt/proxy.pem"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxymachinecertificatepath"><span id="SSLProxyMachineCertificatePath">SSLProxyMachineCertificatePath</span> Directive <a title="Permanent link" href="#sslproxymachinecertificatepath" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <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> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyMachineCertificatePath <var>directory</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the directory where you keep the client | |
| certificates and keys used for authentication of the proxy server to | |
| remote servers. | |
| </p> | |
| <p> | |
| mod_ssl will attempt to load every file inside the specified directory | |
| as if it was configured individually with <code class="directive"><a href="#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile</a></code>. | |
| </p> | |
| <div class="warning"> | |
| <p>Currently there is no support for encrypted private keys</p> | |
| </div> | |
| <div class="warning"> | |
| <p>Only keys encoded in PKCS1 RSA, DSA or EC format are supported. | |
| Keys encoded in PKCS8 format, ie. starting with | |
| "<code>-----BEGIN PRIVATE KEY-----</code>", | |
| must be converted, eg. using | |
| "<code>openssl rsa -in private-pkcs8.pem -outform pem</code>".</p> | |
| </div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyMachineCertificatePath "/usr/local/apache2/conf/proxy.crt/"</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxyprotocol"><span id="SSLProxyProtocol">SSLProxyProtocol</span> Directive <a title="Permanent link" href="#sslproxyprotocol" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure usable SSL protocol flavors for proxy usage</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyProtocol [+|-]<var>protocol</var> ...</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyProtocol all -SSLv3</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive can be used to control the SSL protocol flavors mod_ssl should | |
| use when establishing its server environment for proxy . It will only connect | |
| to servers using one of the provided protocols.</p> | |
| <p>Please refer to <code class="directive"><a href="#sslprotocol">SSLProtocol</a></code> | |
| for additional information. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxystoreuri"><span id="SSLProxyStoreURI">SSLProxyStoreURI</span> Directive <a title="Permanent link" href="#sslproxystoreuri" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Proxy certificate and key stores</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyStoreURI <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.1 and later, when linked with | |
| OpenSSL v3 or later.</td></tr> | |
| </table> | |
| <p> | |
| This directive points to a certificate store containing certificates, | |
| intermediate certificates, and private keys, represented by a URI, | |
| to be used when authenticating to another proxy server. | |
| </p> | |
| <p> | |
| If no scheme is specified, the path will default to a <var>file:</var> | |
| URI, pointing at PEM encoded data, or a PKCS12 file. Other schemes | |
| include, but are not limited to, <var>pkcs11:</var> for smartcards and | |
| HSMs, <var>cng:</var> for the Windows certificate store, and | |
| <var>handle:</var> for TPMs. On Windows, where a file path is also a | |
| valid URI, the <var>file:</var> scheme must be used. | |
| </p> | |
| <p> | |
| The directive can be specified multiple times with tightly scoped | |
| URIs to target specific certificates and keys, or could be specified | |
| with a general URI like <var>pkcs11:</var> that considers all possible | |
| certificates and keys. Certificates, intermediate certificates, and keys | |
| can be defined in any order. | |
| </p> | |
| <p>Proxy certificates and keys are processed as follows. | |
| </p> | |
| <ul> | |
| <li>Leaf certificates that do not have the purpose <var>Client Authentication</var> | |
| are skipped.</li> | |
| <li>Intermediate certificates are considered for building certificate | |
| chains on a best effort basis.</li> | |
| <li>Keys are matched up with leaf certificates, any certificate | |
| without a private key is skipped.</li> | |
| <li>Leaf certificates with private keys are sorted newest to oldest and | |
| are considered during each SSL handshake with a proxy.</li> | |
| <li>The proxy will report back to you how many certificates of each type | |
| were found to help you if no certificates match.</li> | |
| </ul> | |
| <p>If the private key is encrypted, the pass phrase dialog is forced | |
| at startup time.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># Example using a PEM-encoded file. | |
| SSLProxyStoreURI "/usr/local/apache2/conf/ssl.crt/proxy.pem" | |
| # Example using a PKCS12 file. | |
| SSLProxyStoreURI "/usr/local/apache2/conf/ssl.crt/proxy.p12" | |
| # Example use of a certificate and private key from a PKCS#11 token: | |
| SSLProxyStoreURI "pkcs11:token=My%20Token%20Name;id=45"</pre> | |
| </div> | |
| <p>These URIs are read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The URI is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| <p>When challenged to provide a client certificate by a remote server, | |
| the server should provide a list of <em>acceptable certificate | |
| authority names</em> in the challenge. If such a list is <em>not</em> | |
| provided, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will use the most recently | |
| issued client certificate and key. If a list of CA names | |
| <em>is</em> provided, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will iterate through | |
| that list, and attempt to find a configured client certificate which | |
| was issued either directly by that CA, or indirectly via any number of | |
| intermediate CA certificates. | |
| </p> | |
| <p>If the list of CA names <em>is</em> provided by the remote server, | |
| and <em>no</em> matching client certificate can be found, no client | |
| certificate will be provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>, which will | |
| likely fail the SSL/TLS handshake (depending on the remote server | |
| configuration).</p> | |
| <div class="warning"><h3>Using SSLProxyMachineCertificateFile and | |
| SSLProxyStoreURI together</h3> | |
| <p> | |
| You can use both SSLProxyMachineCertificateFile and | |
| SSLProxyStoreURI together, however there is | |
| no overlap between the mechanisms. A certificate defined by | |
| SSLProxyMachineCertificateFile will not be matched with a | |
| key from SSLProxyStoreURI. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxytrusturi"><span id="SSLProxyTrustURI">SSLProxyTrustURI</span> Directive <a title="Permanent link" href="#sslproxytrusturi" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Proxy CA certificate store for Remote Server Auth</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyTrustURI <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.1 and later, when linked with | |
| OpenSSL v3 or later.</td></tr> | |
| </table> | |
| <p> | |
| This directive sets URIs where you can assemble the | |
| Certificates of Certification Authorities (CA) whose <em>remote servers</em> you deal | |
| with. These are used for Remote Server Authentication. This can be used alternatively | |
| and/or additionally to | |
| <code class="directive"><a href="#sslproxycacertificatefile">SSLProxyCACertificateFile</a></code> and | |
| <code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyTrustURI "/usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt"</pre> | |
| </div> | |
| <p> | |
| This directive will also process Certificate Revocation Lists (CRL) of Certification | |
| Authorities (CAs) whose remote servers you deal with, if they fall within scope. | |
| These are used to revoke the remote server certificate on Remote Server Authentication. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxyverify"><span id="SSLProxyVerify">SSLProxyVerify</span> Directive <a title="Permanent link" href="#sslproxyverify" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of remote server Certificate verification</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerify <var>level</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerify none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p>When a proxy is configured to forward requests to a remote SSL | |
| server, this directive can be used to configure certificate | |
| verification of the remote server. </p> | |
| <p> | |
| The following levels are available for <var>level</var>:</p> | |
| <ul> | |
| <li><strong>none</strong>: | |
| no remote server Certificate is required at all</li> | |
| <li><strong>optional</strong>: | |
| the remote server <em>may</em> present a valid Certificate</li> | |
| <li><strong>require</strong>: | |
| the remote server <em>has to</em> present a valid Certificate</li> | |
| <li><strong>optional_no_ca</strong>: | |
| the remote server may present a valid Certificate<br> | |
| but it need not to be (successfully) verifiable.</li> | |
| </ul> | |
| <p>In practice only levels <strong>none</strong> and | |
| <strong>require</strong> are really interesting, because level | |
| <strong>optional</strong> doesn't work with all servers and level | |
| <strong>optional_no_ca</strong> is actually against the idea of | |
| authentication (but can be used to establish SSL test pages, etc.)</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyVerify require</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslproxyverifydepth"><span id="SSLProxyVerifyDepth">SSLProxyVerifyDepth</span> Directive <a title="Permanent link" href="#sslproxyverifydepth" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Remote Server | |
| Certificate verification</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLProxyVerifyDepth <var>number</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLProxyVerifyDepth 1</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, proxy section</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets how deeply mod_ssl should verify before deciding that the | |
| remote server does not have a valid certificate. </p> | |
| <p> | |
| The depth actually is the maximum number of intermediate certificate issuers, | |
| i.e. the number of CA certificates which are max allowed to be followed while | |
| verifying the remote server certificate. A depth of 0 means that self-signed | |
| remote server certificates are accepted only, the default depth of 1 means | |
| the remote server certificate can be self-signed or has to be signed by a CA | |
| which is directly known to the server (i.e. the CA's certificate is under | |
| <code class="directive"><a href="#sslproxycacertificatepath">SSLProxyCACertificatePath</a></code>), etc.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLProxyVerifyDepth 10</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslrandomseed"><span id="SSLRandomSeed">SSLRandomSeed</span> Directive <a title="Permanent link" href="#sslrandomseed" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pseudo Random Number Generator (PRNG) seeding | |
| source</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRandomSeed <var>context</var> <var>source</var> | |
| [<var>bytes</var>]</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <div class="note"><h3>SSLRandomSeed is deprecated</h3> | |
| <p>The <code>SSLRandomSeed</code> directive is deprecated, and is | |
| completely ignored if httpd is built using OpenSSL version 1.1.1 or | |
| later.</p> | |
| </div> | |
| <p> | |
| This configures one or more sources for seeding the Pseudo Random Number | |
| Generator (PRNG) in OpenSSL at startup time (<var>context</var> is | |
| <code>startup</code>) and/or just before a new SSL connection is established | |
| (<var>context</var> is <code>connect</code>). This directive can only be used | |
| in the global server context because the PRNG is a global facility.</p> | |
| <p> | |
| The following <var>source</var> variants are available:</p> | |
| <ul> | |
| <li><code>builtin</code> | |
| <p> This is the always available builtin seeding source. Its usage | |
| consumes minimum CPU cycles under runtime and hence can be always used | |
| without drawbacks. The source used for seeding the PRNG contains of the | |
| current time, the current process id and a randomly | |
| chosen 128 bytes extract of the stack. | |
| The drawback is that this is not really a strong source and at startup | |
| time (where the scoreboard is still not available) this source just | |
| produces a few bytes of entropy. So you should always, at least for the | |
| startup, use an additional seeding source.</p></li> | |
| <li><code>file:/path/to/source</code> | |
| <p> | |
| This variant uses an external file <code>/path/to/source</code> as the | |
| source for seeding the PRNG. When <var>bytes</var> is specified, only the | |
| first <var>bytes</var> number of bytes of the file form the entropy (and | |
| <var>bytes</var> is given to <code>/path/to/source</code> as the first | |
| argument). When <var>bytes</var> is not specified the whole file forms the | |
| entropy (and <code>0</code> is given to <code>/path/to/source</code> as | |
| the first argument). Use this especially at startup time, for instance | |
| with an available <code>/dev/random</code> and/or | |
| <code>/dev/urandom</code> devices (which usually exist on modern Unix | |
| derivatives like FreeBSD and Linux).</p> | |
| <p> | |
| <em>But be careful</em>: Usually <code>/dev/random</code> provides only as | |
| much entropy data as it actually has, i.e. when you request 512 bytes of | |
| entropy, but the device currently has only 100 bytes available two things | |
| can happen: On some platforms you receive only the 100 bytes while on | |
| other platforms the read blocks until enough bytes are available (which | |
| can take a long time). Here using an existing <code>/dev/urandom</code> is | |
| better, because it never blocks and actually gives the amount of requested | |
| data. The drawback is just that the quality of the received data may not | |
| be the best.</p></li> | |
| <li><code>exec:/path/to/program</code> | |
| <p> | |
| This variant uses an external executable | |
| <code>/path/to/program</code> as the source for seeding the | |
| PRNG. When <var>bytes</var> is specified, only the first | |
| <var>bytes</var> number of bytes of its <code>stdout</code> contents | |
| form the entropy. When <var>bytes</var> is not specified, the | |
| entirety of the data produced on <code>stdout</code> form the | |
| entropy. Use this only at startup time when you need a very strong | |
| seeding with the help of an external program (for instance as in | |
| the example above with the <code>truerand</code> utility you can | |
| find in the mod_ssl distribution which is based on the AT&T | |
| <em>truerand</em> library). Using this in the connection context | |
| slows down the server too dramatically, of course. So usually you | |
| should avoid using external programs in that context.</p></li> | |
| <li><code>egd:/path/to/egd-socket</code> (Unix only) | |
| <p> | |
| This variant uses the Unix domain socket of the | |
| external Entropy Gathering Daemon (EGD) (see <a href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech | |
| /crypto/</a>) to seed the PRNG. Use this if no random device exists | |
| on your platform.</p></li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRandomSeed startup builtin | |
| SSLRandomSeed startup "file:/dev/random" | |
| SSLRandomSeed startup "file:/dev/urandom" 1024 | |
| SSLRandomSeed startup "exec:/usr/local/bin/truerand" 16 | |
| SSLRandomSeed connect builtin | |
| SSLRandomSeed connect "file:/dev/random" | |
| SSLRandomSeed connect "file:/dev/urandom" 1024</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslrenegbuffersize"><span id="SSLRenegBufferSize">SSLRenegBufferSize</span> Directive <a title="Permanent link" href="#sslrenegbuffersize" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the size for the SSL renegotiation buffer</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRenegBufferSize <var>bytes</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLRenegBufferSize 131072</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>If an SSL renegotiation is required in per-location context, for | |
| example, any use of <code class="directive"><a href="#sslverifyclient">SSLVerifyClient</a></code> in a Directory or | |
| Location block, then <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> must buffer any HTTP | |
| request body into memory until the new SSL handshake can be performed. | |
| This directive can be used to set the amount of memory that will be | |
| used for this buffer. </p> | |
| <div class="warning"><p> | |
| Note that in many configurations, the client sending the request body | |
| will be untrusted so a denial of service attack by consumption of | |
| memory must be considered when changing this configuration setting. | |
| </p></div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRenegBufferSize 262144</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslrequire"><span id="SSLRequire">SSLRequire</span> Directive <a title="Permanent link" href="#sslrequire" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow access only when an arbitrarily complex | |
| boolean expression is true</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequire <var>expression</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <div class="note"><h3>SSLRequire is deprecated</h3> | |
| <p><code>SSLRequire</code> is deprecated and should in general be replaced | |
| by <a href="mod_authz_core.html#reqexpr">Require expr</a>. The so called | |
| <a href="../expr.html">ap_expr</a> syntax of <code>Require expr</code> is | |
| a superset of the syntax of <code>SSLRequire</code>, with the following | |
| exception:</p> | |
| <p>In <code>SSLRequire</code>, the comparison operators <code><</code>, | |
| <code><=</code>, ... are completely equivalent to the operators | |
| <code>lt</code>, <code>le</code>, ... and work in a somewhat peculiar way that | |
| first compares the length of two strings and then the lexical order. | |
| On the other hand, <a href="../expr.html">ap_expr</a> has two sets of | |
| comparison operators: The operators <code><</code>, | |
| <code><=</code>, ... do lexical string comparison, while the operators | |
| <code>-lt</code>, <code>-le</code>, ... do integer comparison. | |
| For the latter, there are also aliases without the leading dashes: | |
| <code>lt</code>, <code>le</code>, ... | |
| </p> | |
| </div> | |
| <p> | |
| This directive specifies a general access requirement which has to be | |
| fulfilled in order to allow access. It is a very powerful directive because the | |
| requirement specification is an arbitrarily complex boolean expression | |
| containing any number of access checks.</p> | |
| <p> | |
| The <var>expression</var> must match the following syntax (given as a BNF | |
| grammar notation):</p> | |
| <blockquote> | |
| <pre>expr ::= "<strong>true</strong>" | "<strong>false</strong>" | |
| | "<strong>!</strong>" expr | |
| | expr "<strong>&&</strong>" expr | |
| | expr "<strong>||</strong>" expr | |
| | "<strong>(</strong>" expr "<strong>)</strong>" | |
| | comp | |
| comp ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word | |
| | word "<strong>!=</strong>" word | word "<strong>ne</strong>" word | |
| | word "<strong><</strong>" word | word "<strong>lt</strong>" word | |
| | word "<strong><=</strong>" word | word "<strong>le</strong>" word | |
| | word "<strong>></strong>" word | word "<strong>gt</strong>" word | |
| | word "<strong>>=</strong>" word | word "<strong>ge</strong>" word | |
| | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>" | |
| | word "<strong>in</strong>" "<strong>PeerExtList(</strong>" word "<strong>)</strong>" | |
| | word "<strong>=~</strong>" regex | |
| | word "<strong>!~</strong>" regex | |
| wordlist ::= word | |
| | wordlist "<strong>,</strong>" word | |
| word ::= digit | |
| | cstring | |
| | variable | |
| | function | |
| digit ::= [0-9]+ | |
| cstring ::= "..." | |
| variable ::= "<strong>%{</strong>" varname "<strong>}</strong>" | |
| function ::= funcname "<strong>(</strong>" funcargs "<strong>)</strong>"</pre> | |
| </blockquote> | |
| <p>For <code>varname</code> any of the variables described in <a href="#envvars">Environment Variables</a> can be used. For | |
| <code>funcname</code> the available functions are listed in | |
| the <a href="../expr.html#functions">ap_expr documentation</a>.</p> | |
| <p>The <var>expression</var> is parsed into an internal machine | |
| representation when the configuration is loaded, and then evaluated | |
| during request processing. In .htaccess context, the <var>expression</var> is | |
| both parsed and executed each time the .htaccess file is encountered during | |
| request processing.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ | |
| and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ | |
| and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ | |
| and %{TIME_WDAY} -ge 1 and %{TIME_WDAY} -le 5 \ | |
| and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20 ) \ | |
| or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/</pre> | |
| </div> | |
| <p>The <code>PeerExtList(<var>object-ID</var>)</code> function expects | |
| to find zero or more instances of the X.509 certificate extension | |
| identified by the given <var>object ID</var> (OID) in the client certificate. | |
| The expression evaluates to true if the left-hand side string matches | |
| exactly against the value of an extension identified with this OID. | |
| (If multiple extensions with the same OID are present, at least one | |
| extension must match).</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")</pre> | |
| </div> | |
| <div class="note"><h3>Notes on the PeerExtList function</h3> | |
| <ul> | |
| <li><p>The object ID can be specified either as a descriptive | |
| name recognized by the SSL library, such as <code>"nsComment"</code>, | |
| or as a numeric OID, such as <code>"1.2.3.4.5.6"</code>.</p></li> | |
| <li><p>Expressions with types known to the SSL library are rendered to | |
| a string before comparison. For an extension with a type not | |
| recognized by the SSL library, mod_ssl will parse the value if it is | |
| one of the primitive ASN.1 types UTF8String, IA5String, VisibleString, | |
| or BMPString. For an extension of one of these types, the string | |
| value will be converted to UTF-8 if necessary, then compared against | |
| the left-hand-side expression.</p></li> | |
| </ul> | |
| </div> | |
| <h3>See also</h3> | |
| <ul> | |
| <li><a href="../env.html">Environment Variables in Apache HTTP Server</a>, | |
| for additional examples. | |
| </li> | |
| <li><a href="mod_authz_core.html#reqexpr">Require expr</a></li> | |
| <li><a href="../expr.html">Generic expression syntax in Apache HTTP Server</a> | |
| </li> | |
| </ul> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslrequiressl"><span id="SSLRequireSSL">SSLRequireSSL</span> Directive <a title="Permanent link" href="#sslrequiressl" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deny access when SSL is not used for the | |
| HTTP request</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLRequireSSL</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for | |
| the current connection. This is very handy inside the SSL-enabled virtual | |
| host or directories for defending against configuration errors that expose | |
| stuff that should be protected. When this directive is present all requests | |
| are denied which are not using SSL.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLRequireSSL</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsessioncache"><span id="SSLSessionCache">SSLSessionCache</span> Directive <a title="Permanent link" href="#sslsessioncache" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of the global/inter-process SSL Session | |
| Cache</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCache <var>type</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCache none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This configures the storage type of the global/inter-process SSL Session | |
| Cache. This cache is an optional facility which speeds up parallel request | |
| processing. For requests to the same server process (via HTTP keep-alive), | |
| OpenSSL already caches the SSL session information locally. But because modern | |
| clients request inlined images and other data via parallel requests (usually | |
| up to four parallel requests are common) those requests are served by | |
| <em>different</em> pre-forked server processes. Here an inter-process cache | |
| helps to avoid unnecessary session handshakes.</p> | |
| <p> | |
| The following five storage <var>type</var>s are currently supported:</p> | |
| <ul> | |
| <li><code>none</code> | |
| <p>This disables the global/inter-process Session Cache. This | |
| will incur a noticeable speed penalty and may cause problems if | |
| using certain browsers, particularly if client certificates are | |
| enabled. This setting is not recommended.</p></li> | |
| <li><code>nonenotnull</code> | |
| <p>This disables any global/inter-process Session Cache. However | |
| it does force OpenSSL to send a non-null session ID to | |
| accommodate buggy clients that require one.</p></li> | |
| <li><code>dbm:/path/to/datafile</code> | |
| <p>This makes use of a DBM hashfile on the local disk to | |
| synchronize the local OpenSSL memory caches of the server | |
| processes. This session cache may suffer reliability issues under | |
| high load. To use this, ensure that | |
| <code class="module"><a href="../mod/mod_socache_dbm.html">mod_socache_dbm</a></code> is loaded.</p></li> | |
| <li><code>shmcb:/path/to/datafile</code>[<code>(</code><var>size</var><code>)</code>] | |
| <p>This makes use of a high-performance cyclic buffer | |
| (approx. <var>size</var> bytes in size) inside a shared memory | |
| segment in RAM (established via <code>/path/to/datafile</code>) to | |
| synchronize the local OpenSSL memory caches of the server | |
| processes. This is the recommended session cache. To use this, | |
| ensure that <code class="module"><a href="../mod/mod_socache_shmcb.html">mod_socache_shmcb</a></code> is loaded.</p></li> | |
| <li><code>dc:UNIX:/path/to/socket</code> | |
| <p>This makes use of the <a href="http://distcache.sourceforge.net/">distcache</a> distributed session | |
| caching libraries. The argument should specify the location of | |
| the server or proxy to be used using the distcache address syntax; | |
| for example, <code>UNIX:/path/to/socket</code> specifies a UNIX | |
| domain socket (typically a local dc_client proxy); | |
| <code>IP:server.example.com:9001</code> specifies an IP | |
| address. To use this, ensure that | |
| <code class="module"><a href="../mod/mod_socache_dc.html">mod_socache_dc</a></code> is loaded.</p></li> | |
| </ul> | |
| <div class="example"><h3>Examples</h3><pre class="prettyprint lang-config">SSLSessionCache "dbm:/usr/local/apache/logs/ssl_gcache_data" | |
| SSLSessionCache "shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)"</pre> | |
| </div> | |
| <p>The <code>ssl-cache</code> mutex is used to serialize access to | |
| the session cache to prevent corruption. This mutex can be configured | |
| using the <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsessioncachetimeout"><span id="SSLSessionCacheTimeout">SSLSessionCacheTimeout</span> Directive <a title="Permanent link" href="#sslsessioncachetimeout" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before an SSL session expires | |
| in the Session Cache</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionCacheTimeout <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionCacheTimeout 300</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Applies also to RFC 5077 TLS session resumption in Apache 2.4.10 and later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the timeout in seconds for the information stored in the | |
| global/inter-process SSL Session Cache, the OpenSSL internal memory cache and | |
| for sessions resumed by TLS session resumption (RFC 5077). | |
| It can be set as low as 15 for testing, but should be set to higher | |
| values like 300 in real life.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLSessionCacheTimeout 600</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsessionticketkeyfile"><span id="SSLSessionTicketKeyFile">SSLSessionTicketKeyFile</span> Directive <a title="Permanent link" href="#sslsessionticketkeyfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Persistent encryption/decryption key for TLS session tickets</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionTicketKeyFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>Optionally configures a secret key for encrypting and decrypting | |
| TLS session tickets, as defined in | |
| <a href="https://www.rfc-editor.org/rfc/rfc5077">RFC 5077</a>. | |
| Primarily suitable for clustered environments where TLS sessions information | |
| should be shared between multiple nodes. For single-instance httpd setups, | |
| it is recommended to <em>not</em> configure a ticket key file, but to | |
| rely on (random) keys generated by mod_ssl at startup, instead.</p> | |
| <p>The ticket key file must contain 48 bytes of random data, | |
| preferably created from a high-entropy source. On a Unix-based system, | |
| a ticket key file can be created as follows:</p> | |
| <div class="example"><p><code> | |
| dd if=/dev/random of=/path/to/file.tkey bs=1 count=48 | |
| </code></p></div> | |
| <p>Ticket keys should be rotated (replaced) on a frequent basis, | |
| as this is the only way to invalidate an existing session ticket - | |
| OpenSSL currently doesn't allow to specify a limit for ticket lifetimes. | |
| A new ticket key only gets used after restarting the web server. | |
| All existing session tickets become invalid after a restart.</p> | |
| <div class="warning"> | |
| <p>The ticket key file contains sensitive keying material and should | |
| be protected with file permissions similar to those used for | |
| <code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code>.</p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsessiontickets"><span id="SSLSessionTickets">SSLSessionTickets</span> Directive <a title="Permanent link" href="#sslsessiontickets" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable or disable use of TLS session tickets</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSessionTickets on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLSessionTickets on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.11 and later, if using OpenSSL 0.9.8f | |
| or later.</td></tr> | |
| </table> | |
| <p>This directive allows to enable or disable the use of TLS session tickets | |
| (RFC 5077).</p> | |
| <div class="warning"> | |
| <p>TLS session tickets are enabled by default. Using them without restarting | |
| the web server with an appropriate frequency (e.g. daily) compromises perfect | |
| forward secrecy.</p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsrpunknownuserseed"><span id="SSLSRPUnknownUserSeed">SSLSRPUnknownUserSeed</span> Directive <a title="Permanent link" href="#sslsrpunknownuserseed" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SRP unknown user seed</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSRPUnknownUserSeed <var>secret-string</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or | |
| later</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the seed used to fake SRP user parameters for unknown | |
| users, to avoid leaking whether a given user exists. Specify a secret | |
| string. If this directive is not used, then Apache will return the | |
| UNKNOWN_PSK_IDENTITY alert to clients who specify an unknown username. | |
| </p> | |
| <div class="example"><h3>Example</h3><p><code> | |
| SSLSRPUnknownUserSeed "secret" | |
| </code></p></div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslsrpverifierfile"><span id="SSLSRPVerifierFile">SSLSRPVerifierFile</span> Directive <a title="Permanent link" href="#sslsrpverifierfile" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Path to SRP verifier file</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLSRPVerifierFile <var>file-path</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or | |
| later</td></tr> | |
| </table> | |
| <p> | |
| This directive enables TLS-SRP and sets the path to the OpenSSL SRP (Secure | |
| Remote Password) verifier file containing TLS-SRP usernames, verifiers, salts, | |
| and group parameters.</p> | |
| <div class="example"><h3>Example</h3><p><code> | |
| SSLSRPVerifierFile "/path/to/file.srpv" | |
| </code></p></div> | |
| <p> | |
| The verifier file can be created with the <code>openssl</code> command line | |
| utility:</p> | |
| <div class="example"><h3>Creating the SRP verifier file</h3><p><code> | |
| openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username | |
| </code></p></div> | |
| <p> The value given with the optional <code>-userinfo</code> parameter is | |
| available in the <code>SSL_SRP_USERINFO</code> request environment variable.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingcache"><span id="SSLStaplingCache">SSLStaplingCache</span> Directive <a title="Permanent link" href="#sslstaplingcache" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the OCSP stapling cache</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingCache <var>type</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>Configures the cache used to store OCSP responses which get included | |
| in the TLS handshake if <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> | |
| is enabled. Configuration of a cache is mandatory for OCSP stapling. | |
| With the exception of <code>none</code> and <code>nonenotnull</code>, | |
| the same storage types are supported as with | |
| <code class="directive"><a href="#sslsessioncache">SSLSessionCache</a></code>.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingerrorcachetimeout"><span id="SSLStaplingErrorCacheTimeout">SSLStaplingErrorCacheTimeout</span> Directive <a title="Permanent link" href="#sslstaplingerrorcachetimeout" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before expiring invalid responses in the OCSP stapling cache</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingErrorCacheTimeout <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingErrorCacheTimeout 600</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>Sets the timeout in seconds before <em>invalid</em> responses | |
| in the OCSP stapling cache (configured through <code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code>) will expire. | |
| To set the cache timeout for valid responses, see | |
| <code class="directive"><a href="#sslstaplingstandardcachetimeout">SSLStaplingStandardCacheTimeout</a></code>.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingfaketrylater"><span id="SSLStaplingFakeTryLater">SSLStaplingFakeTryLater</span> Directive <a title="Permanent link" href="#sslstaplingfaketrylater" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Synthesize "tryLater" responses for failed OCSP stapling queries</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingFakeTryLater on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingFakeTryLater on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>When enabled and a query to an OCSP responder for stapling | |
| purposes fails, mod_ssl will synthesize a "tryLater" response for the | |
| client. Only effective if <code class="directive"><a href="#sslstaplingreturnrespondererrors">SSLStaplingReturnResponderErrors</a></code> | |
| is also enabled.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingforceurl"><span id="SSLStaplingForceURL">SSLStaplingForceURL</span> Directive <a title="Permanent link" href="#sslstaplingforceurl" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override the OCSP responder URI specified in the certificate's AIA extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingForceURL <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>This directive overrides the URI of an OCSP responder as obtained from | |
| the authorityInfoAccess (AIA) extension of the certificate. | |
| One potential use is when a proxy is used for retrieving OCSP queries.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingrespondertimeout"><span id="SSLStaplingResponderTimeout">SSLStaplingResponderTimeout</span> Directive <a title="Permanent link" href="#sslstaplingrespondertimeout" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Timeout for OCSP stapling queries</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponderTimeout <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponderTimeout 10</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>This option sets the timeout for queries to OCSP responders when | |
| <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is enabled | |
| and mod_ssl is querying a responder for OCSP stapling purposes.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingresponsemaxage"><span id="SSLStaplingResponseMaxAge">SSLStaplingResponseMaxAge</span> Directive <a title="Permanent link" href="#sslstaplingresponsemaxage" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable age for OCSP stapling responses</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponseMaxAge <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponseMaxAge -1</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>This option sets the maximum allowable age ("freshness") when | |
| considering OCSP responses for stapling purposes, i.e. when | |
| <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is turned on. | |
| The default value (<code>-1</code>) does not enforce a maximum age, | |
| which means that OCSP responses are considered valid as long as their | |
| <code>nextUpdate</code> field is in the future.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingresponsetimeskew"><span id="SSLStaplingResponseTimeSkew">SSLStaplingResponseTimeSkew</span> Directive <a title="Permanent link" href="#sslstaplingresponsetimeskew" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum allowable time skew for OCSP stapling response validation</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingResponseTimeSkew <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingResponseTimeSkew 300</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>This option sets the maximum allowable time skew when mod_ssl checks the | |
| <code>thisUpdate</code> and <code>nextUpdate</code> fields of OCSP responses | |
| which get included in the TLS handshake (OCSP stapling). Only applicable | |
| if <code class="directive"><a href="#sslusestapling">SSLUseStapling</a></code> is turned on.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingreturnrespondererrors"><span id="SSLStaplingReturnResponderErrors">SSLStaplingReturnResponderErrors</span> Directive <a title="Permanent link" href="#sslstaplingreturnrespondererrors" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Pass stapling related OCSP errors on to client</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingReturnResponderErrors on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingReturnResponderErrors on</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>When enabled, mod_ssl will pass responses from unsuccessful | |
| stapling related OCSP queries (such as responses with an overall status | |
| other than "successful", responses with a certificate status other than | |
| "good", expired responses etc.) on to the client. | |
| If set to <code>off</code>, only responses indicating a certificate status | |
| of "good" or "revoked" will be included in the TLS handshake. | |
| Responses with a "revoked" status are always included regardless of | |
| this setting, because suppressing a known revocation would be a | |
| security risk.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstaplingstandardcachetimeout"><span id="SSLStaplingStandardCacheTimeout">SSLStaplingStandardCacheTimeout</span> Directive <a title="Permanent link" href="#sslstaplingstandardcachetimeout" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Number of seconds before expiring responses in the OCSP stapling cache</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStaplingStandardCacheTimeout <var>seconds</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStaplingStandardCacheTimeout 3600</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>Sets the timeout in seconds before responses in the OCSP stapling cache | |
| (configured through <code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code>) | |
| will expire. This directive applies to <em>valid</em> responses, while | |
| <code class="directive"><a href="#sslstaplingerrorcachetimeout">SSLStaplingErrorCacheTimeout</a></code> is | |
| used for controlling the timeout for invalid/unavailable responses. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstoreuri"><span id="SSLStoreURI">SSLStoreURI</span> Directive <a title="Permanent link" href="#sslstoreuri" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server certificate and key store</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStoreURI <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.1 and later, when linked with | |
| OpenSSL v3 or later.</td></tr> | |
| </table> | |
| <p> | |
| This directive points to a certificate store containing certificates, | |
| intermediate certificates, and private keys, represented by a URI. | |
| </p> | |
| <p> | |
| If no scheme is specified, the path will default to a <var>file:</var> | |
| URI, pointing at PEM encoded data, or a PKCS12 file. Other schemes | |
| include, but are not limited to, <var>pkcs11:</var> for smartcards and | |
| HSMs, <var>cng:</var> for the Windows certificate store, and | |
| <var>handle:</var> for TPMs. On Windows, where a file path is also a | |
| valid URI, the <var>file:</var> scheme must be used. | |
| </p> | |
| <p> | |
| The directive can be specified multiple times with tightly scoped | |
| URIs to target specific certificates and keys, or could be specified | |
| with a general URI like <var>pkcs11:</var> that considers all possible | |
| certificates and keys. Certificates, intermediate certificates, and keys | |
| can be defined in any order. | |
| </p> | |
| <p>Certificates and keys are processed as follows. | |
| </p> | |
| <ul> | |
| <li>Leaf certificates that do not have the purpose <var>Server Authentication</var> | |
| are skipped.</li> | |
| <li>Remaining leaf certificates are checked whether the | |
| <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> and all | |
| <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code> directives match the | |
| hostname or IP address of the certificate, and if no match is found they | |
| are skipped.</li> | |
| <li>Intermediate certificates are considered for building certificate | |
| chains on a best effort basis.</li> | |
| <li>Keys are matched up with leaf certificates, any certificate | |
| without a private key is skipped.</li> | |
| <li>Leaf certificates with private keys are sorted oldest to newest and | |
| passed on for configuration.</li> | |
| <li>The most recently issued certificate and key pair for each algorithm | |
| type (RSA, ECDSA, etc) will be used for each virtual host.</li> | |
| <li>The server will report back to you how many certificates of each type | |
| were found to help you if no certificates match.</li> | |
| </ul> | |
| <p>If the private key is encrypted, the pass phrase dialog is forced | |
| at startup time.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># Example using a PEM-encoded file. | |
| SSLStoreURI "/usr/local/apache2/conf/ssl.crt/server.crt" | |
| # Example using a PKCS12 file. | |
| SSLStoreURI "/usr/local/apache2/conf/ssl.crt/server.p12" | |
| # Example use of a certificate and private key from a PKCS#11 token: | |
| SSLStoreURI "pkcs11:token=My%20Token%20Name;id=45"</pre> | |
| </div> | |
| <p>These URIs are read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The URI is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| <div class="warning"><h3>Using SSLCertificateFile and SSLStoreURI | |
| together</h3> | |
| <p> | |
| You can use both SSLCertificateFile and SSLStoreURI together, however | |
| there is no overlap between the mechanisms. A certificate defined by | |
| SSLCertificateFile will not be matched with a key from SSLStoreURI. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslstrictsnivhostcheck"><span id="SSLStrictSNIVHostCheck">SSLStrictSNIVHostCheck</span> Directive <a title="Permanent link" href="#sslstrictsnivhostcheck" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether to allow non-SNI clients to access a name-based virtual | |
| host. | |
| </td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLStrictSNIVHostCheck on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLStrictSNIVHostCheck off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets whether a non-SNI client is allowed to access a name-based | |
| virtual host. If set to <code>on</code> in the default name-based virtual | |
| host, clients that are SNI unaware will not be allowed to access <em>any</em> | |
| virtual host, belonging to this particular IP / port combination. | |
| If set to <code>on</code> in any other virtual host, SNI unaware clients | |
| are not allowed to access this particular virtual host. | |
| </p> | |
| <p> | |
| If set to <code>on</code> in server context (globally, outside any | |
| <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> block), | |
| the setting is inherited by all virtual hosts that do not override it. | |
| This has the same effect as setting it to <code>on</code> in every | |
| default name-based virtual host: non-SNI clients will be denied access | |
| to any name-based virtual host. | |
| </p> | |
| <div class="warning"><p> | |
| This option is only available if httpd was compiled against an SNI capable | |
| version of OpenSSL. | |
| </p></div> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLStrictSNIVHostCheck on</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="ssltrustrequesturi"><span id="SSLTrustRequestURI">SSLTrustRequestURI</span> Directive <a title="Permanent link" href="#ssltrustrequesturi" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>certificate store of CA Certificates for defining | |
| acceptable CA names</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLTrustRequestURI <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p>When a client certificate is requested by mod_ssl, a list of | |
| <em>acceptable Certificate Authority names</em> is sent to the client | |
| in the SSL handshake. These CA names can be used by the client to | |
| select an appropriate client certificate out of those it has | |
| available.</p> | |
| <p>If none of the directives <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code>, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code>, or <code class="directive">SSLTrustRequestURI</code> are given, then the | |
| set of acceptable CA names sent to the client is the names of all the | |
| CA certificates given by the <code class="directive"><a href="#sslcacertificatefile">SSLCACertificateFile</a></code>, <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>, and <code class="directive"><a href="#ssltrusturi">SSLTrustURI</a></code> directives; in other | |
| words, the names of the CAs which will actually be used to verify the | |
| client certificate.</p> | |
| <p>In some circumstances, it is useful to be able to send a set of | |
| acceptable CA names which differs from the actual CAs used to verify | |
| the client certificate - for example, if the client certificates are | |
| signed by intermediate CAs. In such cases, <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code>, <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code>, and/or <code class="directive">SSLTrustRequestURI</code> can be used; the | |
| acceptable CA names are then taken from the complete set of | |
| certificates in the directory and/or file specified by this pair of | |
| directives.</p> | |
| <p><code class="directive">SSLTrustRequestURI</code> must | |
| specify an <em>all-in-one</em> certificate store uri containing a | |
| set of CA certificates.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLTrustRequestURI "file:///usr/local/apache2/conf/ca-names.crt"</pre> | |
| </div> | |
| <p>A <var>file:</var> URI pointing at a file of PEM encoded certificates | |
| can be used instead of <code class="directive"><a href="#sslcadnrequestfile">SSLCADNRequestFile</a></code>, and a <var>file:</var> | |
| URI pointing at a directory of PEM encoded certificates can be used | |
| instead of <code class="directive"><a href="#sslcadnrequestpath">SSLCADNRequestPath</a></code>. | |
| </p> | |
| <p>This store is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The uri is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="ssltrusturi"><span id="SSLTrustURI">SSLTrustURI</span> Directive <a title="Permanent link" href="#ssltrusturi" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Server CA certificate store for Client Authentication</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLTrustURI <var>uri</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.5.1 and later, when linked with | |
| OpenSSL v3 or later.</td></tr> | |
| </table> | |
| <p> | |
| This directive sets URIs where you can assemble the Certificates of Certification | |
| Authorities (CA) whose <em>clients</em> you deal with. These are used for Client | |
| Authentication. This can be used alternatively and/or additionally to | |
| <code class="directive"><a href="#sslcacertificatefile">SSLCACertificateFile</a></code> | |
| or <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"># trust certs in a PEM encoded certificate bundle | |
| SSLTrustURI "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt" | |
| # trust all certs in a typical Linux machine | |
| SSLTrustURI "pkcs11:token=System%20Trust" | |
| # trust all certs in the Windows trust store | |
| SSLTrustURI "org.openssl.winstore:"</pre> | |
| </div> | |
| <p> | |
| This directive will also read in Certificate Revocation Lists (CRL) of | |
| Certification Authorities (CAs) whose clients you deal with. These are used | |
| to revoke the client certificate on Client Authentication.</p> | |
| <p>This URI is read at server startup, while the server is still running | |
| as <code>root</code> (before privilege dropping), so it may be owned by | |
| and readable only by <code>root</code>. The URI is not re-read during | |
| normal operation; a server restart is required for changes to take | |
| effect.</p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslusername"><span id="SSLUserName">SSLUserName</span> Directive <a title="Permanent link" href="#sslusername" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Variable name to determine user name</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLUserName <var>varname</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the "user" field in the Apache request object. | |
| This is used by lower modules to identify the user with a character | |
| string. In particular, this may cause the environment variable | |
| <code>REMOTE_USER</code> to be set. The <var>varname</var> can be | |
| any of the <a href="#envvars">SSL environment variables</a>.</p> | |
| <p>When the <code>FakeBasicAuth</code> option (see | |
| <a href="#ssloptions">SSLOptions</a>) or the | |
| <code class="directive"><a href="#authbasicfake">AuthBasicFake</a></code> directive is in | |
| effect, this directive controls which part of the client certificate is | |
| used as the username. Without <code class="directive">SSLUserName</code>, | |
| <code>REMOTE_USER</code> may not be set for other modules and CGI scripts.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLUserName SSL_CLIENT_S_DN_CN</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslusestapling"><span id="SSLUseStapling">SSLUseStapling</span> Directive <a title="Permanent link" href="#sslusestapling" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable stapling of OCSP responses in the TLS handshake</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLUseStapling on|off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLUseStapling off</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available if using OpenSSL 0.9.8h or later</td></tr> | |
| </table> | |
| <p>This option enables OCSP stapling, as defined by the "Certificate | |
| Status Request" TLS extension specified in RFC 6066. If enabled (and | |
| requested by the client), mod_ssl will include an OCSP response | |
| for its own certificate in the TLS handshake. Configuring an | |
| <code class="directive"><a href="#sslstaplingcache">SSLStaplingCache</a></code> is a | |
| prerequisite for enabling OCSP stapling.</p> | |
| <p>OCSP stapling relieves the client of querying the OCSP responder | |
| on its own, but it should be noted that with the RFC 6066 specification, | |
| the server's <code>CertificateStatus</code> reply may only include an | |
| OCSP response for a single cert. For server certificates with intermediate | |
| CA certificates in their chain (the typical case nowadays), | |
| stapling in its current implementation therefore only partially achieves the | |
| stated goal of "saving roundtrips and resources" - see also | |
| <a href="https://www.rfc-editor.org/rfc/rfc6961">RFC 6961</a> | |
| (TLS Multiple Certificate Status Extension). | |
| </p> | |
| <p>When OCSP stapling is enabled, the <code>ssl-stapling</code> mutex is used | |
| to control access to the OCSP stapling cache in order to prevent corruption, | |
| and the <code>sss-stapling-refresh</code> mutex is used to control refreshes | |
| of OCSP responses. These mutexes can be configured using the | |
| <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive. | |
| </p> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslverifyclient"><span id="SSLVerifyClient">SSLVerifyClient</span> Directive <a title="Permanent link" href="#sslverifyclient" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Type of Client Certificate verification</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyClient <var>level</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyClient none</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets the Certificate verification level for the Client | |
| Authentication. Notice that this directive can be used both in per-server and | |
| per-directory context. In per-server context it applies to the client | |
| authentication process used in the standard SSL handshake when a connection is | |
| established. In per-directory context it forces a SSL renegotiation with the | |
| reconfigured client verification level after the HTTP request was read but | |
| before the HTTP response is sent.</p> | |
| <p> | |
| The following levels are available for <var>level</var>:</p> | |
| <ul> | |
| <li><strong>none</strong>: | |
| no client Certificate is required at all</li> | |
| <li><strong>optional</strong>: | |
| the client <em>may</em> present a valid Certificate</li> | |
| <li><strong>require</strong>: | |
| the client <em>has to</em> present a valid Certificate</li> | |
| <li><strong>optional_no_ca</strong>: | |
| the client may present a valid Certificate<br> | |
| but it need not to be (successfully) verifiable. This option | |
| cannot be relied upon for client authentication. </li> | |
| </ul> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyClient require</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslverifydepth"><span id="SSLVerifyDepth">SSLVerifyDepth</span> Directive <a title="Permanent link" href="#sslverifydepth" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum depth of CA Certificates in Client | |
| Certificate verification</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVerifyDepth <var>number</var></code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVerifyDepth 1</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> | |
| <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| </table> | |
| <p> | |
| This directive sets how deeply mod_ssl should verify before deciding that the | |
| clients don't have a valid certificate. Notice that this directive can be | |
| used both in per-server and per-directory context. In per-server context it | |
| applies to the client authentication process used in the standard SSL | |
| handshake when a connection is established. In per-directory context it forces | |
| a SSL renegotiation with the reconfigured client verification depth after the | |
| HTTP request was read but before the HTTP response is sent.</p> | |
| <p> | |
| The depth actually is the maximum number of intermediate certificate issuers, | |
| i.e. the number of CA certificates which are max allowed to be followed while | |
| verifying the client certificate. A depth of 0 means that self-signed client | |
| certificates are accepted only, the default depth of 1 means the client | |
| certificate can be self-signed or has to be signed by a CA which is directly | |
| known to the server (i.e. the CA's certificate is under | |
| <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>), etc.</p> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVerifyDepth 10</pre> | |
| </div> | |
| </div> | |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif"></a></div> | |
| <div class="directive-section"><h2 id="sslvhostsnipolicy"><span id="SSLVHostSNIPolicy">SSLVHostSNIPolicy</span> Directive <a title="Permanent link" href="#sslvhostsnipolicy" class="permalink">¶</a></h2> | |
| <table class="directive"> | |
| <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set compatibility policy for SNI client access to virtual hosts.</td></tr> | |
| <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSLVHostSNIPolicy strict|secure|authonly|insecure</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSLVHostSNIPolicy secure</code></td></tr> | |
| <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> | |
| <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> | |
| <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ssl</td></tr> | |
| <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.4.66 and later</td></tr> | |
| </table><p>This directive sets the policy applied when checking whether the | |
| <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> | |
| identified by the <code>Host</code> request header in an HTTP request | |
| is compatible with the <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> identified from the SNI | |
| extension sent during the initial TLS connection handshake. If an HTTP | |
| request is associated with a virtual host which has an incompatible | |
| SSL/TLS configuration under the policy used, an HTTP error response | |
| with status code 421 ("Misdirected Request") will be sent.</p> | |
| <p>The policy also applies to TLS connections where an SNI extension | |
| is not sent during the handshake, implicitly using the default or | |
| first virtual host definition. If the Host header in an HTTP request | |
| on such a connection identifies any other non-default virtual host, | |
| the compatibility policy is tested.</p> | |
| <p>The <code>strict</code> policy blocks all HTTP requests which are | |
| identified with a different virtual host to that identified by SNI. | |
| The <code>insecure</code> policy allows all HTTP requests regardless | |
| of virtual host identified; such a configuration may be vulnerable to | |
| <a href="https://httpd.apache.org/security/vulnerabilities_24.html">CVE-2025-23048</a>. | |
| </p> | |
| <p>The (default) <code>secure</code>, and <code>authonly</code> | |
| policies compare specific aspects of the SSL configuration for the two | |
| virtual hosts, which are grouped into two categories:</p> | |
| <ul> | |
| <li><strong>server certificate/key, or protocol/cipher | |
| restrictions</strong>: directives which determine the server | |
| certificate or key (<code class="directive"><a href="#sslcertificatekeyfile">SSLCertificateKeyFile</a></code> etc), cipher or | |
| protocol restrictions (<code class="directive"><a href="#sslciphersuite">SSLCipherSuite</a></code> and <code class="directive"><a href="#sslprotocol">SSLProtocol</a></code>)</li> | |
| <li><strong>client verification and authentication | |
| settings</strong>: directives which affect TLS client certificate | |
| verification or authentication, such as <code class="directive"><a href="#sslverifyclient">SSLVerifyClient</a></code>, <code class="directive"><a href="#sslverifymode">SSLVerifyMode</a></code>, <code class="directive"><a href="#sslcacertificatepath">SSLCACertificatePath</a></code>, <code class="directive"><a href="#sslsrpverifierfile">SSLSRPVerifierFile</a></code>; any use of <code class="directive"><a href="#sslopensslconfcmd">SSLOpenSSLConfCmd</a></code></li> | |
| </ul> | |
| <p>This table illustrates whether an HTTP request will be blocked or | |
| allowed when the virtual host configurations differ as described, | |
| under each different policy setting:</p> | |
| <table class="bordered"><tr class="header"> | |
| <th>Policy mode</th> | |
| <th>Any VirtualHost mismatch</th> | |
| <th>Server certificate/key, <br>or protocol/cipher restrictions</th> | |
| <th>Client verification/<br>authentication settings</th> | |
| </tr> | |
| <tr> | |
| <td><code>strict</code></td><td>blocked</td><td>blocked</td><td>blocked</td> | |
| </tr> | |
| <tr class="odd"> | |
| <td><code>secure</code></td><td>allowed</td><td>blocked</td><td>blocked</td> | |
| </tr> | |
| <tr> | |
| <td><code>authonly</code></td><td>allowed</td><td>allowed</td><td>blocked</td> | |
| </tr> | |
| <tr class="odd"> | |
| <td><code>insecure</code></td><td>allowed</td><td>allowed</td><td>allowed</td> | |
| </tr> | |
| </table> | |
| <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">SSLVHostSNIPolicy authonly</pre> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="bottomlang"> | |
| <p><span>Available Languages: </span><a href="../en/mod/mod_ssl.html" title="English"> en </a> | | |
| <a href="../es/mod/mod_ssl.html" hreflang="es" rel="alternate" title="Español"> es </a> | | |
| <a href="../fr/mod/mod_ssl.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> | |
| </div><div id="footer"> | |
| <p class="apache">Copyright 2026 The Apache Software Foundation.<br>Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> | |
| <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="https://cwiki.apache.org/confluence/display/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a> | <a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2">Report a bug</a></p></div><script><!--//--><![CDATA[//><!-- | |
| if (typeof(prettyPrint) !== 'undefined') { | |
| prettyPrint(); | |
| } | |
| var langToggle = document.querySelector('.lang-toggle'); | |
| var topLang = document.querySelector('.toplang'); | |
| if (langToggle && topLang) { | |
| langToggle.addEventListener('click', function() { topLang.classList.toggle('open'); }); | |
| } | |
| var qv = document.getElementById('quickview'); | |
| if (qv) { | |
| document.body.appendChild(qv); | |
| var qvBtn = document.createElement('button'); | |
| qvBtn.className = 'qv-toggle'; | |
| qvBtn.setAttribute('aria-label', 'Toggle page navigation'); | |
| qvBtn.innerHTML = '☰'; | |
| document.body.appendChild(qvBtn); | |
| qvBtn.addEventListener('click', function() { | |
| var isOpen = qv.classList.toggle('open'); | |
| if (isOpen) { | |
| qv.style.top = window.scrollY + 10 + 'px'; | |
| } | |
| }); | |
| window.addEventListener('scroll', function() { qv.classList.remove('open'); }); | |
| } | |
| //--><!]]></script> | |
| </body></html> |