<identifier>ssl_module</identifier>
<summary>
-<p>This module provides SSL v2/v3 and TLS v1 support for the Apache
-HTTP Server. It was contributed by Ralf S. Engelschall based on his
-mod_ssl project and originally derived from work by Ben Laurie.</p>
+<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="http://www.openssl.org/">OpenSSL</a>
to provide the cryptography engine.</p>
<section id="envvars"><title>Environment Variables</title>
-<p>This module provides a lot of SSL information as additional environment
-variables to the SSI and CGI namespace. The generated variables are listed in
-the table below. For backward compatibility the information can
+<p>This module can be configured to provide several items of SSL information
+as additional environment variables to the SSI and CGI namespace. This
+information is not provided by default for performance reasons. (See
+<directive>SSLOptions</directive> StdEnvVars, 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>
<th>Description:</th>
</tr>
<tr><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr>
-<tr><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr>
+<tr><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><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><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>
<tr><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><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr>
+<tr><td><code>SSL_CLIENT_SAN_Email_</code><em>n</em></td> <td>string</td> <td>Client certificate's subjectAltName extension entries of type rfc822Name</td></tr>
+<tr><td><code>SSL_CLIENT_SAN_DNS_</code><em>n</em></td> <td>string</td> <td>Client certificate's subjectAltName extension entries of type dNSName</td></tr>
<tr><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>
<tr><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></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><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><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><em>n</em></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr>
+<tr><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><em>reason</em></td></tr>
<tr><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><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><em>n</em></td> <td>string</td> <td>Server certificate's subjectAltName extension entries of type rfc822Name</td></tr>
+<tr><td><code>SSL_SERVER_SAN_DNS_</code><em>n</em></td> <td>string</td> <td>Server certificate's subjectAltName extension entries of type dNSName</td></tr>
<tr><td><code>SSL_SERVER_S_DN_</code><em>x509</em></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><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</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><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><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><td><code>SSL_TLS_SNI</code></td> <td>string</td> <td>Contents of the SNI TLS extension (if supplied with ClientHello)</td></tr>
</table>
<p><em>x509</em> 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 Apache 2.1 and
later, <em>x509</em> 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 an index to select a particular
-attribute. For example, where the server certificate subject DN
-included two OU fields, <code>SSL_SERVER_S_DN_OU_0</code> and
-<code>SSL_SERVER_S_DN_OU_1</code> could be used to reference each.</p>
+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 <directive module="mod_ssl">SSLOptions</directive> 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>The format of the <em>*_DN</em> variables has changed in Apache HTTPD
+2.3.11. See the <code>LegacyDNStringFormat</code> option for
+<directive module="mod_ssl">SSLOptions</directive> for details.</p>
<p><code>SSL_CLIENT_V_REMAIN</code> is only available in version 2.1
and later.</p>
<dt><code>ENV:<em>variablename</em></code></dt>
<dd>This will expand to the standard environment
variable <em>variablename</em>.</dd>
-
+
<dt><code>HTTP:<em>headername</em></code></dt>
<dd>This will expand to the value of the request header with name
<em>headername</em>.</dd>
<p>When <module>mod_ssl</module> 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
+href="mod_log_config.html#formats">Custom Log Format</a> of
<module>mod_log_config</module>. First there is an
additional ``<code>%{</code><em>varname</em><code>}x</code>''
eXtension format function which can be used to expand any variables
provided. Information about this function is provided in the <a
href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p>
<example><title>Example</title>
-CustomLog logs/ssl_request_log \
- "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+<highlight language="config">
+CustomLog logs/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+</highlight>
</example>
</section>
encrypted with SSL. This is similar to the
<directive>SSLRequireSSL</directive> directive.</p>
- <example>
+ <highlight language="config">
Require ssl
- </example>
+ </highlight>
</section>
<p>The following example grants access if the user is authenticated
either with a client certificate or by username and password.</p>
- <example>
+ <highlight language="config">
Require ssl-verify-client<br/>
Require valid-user
- </example>
+ </highlight>
</section>
<directivesynopsis>
<name>SSLPassPhraseDialog</name>
-<description>Type of pass phrase dialog for encrypted private
+<description>Type of pass phrase dialog for encrypted private
keys</description>
<syntax>SSLPassPhraseDialog <em>type</em></syntax>
<default>SSLPassPhraseDialog builtin</default>
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>
+<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
<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 two arguments (the first is
- of the form ``<code>servername:portnumber</code>'', the second is either
- ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which
- server and algorithm 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>
+ 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
program is called only once per unique Pass Phrase.</p></li>
</ul>
<example><title>Example</title>
+<highlight language="config">
SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLRandomSeed</name>
-<description>Pseudo Random Number Generator (PRNG) seeding
+<description>Pseudo Random Number Generator (PRNG) seeding
source</description>
-<syntax>SSLRandomSeed <em>context</em> <em>source</em>
+<syntax>SSLRandomSeed <em>context</em> <em>source</em>
[<em>bytes</em>]</syntax>
<contextlist><context>server config</context></contextlist>
The following <em>source</em> variants are available:</p>
<ul>
<li><code>builtin</code>
- <p> This is the always available builtin seeding source. It's usage
+ <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 (when applicable) a randomly
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>
- <p>
- On some platforms like FreeBSD one can even control how the entropy is
- actually generated, i.e. by which system interrupts. More details one can
- find under <em>rndcontrol(8)</em> on those platforms. Alternatively, when
- your system lacks such a random device, you can use tool
- like <a href="http://www.lothar.com/tech/crypto/">EGD</a>
- (Entropy Gathering Daemon) and run it's client program with the
- <code>exec:/path/to/program/</code> variant (see below) or use
- <code>egd:/path/to/egd-socket</code> (see below).</p></li>
+ be the best.</p></li>
<li><code>exec:/path/to/program</code>
<p>
on your platform.</p></li>
</ul>
<example><title>Example</title>
-SSLRandomSeed startup builtin<br />
-SSLRandomSeed startup file:/dev/random<br />
-SSLRandomSeed startup file:/dev/urandom 1024<br />
-SSLRandomSeed startup exec:/usr/local/bin/truerand 16<br />
-SSLRandomSeed connect builtin<br />
-SSLRandomSeed connect file:/dev/random<br />
-SSLRandomSeed connect file:/dev/urandom 1024<br />
+<highlight language="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
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLSessionCache</name>
-<description>Type of the global/inter-process SSL Session
+<description>Type of the global/inter-process SSL Session
Cache</description>
<syntax>SSLSessionCache <em>type</em></syntax>
<default>SSLSessionCache none</default>
<em>different</em> pre-forked server processes. Here an inter-process cache
helps to avoid unnecessary session handshakes.</p>
<p>
-The following four storage <em>type</em>s are currently supported:</p>
+The following five storage <em>type</em>s are currently supported:</p>
<ul>
<li><code>none</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.</p></li>
+ processes. This session cache may suffer reliability issues under
+ high load. To use this, ensure that
+ <module>mod_socache_dbm</module> is loaded.</p></li>
-<li><code>shm:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>]
+<li><code>shmcb:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>]
<p>This makes use of a high-performance cyclic buffer
(approx. <em>size</em> 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.</p></li>
+ processes. This is the recommended session cache. To use this,
+ ensure that <module>mod_socache_shmcb</module> is loaded.</p></li>
<li><code>dc:UNIX:/path/to/socket</code>
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.</p></li>
+ address. To use this, ensure that
+ <module>mod_socache_dc</module> is loaded.</p></li>
</ul>
<example><title>Examples</title>
-SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data<br />
-SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
+<highlight language="config">
+SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
+SSLSessionCache shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)
+</highlight>
</example>
<p>The <code>ssl-cache</code> mutex is used to serialize access to
<default>SSLSessionCacheTimeout 300</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
+<compatibility>Applies also to RFC 5077 TLS session resumption in Apache 2.4.10 and later</compatibility>
<usage>
<p>
This directive sets the timeout in seconds for the information stored in the
-global/inter-process SSL Session Cache and the OpenSSL internal memory cache.
+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>
<example><title>Example</title>
+<highlight language="config">
SSLSessionCacheTimeout 600
+</highlight>
</example>
</usage>
</directivesynopsis>
that virtual host. By default the SSL/TLS Protocol Engine is
disabled for both the main server and all configured virtual hosts.</p>
<example><title>Example</title>
-<VirtualHost _default_:443><br />
-SSLEngine on<br />
-...<br />
+<highlight language="config">
+<VirtualHost _default_:443>
+SSLEngine on
+#...
</VirtualHost>
+</highlight>
</example>
-<p>In Apache 2.1 and later, <directive>SSLEngine</directive> can be set to
-<code>optional</code>. This enables support for
-<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS
+<p>In Apache 2.1 and later, <directive>SSLEngine</directive> can be set to
+<code>optional</code>. This enables support for
+<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS
Within HTTP/1.1. At this time no web browsers support RFC 2817.</p>
</usage>
</directivesynopsis>
<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
+with conflicting settings (SSLFIPS on followed by SSLFIPS off or
similar). The mode applies to all SSL library operations.
</p>
<p>
<directivesynopsis>
<name>SSLProtocol</name>
-<description>Configure usable SSL protocol versions</description>
+<description>Configure usable SSL/TLS protocol versions</description>
<syntax>SSLProtocol [+|-]<em>protocol</em> ...</syntax>
<default>SSLProtocol all</default>
<contextlist><context>server config</context>
<usage>
<p>
-This directive can be used to control which versions of the SSL protocol
+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) <em>protocol</em>s are:</p>
<ul>
-<li><code>SSLv2</code>
- <p>
- This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the
- original SSL protocol as designed by Netscape Corporation. Though it's
- use has been deprecated, because of weaknesses in the security of the protocol.</p></li>
-
<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. It's supported by
- almost all popular browsers.</p></li>
+ the Netscape Corporation.
+ It is the successor to SSLv2 and the predecessor to TLSv1.</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="http://www.ietf.org/rfc/rfc2246.txt">RFC2246</a>.
- Which has been obsoleted by <a href="http://www.ietf.org/rfc/rfc4346.txt">RFC4346</a>.</p></li>
+ This is the Transport Layer Security (TLS) protocol, version 1.0.
+ It is the successor to SSLv3 and is defined in
+ <a href="http://www.ietf.org/rfc/rfc2246.txt">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="http://www.ietf.org/rfc/rfc4346.txt">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="http://www.ietf.org/rfc/rfc5246.txt">RFC 5246</a>.</p></li>
-<li><code>All</code>
+<li><code>all</code>
<p>
- This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a
- convenient way for enabling all protocols except one when used in
- combination with the minus sign on a protocol as the example above
- shows.</p></li>
+ 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</code>, respectively.</p></li>
</ul>
<example><title>Example</title>
-# enable SSLv3 and TLSv1, but not SSLv2<br />
-SSLProtocol all -SSLv2
+<highlight language="config">
+SSLProtocol TLSv1
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCipherSuite</name>
-<description>Cipher Suite available for negotiation in SSL
+<description>Cipher Suite available for negotiation in SSL
handshake</description>
<syntax>SSLCipherSuite <em>cipher-spec</em></syntax>
-<default>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</default>
+<default>SSLCipherSuite DEFAULT (depends on OpenSSL version)</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
attributes plus a few extra minor ones:</p>
<ul>
<li><em>Key Exchange Algorithm</em>:<br />
- RSA or Diffie-Hellman variants.
+ RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password
</li>
<li><em>Authentication Algorithm</em>:<br />
- RSA, Diffie-Hellman, DSS or none.
+ RSA, Diffie-Hellman, DSS, ECDSA, or none.
</li>
<li><em>Cipher/Encryption Algorithm</em>:<br />
- DES, Triple-DES, RC4, RC2, IDEA or none.
+ AES, DES, Triple-DES, RC4, RC2, IDEA, etc.
</li>
<li><em>MAC Digest Algorithm</em>:<br />
- MD5, SHA or SHA1.
+ MD5, SHA or SHA1, SHA256, SHA384.
</li>
</ul>
-<p>An SSL cipher can also be an export cipher and is either an SSLv2 or SSLv3/TLSv1
-cipher (here TLSv1 is equivalent to SSLv3). 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>).</p>
+<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 border="1">
<columnspec><column width=".5"/><column width=".5"/></columnspec>
<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 encoding</td> </tr>
-<tr><td><code>DES</code></td> <td>DES encoding</td> </tr>
-<tr><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr>
-<tr><td><code>RC4</code></td> <td>RC4 encoding</td> </tr>
-<tr><td><code>RC2</code></td> <td>RC2 encoding</td> </tr>
-<tr><td><code>IDEA</code></td> <td>IDEA encoding</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>SHA 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>SSLv2</code></td> <td>all SSL version 2.0 ciphers</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>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>NULL</code></td> <td>all ciphers using no encryption</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>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM,
+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 <em>cipher-spec</em>. Available
prefixes are:</p>
<ul>
<li>none: add cipher to list</li>
-<li><code>+</code>: add ciphers to list and pull them to current location in 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>
+
+<note>
+<title><code>aNULL</code>, <code>eNULL</code> and <code>EXP</code>
+ciphers are always disabled</title>
+<p>Beginning with version 2.4.7, null and export-grade
+ciphers are always disabled, as mod_ssl unconditionally prepends any supplied
+cipher suite string with <code>!aNULL:!eNULL:!EXP:</code> at initialization.</p>
+</note>
+
<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 <em>cipher-spec</em> string. The default <em>cipher-spec</em> string
-is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which
-means the following: first, remove from consideration any ciphers that do not
-authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
-use ciphers using RC4 and RSA. Next include the high, medium and then the low
-security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the
-end of the list.</p>
+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>
<example>
<pre>
-$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
-NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1
-NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5
-EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
+$ 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
... ... ... ... ...
-EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
-EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
-EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+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>
</example>
<p>The complete list of particular RSA & DH ciphers for SSL is given in <a
href="#table2">Table 2</a>.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
+</highlight>
</example>
<table border="1">
<columnspec><column width=".3"/><column width=".1"/><column width=".13"/>
<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>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</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>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td></td> </tr>
-<tr><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td></td> </tr>
-<tr><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td></td> </tr>
<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>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td></td> </tr>
-<tr><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td></td> </tr>
<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>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr>
-<tr><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr>
<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>
<directivesynopsis>
<name>SSLCertificateFile</name>
-<description>Server PEM-encoded X.509 Certificate file</description>
+<description>Server PEM-encoded X.509 certificate data file</description>
<syntax>SSLCertificateFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
<p>
-This directive points to the PEM-encoded Certificate file for the server and
-optionally also to the corresponding RSA or DSA Private Key file for it
-(contained in the same file). If the contained Private Key is encrypted the
-Pass Phrase dialog is forced at startup time. This directive can be used up to
-two times (referencing different filenames) when both a RSA and a DSA based
-server certificate is used in parallel.</p>
+This directive points to a file with certificate data in PEM format.
+At a minimum, the file must include an end-entity (leaf) certificate.
+Beginning with version 2.4.8, it may also include intermediate CA
+certificates, sorted from leaf to root, and obsoletes
+<directive module="mod_ssl">SSLCertificateChainFile</directive>.
+</p>
+
+<p>
+Additional optional elements are DH parameters and/or an EC curve name
+for ephemeral keys, as generated by <code>openssl dhparam</code> and
+<code>openssl ecparam</code>, respectively (supported in version 2.4.7
+or later) and finally, the end-entity certificate's private key.
+If the private key is encrypted, the pass phrase dialog is forced
+at startup time.</p>
+
+<p>
+This 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 1.0.0 or later,
+<code>openssl list-public-key-algorithms</code> will output a list
+of supported algorithms.</p>
+
+<p>
+When running with OpenSSL 1.0.2 or later, this directive allows
+to configure the intermediate CA chain on a per-certificate basis,
+which removes a limitation of the (now obsolete)
+<directive module="mod_ssl">SSLCertificateChainFile</directive> directive.
+DH and ECDH parameters, however, are only read from the first
+<directive>SSLCertificateFile</directive> directive, as they
+are applied independently of the authentication algorithm type.</p>
+
+<note>
+<title>DH parameter interoperability with primes > 1024 bit</title>
+<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="http://www.ietf.org/rfc/rfc3526.txt">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>
+</note>
+
<example><title>Example</title>
+<highlight language="config">
SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCertificateKeyFile</name>
-<description>Server PEM-encoded Private Key file</description>
+<description>Server PEM-encoded private key file</description>
<syntax>SSLCertificateKeyFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
<usage>
<p>
-This directive points to the PEM-encoded Private Key file for the
-server. If the Private Key is not combined with the Certificate in the
-<directive>SSLCertificateFile</directive>, use this additional directive to
-point to the file with the stand-alone Private Key. When
-<directive>SSLCertificateFile</directive> is used and the file
-contains both the Certificate and the Private Key this directive need
-not be used. But we strongly discourage this practice. Instead we
-recommend you to separate the Certificate and the Private Key. If the
-contained Private Key is encrypted, the Pass Phrase dialog is forced
-at startup time. This directive can be used up to two times
-(referencing different filenames) when both a RSA and a DSA based
-private key is used in parallel.</p>
+This directive points to the PEM-encoded private key file for the
+server (the private key may also be combined with the certificate in the
+<directive module="mod_ssl">SSLCertificateFile</directive>, but this practice
+is discouraged). 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
+<directive module="mod_ssl">SSLCertificateKeyFile</directive>
+directive, there must be a matching <directive>SSLCertificateFile</directive>
+directive.</p>
+
<example><title>Example</title>
+<highlight language="config">
SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key
+</highlight>
</example>
</usage>
</directivesynopsis>
<context>virtual host</context></contextlist>
<usage>
+<note><title>SSLCertificateChainFile is deprecated</title>
+<p><code>SSLCertificateChainFile</code> became obsolete with version 2.4.8,
+when <directive module="mod_ssl">SSLCertificateFile</directive>
+was extended to also load intermediate CA certificates from the server
+certificate file.</p>
+</note>
+
<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
certificates use the <em>same</em> certificate chain. Else the browsers will be
confused in this situation.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCACertificatePath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
Client Auth</description>
<syntax>SSLCACertificatePath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
hash filenames. So usually you can't just place the Certificate files
there: you also have to create symbolic links named
<em>hash-value</em><code>.N</code>. And you should always make sure this directory
-contains the appropriate symbolic links. Use the <code>Makefile</code> which
-comes with mod_ssl to accomplish this task.</p>
+contains the appropriate symbolic links.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCACertificateFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for Client Auth</description>
<syntax>SSLCACertificateFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
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
+preference. This can be used alternatively and/or additionally to
<directive module="mod_ssl">SSLCACertificatePath</directive>.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCADNRequestFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for defining acceptable CA names</description>
<syntax>SSLCADNRequestFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
PEM-encoded CA certificates.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCADNRequestPath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
defining acceptable CA names</description>
<syntax>SSLCADNRequestPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
through hash filenames. So usually you can't just place the
Certificate files there: you also have to create symbolic links named
<em>hash-value</em><code>.N</code>. And you should always make sure
-this directory contains the appropriate symbolic links. Use the
-<code>Makefile</code> which comes with mod_ssl to accomplish this
-task.</p>
+this directory contains the appropriate symbolic links.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCADNRequestPath /usr/local/apache2/conf/ca-names.crt/
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCARevocationPath</name>
-<description>Directory of PEM-encoded CA CRLs for
+<description>Directory of PEM-encoded CA CRLs for
Client Auth</description>
<syntax>SSLCARevocationPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
hash filenames. So usually you have not only to place the CRL files there.
Additionally you have to create symbolic links named
<em>hash-value</em><code>.rN</code>. And you should always make sure this directory
-contains the appropriate symbolic links. Use the <code>Makefile</code> which
-comes with <module>mod_ssl</module> to accomplish this task.</p>
+contains the appropriate symbolic links.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLCARevocationFile</name>
-<description>File of concatenated PEM-encoded CA CRLs for
+<description>File of concatenated PEM-encoded CA CRLs for
Client Auth</description>
<syntax>SSLCARevocationFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
used alternatively and/or additionally to <directive
module="mod_ssl">SSLCARevocationPath</directive>.</p>
<example><title>Example</title>
+<highlight language="config">
SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl
+</highlight>
+</example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLCARevocationCheck</name>
+<description>Enable CRL-based revocation checking</description>
+<syntax>SSLCARevocationCheck chain|leaf|none</syntax>
+<default>SSLCARevocationCheck none</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+<p>
+Enables certificate revocation list (CRL) checking. At least one of
+<directive module="mod_ssl">SSLCARevocationFile</directive>
+or <directive module="mod_ssl">SSLCARevocationPath</directive> 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>
+<note>
+<title>When set to <code>chain</code> or <code>leaf</code>,
+CRLs <em>must</em> be available for successful validation</title>
+<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
+<directive module="mod_ssl">SSLCARevocationFile</directive>
+or <directive module="mod_ssl">SSLCARevocationPath</directive>.
+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>
+</note>
+<example><title>Example</title>
+<highlight language="config">
+SSLCARevocationCheck chain
+</highlight>
</example>
</usage>
</directivesynopsis>
<strong>optional_no_ca</strong> is actually against the idea of
authentication (but can be used to establish SSL test pages, etc.)</p>
<example><title>Example</title>
+<highlight language="config">
SSLVerifyClient require
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLVerifyDepth</name>
-<description>Maximum depth of CA Certificates in Client
+<description>Maximum depth of CA Certificates in Client
Certificate verification</description>
<syntax>SSLVerifyDepth <em>number</em></syntax>
<default>SSLVerifyDepth 1</default>
known to the server (i.e. the CA's certificate is under
<directive module="mod_ssl">SSLCACertificatePath</directive>), etc.</p>
<example><title>Example</title>
+<highlight language="config">
SSLVerifyDepth 10
+</highlight>
+</example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLSRPVerifierFile</name>
+<description>Path to SRP verifier file</description>
+<syntax>SSLSRPVerifierFile <em>file-path</em></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or
+later</compatibility>
+
+<usage>
+<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>
+<example><title>Example</title>
+SSLSRPVerifierFile "/path/to/file.srpv"
+</example>
+<p>
+The verifier file can be created with the <code>openssl</code> command line
+utility:</p>
+<example><title>Creating the SRP verifier file</title>
+openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username
+</example>
+<p> The value given with the optional <code>-userinfo</code> parameter is
+avalable in the <code>SSL_SRP_USERINFO</code> request environment variable.</p>
+
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLSRPUnknownUserSeed</name>
+<description>SRP unknown user seed</description>
+<syntax>SSLSRPUnknownUserSeed <em>secret-string</em></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or
+later</compatibility>
+
+<usage>
+<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>
+<example><title>Example</title>
+SSLSRPUnknownUserSeed "secret"
</example>
</usage>
</directivesynopsis>
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><em>certificate</em><code>.crt</code>). 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>
+ </code><em>certificate</em><code>.crt</code>). The optional <directive
+ module="mod_ssl">SSLUserName</directive> 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 <directive module="mod_auth_basic">AuthBasicFake</directive>
+ directive within <module>mod_auth_basic</module> can be used as a more
+ general mechanism for faking basic authentication, giving control over the
+ structure of both the username and password.</p>
</li>
<li><code>StrictRequire</code>
<p>
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 maybe not what the user expects, so enable this on a
+ 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>
<example><title>Example</title>
-SSLOptions +FakeBasicAuth -StrictRequire<br />
-<Files ~ "\.(cgi|shtml)$"><br />
- SSLOptions +StdEnvVars -ExportCertData<br />
+<highlight language="config">
+SSLOptions +FakeBasicAuth -StrictRequire
+<Files ~ "\.(cgi|shtml)$">
+ SSLOptions +StdEnvVars -ExportCertData
<Files>
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLRequireSSL</name>
-<description>Deny access when SSL is not used for the
+<description>Deny access when SSL is not used for the
HTTP request</description>
<syntax>SSLRequireSSL</syntax>
<contextlist><context>directory</context>
stuff that should be protected. When this directive is present all requests
are denied which are not using SSL.</p>
<example><title>Example</title>
+<highlight language="config">
SSLRequireSSL
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLRequire</name>
-<description>Allow access only when an arbitrarily complex
+<description>Allow access only when an arbitrarily complex
boolean expression is true</description>
<syntax>SSLRequire <em>expression</em></syntax>
<contextlist><context>directory</context>
<override>AuthConfig</override>
<usage>
+
+<note><title>SSLRequire is deprecated</title>
+<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>
+
+</note>
+
<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
</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 following functions are available:</p>
-<ul>
-<li><code>file(</code><em>filename</em><code>)</code>
- <p>
- This function takes one string argument and expands to the contents of the
- file. This is especially useful for matching this contents against a
- regular expression, etc.</p>
-</li>
-</ul>
-<p>Notice that <em>expression</em> is first parsed into an internal machine
-representation and then evaluated in a second step. Actually, in Global and
-Per-Server Class context <em>expression</em> is parsed at startup time and
-at runtime only the machine representation is executed. For Per-Directory
-context this is different: here <em>expression</em> has to be parsed and
-immediately executed for every request.</p>
+<code>funcname</code> the available functions are listed in
+the <a href="../expr.html#functions">ap_expr documentation</a>.</p>
+
+<p>The <em>expression</em> is parsed into an internal machine
+representation when the configuration is loaded, and then evaluated
+during request processing. In .htaccess context, the <em>expression</em> is
+both parsed and executed each time the .htaccess file is encountered during
+request processing.</p>
+
<example><title>Example</title>
-<pre>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} >= 1 and %{TIME_WDAY} <= 5 \
- and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
- or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/</pre>
+<highlight language="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]+$/
+</highlight>
</example>
<p>The <code>PeerExtList(<em>object-ID</em>)</code> function expects
extension must match).</p>
<example><title>Example</title>
+<highlight language="config">
SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")
+</highlight>
</example>
<note><title>Notes on the PeerExtList function</title>
<seealso><a href="../env.html">Environment Variables in Apache HTTP Server</a>,
for additional examples.
</seealso>
+<seealso><a href="mod_authz_core.html#reqexpr">Require expr</a></seealso>
+<seealso><a href="../expr.html">Generic expression syntax in Apache HTTP Server</a>
+</seealso>
</directivesynopsis>
<directivesynopsis>
</p></note>
<example><title>Example</title>
+<highlight language="config">
SSLRenegBufferSize 262144
+</highlight>
</example>
</usage>
</directivesynopsis>
<default>SSLStrictSNIVHostCheck off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in Apache 2.2.12 and later</compatibility>
<usage>
<p>
</p></note>
<example><title>Example</title>
+<highlight language="config">
SSLStrictSNIVHostCheck on
+</highlight>
</example>
</usage>
</directivesynopsis>
<p>The files in this directory must be PEM-encoded and are accessed through
hash filenames. Additionally, you must create symbolic links named
<code><em>hash-value</em>.N</code>. And you should always make sure this
-directory contains the appropriate symbolic links. Use the Makefile which
-comes with mod_ssl to accomplish this task.
-</p>
+directory contains the appropriate symbolic links.</p>
<note type="warning">
<p>Currently there is no support for encrypted private keys</p>
</note>
<example><title>Example</title>
+<highlight language="config">
SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/
-</example>
-</usage>
+</highlight>
+</example>
+</usage>
</directivesynopsis>
<p>Currently there is no support for encrypted private keys</p>
</note>
<example><title>Example</title>
+<highlight language="config">
SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem
+</highlight>
+</example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLProxyMachineCertificateChainFile</name>
+<description>File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate</description>
+<syntax>SSLProxyMachineCertificateChainFile <em>filename</em></syntax>
+<contextlist><context>server config</context></contextlist>
+<override>Not applicable</override>
+
+<usage>
+<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>
+<note type="warning"><title>Security warning</title>
+<p>If this directive is enabled, all of the certificates in the file will be
+trusted as if they were also in <directive module="mod_ssl">
+SSLProxyCACertificateFile</directive>.</p>
+</note>
+<example><title>Example</title>
+<highlight language="config">
+SSLProxyMachineCertificateChainFile /usr/local/apache2/conf/ssl.crt/proxyCA.pem
+</highlight>
</example>
</usage>
</directivesynopsis>
<strong>optional_no_ca</strong> is actually against the idea of
authentication (but can be used to establish SSL test pages, etc.)</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyVerify require
+</highlight>
</example>
</usage>
</directivesynopsis>
which is directly known to the server (i.e. the CA's certificate is under
<directive module="mod_ssl">SSLProxyCACertificatePath</directive>), etc.</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyVerifyDepth 10
+</highlight>
</example>
</usage>
</directivesynopsis>
sent.
</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCheckPeerExpire on
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCheckPeerCN</name>
-<description>Whether to check the remote server certificates CN field
+<description>Whether to check the remote server certificate's CN field
</description>
<syntax>SSLProxyCheckPeerCN on|off</syntax>
<default>SSLProxyCheckPeerCN on</default>
<usage>
<p>
-This directive sets whether the remote server certificates CN field is
+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.
</p>
+<p>
+In 2.4.5 and later, SSLProxyCheckPeerCN has been superseded by
+<directive module="mod_ssl">SSLProxyCheckPeerName</directive>, and its
+setting is only taken into account when
+<code>SSLProxyCheckPeerName off</code> is specified at the same time.
+</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCheckPeerCN on
+</highlight>
</example>
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>SSLProxyCheckPeerName</name>
+<description>Configure host name checking for remote server certificates
+</description>
+<syntax>SSLProxyCheckPeerName on|off</syntax>
+<default>SSLProxyCheckPeerName on</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Apache HTTP Server 2.4.5 and later</compatibility>
+
+<usage>
+<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 is found in
+either the subjectAltName extension or (one of) the CN attribute(s)
+in the certificate's subject. If the check fails, the SSL request
+is aborted and a 502 status code (Bad Gateway) is returned.
+The directive supersedes <directive module="mod_ssl">SSLProxyCheckPeerCN</directive>,
+which only checks for the expected host name in the first CN attribute.
+</p>
+<p>
+Wildcard matching is supported in one specific flavor: subjectAltName entries
+of type dNSName or CN attributes starting with <code>*.</code> will match
+for any DNS name with the same number of labels and the same suffix
+(i.e., <code>*.example.org</code> matches for <code>foo.example.org</code>,
+but not for <code>foo.bar.example.org</code>).
+</p>
+</usage>
+</directivesynopsis>
+
<directivesynopsis>
<name>SSLProxyEngine</name>
<description>SSL Proxy Engine Operation Switch</description>
is usually used inside a <directive module="core"
type="section">VirtualHost</directive> section to enable SSL/TLS for proxy
usage in a particular virtual host. By default the SSL/TLS Protocol Engine is
-disabled for proxy image both for the main server and all configured virtual hosts.</p>
+disabled for proxy both for the main server and all configured virtual hosts.</p>
+
+<p>Note that the SSLProxyEngine directive should not, in
+general, be included in a virtual host that will be acting as a
+forward proxy (using <Proxy> or <ProxyRequest> directives.
+SSLProxyEngine is not required to enable a forward proxy server to
+proxy SSL/TLS requests.</p>
+
<example><title>Example</title>
-<VirtualHost _default_:443><br />
-SSLProxyEngine on<br />
-...<br />
+<highlight language="config">
+<VirtualHost _default_:443>
+ SSLProxyEngine on
+ #...
</VirtualHost>
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCipherSuite</name>
-<description>Cipher Suite available for negotiation in SSL
+<description>Cipher Suite available for negotiation in SSL
proxy handshake</description>
<syntax>SSLProxyCipherSuite <em>cipher-spec</em></syntax>
-<default>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</default>
+<default>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCACertificatePath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
Remote Server Auth</description>
<syntax>SSLProxyCACertificatePath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
hash filenames. So usually you can't just place the Certificate files
there: you also have to create symbolic links named
<em>hash-value</em><code>.N</code>. And you should always make sure this directory
-contains the appropriate symbolic links. Use the <code>Makefile</code> which
-comes with mod_ssl to accomplish this task.</p>
+contains the appropriate symbolic links.</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCACertificateFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for Remote Server Auth</description>
<syntax>SSLProxyCACertificateFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
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
+preference. This can be used alternatively and/or additionally to
<directive module="mod_ssl">SSLProxyCACertificatePath</directive>.</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCARevocationPath</name>
-<description>Directory of PEM-encoded CA CRLs for
+<description>Directory of PEM-encoded CA CRLs for
Remote Server Auth</description>
<syntax>SSLProxyCARevocationPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
hash filenames. So usually you have not only to place the CRL files there.
Additionally you have to create symbolic links named
<em>hash-value</em><code>.rN</code>. And you should always make sure this directory
-contains the appropriate symbolic links. Use the <code>Makefile</code> which
-comes with <module>mod_ssl</module> to accomplish this task.</p>
+contains the appropriate symbolic links.</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCARevocationFile</name>
-<description>File of concatenated PEM-encoded CA CRLs for
+<description>File of concatenated PEM-encoded CA CRLs for
Remote Server Auth</description>
<syntax>SSLProxyCARevocationFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
used alternatively and/or additionally to <directive
module="mod_ssl">SSLProxyCARevocationPath</directive>.</p>
<example><title>Example</title>
+<highlight language="config">
SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl
+</highlight>
+</example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLProxyCARevocationCheck</name>
+<description>Enable CRL-based revocation checking for Remote Server Auth</description>
+<syntax>SSLProxyCARevocationCheck chain|leaf|none</syntax>
+<default>SSLProxyCARevocationCheck none</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+<p>
+Enables certificate revocation list (CRL) checking for the
+<em>remote servers</em> you deal with. At least one of
+<directive module="mod_ssl">SSLProxyCARevocationFile</directive>
+or <directive module="mod_ssl">SSLProxyCARevocationPath</directive> 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>
+<note>
+<title>When set to <code>chain</code> or <code>leaf</code>,
+CRLs <em>must</em> be available for successful validation</title>
+<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
+<directive module="mod_ssl">SSLProxyCARevocationFile</directive>
+or <directive module="mod_ssl">SSLProxyCARevocationPath</directive>.
+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>
+</note>
+<example><title>Example</title>
+<highlight language="config">
+SSLProxyCARevocationCheck chain
+</highlight>
</example>
</usage>
</directivesynopsis>
<context>directory</context>
<context>.htaccess</context></contextlist>
<override>AuthConfig</override>
-<compatibility>Available in Apache 2.0.51 and later</compatibility>
<usage>
<p>
<code>REMOTE_USER</code> to be set. The <em>varname</em> can be
any of the <a href="#envvars">SSL environment variables</a>.</p>
-<p>Note that this directive has no effect if the
-<code>FakeBasicAuth</code> option is used (see <a
-href="#ssloptions">SSLOptions</a>).</p>
+<p>When the <code>FakeBasicAuth</code> option is enabled, this directive
+instead controls the value of the username embedded within the basic
+authentication header (see <a href="#ssloptions">SSLOptions</a>).</p>
<example><title>Example</title>
+<highlight language="config">
SSLUserName SSL_CLIENT_S_DN_CN
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLHonorCipherOrder</name>
<description>Option to prefer the server's cipher preference order</description>
-<syntax>SSLHonorCipherOrder <em>flag</em></syntax>
+<syntax>SSLHonorCipherOrder on|off</syntax>
+<default>SSLHonorCipherOrder off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in Apache 2.1 and later, if using OpenSSL 0.9.7 or later</compatibility>
<usage>
<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>
<example><title>Example</title>
+<highlight language="config">
SSLHonorCipherOrder on
+</highlight>
</example>
</usage>
</directivesynopsis>
"<code>openssl engine</code>".</p>
<example><title>Example</title>
-# For a Broadcom accelerator:<br />
+<highlight language="config">
+# For a Broadcom accelerator:
SSLCryptoDevice ubsec
+</highlight>
</example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLOCSPEnable</name>
<description>Enable OCSP validation of the client certificate chain</description>
-<syntax>SSLOCSPEnable <em>flag</em></syntax>
+<syntax>SSLOCSPEnable on|off</syntax>
+<default>SSLOCSPEnable off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</compatibility>
<usage>
<p>This option enables OCSP validation of the client certificate
directives.</p>
<example><title>Example</title>
-SSLVerifyClient on<br/>
-SSLOCSPEnable on<br/>
-SSLOCSPDefaultResponder http://responder.example.com:8888/responder<br/>
+<highlight language="config">
+SSLVerifyClient on
+SSLOCSPEnable on
+SSLOCSPDefaultResponder http://responder.example.com:8888/responder
SSLOCSPOverrideResponder on
+</highlight>
</example>
</usage>
</directivesynopsis>
<syntax>SSLOCSDefaultResponder <em>uri</em></syntax>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</compatibility>
<usage>
<p>This option sets the default OCSP responder to use. If <directive
<directivesynopsis>
<name>SSLOCSPOverrideResponder</name>
<description>Force use of the default responder URI for OCSP validation</description>
-<syntax>SSLOCSPOverrideResponder <em>flag</em></syntax>
+<syntax>SSLOCSPOverrideResponder on|off</syntax>
+<default>SSLOCSPOverrideResponder off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in httpd 2.3 and later, if using OpenSSL 0.9.7 or later</compatibility>
<usage>
<p>This option forces the configured default OCSP responder to be used
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>SSLOCSPResponseTimeSkew</name>
+<description>Maximum allowable time skew for OCSP response validation</description>
+<syntax>SSLOCSPResponseTimeSkew <em>seconds</em></syntax>
+<default>SSLOCSPResponseTimeSkew 300</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+<p>This option sets the maximum allowable time skew for OCSP responses
+(when checking their <code>thisUpdate</code> and <code>nextUpdate</code> fields).</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLOCSPResponseMaxAge</name>
+<description>Maximum allowable age for OCSP responses</description>
+<syntax>SSLOCSPResponseMaxAge <em>seconds</em></syntax>
+<default>SSLOCSPResponseMaxAge -1</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+<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>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLOCSPResponderTimeout</name>
+<description>Timeout for OCSP queries</description>
+<syntax>SSLOCSPResponderTimeout <em>seconds</em></syntax>
+<default>SSLOCSPResponderTimeout 10</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+
+<usage>
+<p>This option sets the timeout for queries to OCSP responders, when
+<directive module="mod_ssl">SSLOCSPEnable</directive> is turned on.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLOCSPUseRequestNonce</name>
+<description>Use a nonce within OCSP queries</description>
+<syntax>SSLOCSPUseRequestNonce on|off</syntax>
+<default>SSLOCSPUseRequestNonce on</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.10 and later</compatibility>
+
+<usage>
+<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>
+</usage>
+</directivesynopsis>
+
<directivesynopsis>
<name>SSLInsecureRenegotiation</name>
<description>Option to enable support for insecure renegotiation</description>
-<syntax>SSLInsecureRenegotiation <em>flag</em></syntax>
+<syntax>SSLInsecureRenegotiation on|off</syntax>
<default>SSLInsecureRenegotiation off</default>
<contextlist><context>server config</context>
<context>virtual host</context></contextlist>
-<compatibility>Available in httpd 2.2.15 and later, if using OpenSSL 0.9.8m or later</compatibility>
+<compatibility>Available if using OpenSSL 0.9.8m or later</compatibility>
<usage>
<p>As originally specified, all versions of the SSL and TLS protocols
</note>
<example><title>Example</title>
+<highlight language="config">
SSLInsecureRenegotiation on
+</highlight>
</example>
<p>The <code>SSL_SECURE_RENEG</code> environment variable can be used
</usage>
</directivesynopsis>
+<directivesynopsis>
+<name>SSLUseStapling</name>
+<description>Enable stapling of OCSP responses in the TLS handshake</description>
+<syntax>SSLUseStapling on|off</syntax>
+<default>SSLUseStapling off</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<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
+<directive module="mod_ssl">SSLStaplingCache</directive> 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="http://www.ietf.org/rfc/rfc6961.txt">RFC 6961</a>
+(TLS Multiple Certificate Status Extension).
+</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingCache</name>
+<description>Configures the OCSP stapling cache</description>
+<syntax>SSLStaplingCache <em>type</em></syntax>
+<contextlist><context>server config</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>Configures the cache used to store OCSP responses which get included
+in the TLS handshake if <directive module="mod_ssl">SSLUseStapling</directive>
+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
+<directive module="mod_ssl">SSLSessionCache</directive>.</p>
+
+<p>The <code>ssl-stapling</code> mutex is used to serialize access to the
+OCSP stapling cache to prevent corruption. This mutex can be configured
+using the <directive module="core">Mutex</directive> directive.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingResponseTimeSkew</name>
+<description>Maximum allowable time skew for OCSP stapling response validation</description>
+<syntax>SSLStaplingResponseTimeSkew <em>seconds</em></syntax>
+<default>SSLStaplingResponseTimeSkew 300</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<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 <directive module="mod_ssl">SSLUseStapling</directive> is turned on.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingResponderTimeout</name>
+<description>Timeout for OCSP stapling queries</description>
+<syntax>SSLStaplingResponderTimeout <em>seconds</em></syntax>
+<default>SSLStaplingResponderTimeout 10</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>This option sets the timeout for queries to OCSP responders when
+<directive module="mod_ssl">SSLUseStapling</directive> is enabled
+and mod_ssl is querying a responder for OCSP stapling purposes.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingResponseMaxAge</name>
+<description>Maximum allowable age for OCSP stapling responses</description>
+<syntax>SSLStaplingResponseMaxAge <em>seconds</em></syntax>
+<default>SSLStaplingResponseMaxAge -1</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>This option sets the maximum allowable age ("freshness") when
+considering OCSP responses for stapling purposes, i.e. when
+<directive module="mod_ssl">SSLUseStapling</directive> 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>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingStandardCacheTimeout</name>
+<description>Number of seconds before expiring responses in the OCSP stapling cache</description>
+<syntax>SSLStaplingStandardCacheTimeout <em>seconds</em></syntax>
+<default>SSLStaplingStandardCacheTimeout 3600</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>Sets the timeout in seconds before responses in the OCSP stapling cache
+(configured through <directive module="mod_ssl">SSLStaplingCache</directive>)
+will expire. This directive applies to <em>valid</em> responses, while
+<directive module="mod_ssl">SSLStaplingErrorCacheTimeout</directive> is
+used for controlling the timeout for invalid/unavailable responses.
+</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingReturnResponderErrors</name>
+<description>Pass stapling related OCSP errors on to client</description>
+<syntax>SSLStaplingReturnResponderErrors on|off</syntax>
+<default>SSLStaplingReturnResponderErrors on</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>When enabled, mod_ssl will pass responses from unsuccessful
+stapling related OCSP queries (such as status errors, expired responses etc.)
+on to the client. If set to <code>off</code>, no stapled responses
+for failed queries will be included in the TLS handshake.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingFakeTryLater</name>
+<description>Synthesize "tryLater" responses for failed OCSP stapling queries</description>
+<syntax>SSLStaplingFakeTryLater on|off</syntax>
+<default>SSLStaplingFakeTryLater on</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<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 <directive
+module="mod_ssl">SSLStaplingReturnResponderErrors</directive>
+is also enabled.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingErrorCacheTimeout</name>
+<description>Number of seconds before expiring invalid responses in the OCSP stapling cache</description>
+<syntax>SSLStaplingErrorCacheTimeout <em>seconds</em></syntax>
+<default>SSLStaplingErrorCacheTimeout 600</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>Sets the timeout in seconds before <em>invalid</em> responses
+in the OCSP stapling cache (configured through <directive
+module="mod_ssl">SSLStaplingCache</directive>) will expire.
+To set the cache timeout for valid responses, see
+<directive module="mod_ssl">SSLStaplingStandardCacheTimeout</directive>.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLStaplingForceURL</name>
+<description>Override the OCSP responder URI specified in the certificate's AIA extension</description>
+<syntax>SSLStaplingForceURL <em>uri</em></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<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>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLSessionTicketKeyFile</name>
+<description>Persistent encryption/decryption key for TLS session tickets</description>
+<syntax>SSLSessionTicketKeyFile <em>file-path</em></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later</compatibility>
+
+<usage>
+<p>Optionally configures a secret key for encrypting and decrypting
+TLS session tickets, as defined in
+<a href="http://www.ietf.org/rfc/rfc5077.txt">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,
+preferrably created from a high-entropy source. On a Unix-based system,
+a ticket key file can be created as follows:</p>
+
+<example>
+dd if=/dev/random of=/path/to/file.tkey bs=1 count=48
+</example>
+
+<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.</p>
+
+<note type="warning">
+<p>The ticket key file contains sensitive keying material and should
+be protected with file permissions similar to those used for
+<directive module="mod_ssl">SSLCertificateKeyFile</directive>.</p>
+</note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLCompression</name>
+<description>Enable compression on the SSL level</description>
+<syntax>SSLCompression on|off</syntax>
+<default>SSLCompression off</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>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.</compatibility>
+
+<usage>
+<p>This directive allows to enable compression on the SSL level.</p>
+<note type="warning">
+<p>Enabling compression causes security issues in most setups (the so called
+CRIME attack).</p>
+</note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLSessionTickets</name>
+<description>Enable or disable use of TLS session tickets</description>
+<syntax>SSLSessionTickets on|off</syntax>
+<default>SSLSessionTickets on</default>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.11 and later, if using OpenSSL 0.9.8f
+or later.</compatibility>
+
+<usage>
+<p>This directive allows to enable or disable the use of TLS session tickets
+(RFC 5077).</p>
+<note type="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>
+</note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>SSLOpenSSLConfCmd</name>
+<description>Configure OpenSSL parameters through its <em>SSL_CONF</em> API</description>
+<syntax>SSLOpenSSLConfCmd <em>command-name</em> <em>command-value</em></syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context></contextlist>
+<compatibility>Available in httpd 2.4.8 and later, if using OpenSSL 1.0.2 or later</compatibility>
+
+<usage>
+<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 <module>mod_ssl</module> directives when new
+features are added to OpenSSL.</p>
+
+<p>The set of available <directive>SSLOpenSSLConfCmd</directive> commands
+depends on the OpenSSL version being used for <module>mod_ssl</module>
+(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="http://www.openssl.org/docs/ssl/SSL_CONF_cmd.html#supported_configuration_file_commands">SSL_CONF_cmd(3)</a> manual page for OpenSSL.</p>
+
+<p>Some of the <directive>SSLOpenSSLConfCmd</directive> commands can be used
+as an alternative to existing directives (such as
+<directive module="mod_ssl">SSLCipherSuite</directive> or
+<directive module="mod_ssl">SSLProtocol</directive>),
+though it should be noted that the syntax / allowable values for the parameters
+may sometimes differ.</p>
+
+<example><title>Examples</title>
+<highlight language="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
+</highlight>
+</example>
+</usage>
+</directivesynopsis>
+
</modulesynopsis>
projects / apache / blobdiff