mirror of
https://github.com/apache/httpd.git
synced 2025-07-25 17:01:22 +00:00
181e083ddb
Append :!aNULL:!eNULL:!EXP to the cipher string settings, instead of prepending !aNULL:!eNULL:!EXP: (as was the case in 2.4.7 and later). Enables support for configuring the SUITEB* cipher strings introduced in OpenSSL 1.0.2. PR 58213. Apply the same treatment to the "SSLOpenSSLConfCmd CipherString ..." directive. Proposed by: kbrand Reviewed by: ylavic, jorton git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1706007 13f79535-47bb-0310-9956-ffa450edef68
2679 lines
115 KiB
XML
2679 lines
115 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_ssl.xml.meta">
|
|
|
|
<name>mod_ssl</name>
|
|
<description>Strong cryptography using the Secure Sockets
|
|
Layer (SSL) and Transport Layer Security (TLS) protocols</description>
|
|
<status>Extension</status>
|
|
<sourcefile>mod_ssl.c</sourcefile>
|
|
<identifier>ssl_module</identifier>
|
|
|
|
<summary>
|
|
<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>
|
|
|
|
<p>Further details, discussion, and examples are provided in the
|
|
<a href="../ssl/">SSL documentation</a>.</p>
|
|
</summary>
|
|
|
|
<section id="envvars"><title>Environment Variables</title>
|
|
|
|
<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>
|
|
|
|
<table border="1">
|
|
<columnspec><column width=".3"/><column width=".2"/><column width=".5"/>
|
|
</columnspec>
|
|
<tr>
|
|
<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><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_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>
|
|
<tr><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><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><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><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><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_SAN_OTHER_msUPN_</code><em>n</em></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><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_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><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><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_SAN_OTHER_dnsSRV_</code><em>n</em></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><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_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>
|
|
<tr><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><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 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>
|
|
|
|
<p>A number of additional environment variables can also be used
|
|
in <directive>SSLRequire</directive> expressions, or in custom log
|
|
formats:</p>
|
|
|
|
<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></note>
|
|
|
|
<p>In these contexts, two special formats can also be used:</p>
|
|
|
|
<dl>
|
|
<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>
|
|
</dl>
|
|
|
|
</section>
|
|
|
|
<section id="logformats"><title>Custom Log Formats</title>
|
|
|
|
<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
|
|
<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 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><em>name</em><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>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
|
|
</highlight>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="notes"><title>Request Notes</title>
|
|
|
|
<p><module>mod_ssl</module> sets "notes" for the request which can be
|
|
used in logging with the <code>%{<em>name</em>}n</code> format
|
|
string in <module>mod_log_config</module>.</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 <directive>SSLRequire</directive>
|
|
or <directive>SSLRequireSSL</directive> directive.</dd>
|
|
|
|
<dt><code>ssl-secure-reneg</code></dt>
|
|
<dd>If <module>mod_ssl</module> 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 <module>mod_ssl</module> 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>
|
|
|
|
</section>
|
|
|
|
<section id="authzproviders"><title>Authorization providers for use with Require</title>
|
|
|
|
<p><module>mod_ssl</module> provides a few authentication providers for use
|
|
with <module>mod_authz_core</module>'s
|
|
<directive module="mod_authz_core">Require</directive> directive.</p>
|
|
|
|
<section id="reqssl"><title>Require ssl</title>
|
|
|
|
<p>The <code>ssl</code> provider denies access if a connection is not
|
|
encrypted with SSL. This is similar to the
|
|
<directive>SSLRequireSSL</directive> directive.</p>
|
|
|
|
<highlight language="config">
|
|
Require ssl
|
|
</highlight>
|
|
|
|
</section>
|
|
|
|
<section id="reqverifyclient"><title>Require ssl-verify-client</title>
|
|
|
|
<p>The <code>ssl</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>
|
|
|
|
<highlight language="config">
|
|
Require ssl-verify-client<br/>
|
|
Require valid-user
|
|
</highlight>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLPassPhraseDialog</name>
|
|
<description>Type of pass phrase dialog for encrypted private
|
|
keys</description>
|
|
<syntax>SSLPassPhraseDialog <em>type</em></syntax>
|
|
<default>SSLPassPhraseDialog builtin</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>
|
|
When Apache starts up it has to read the various Certificate (see
|
|
<directive module="mod_ssl">SSLCertificateFile</directive>) and
|
|
Private Key (see <directive
|
|
module="mod_ssl">SSLCertificateKeyFile</directive>) 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
|
|
<em>type</em>:</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 two arguments (the first is
|
|
of the form ``<code>servername:portnumber</code>'', the second is either
|
|
``<code>RSA</code>'', ``<code>DSA</code>'', ``<code>ECC</code>'' or an
|
|
integer index starting at 3 if more than three keys are configured), which
|
|
indicate for which server and algorithm it has to print the corresponding
|
|
Pass Phrase to <code>stdout</code>. In versions 2.4.8 (unreleased)
|
|
and 2.4.9, it is called with one argument, a string of the
|
|
form ``<code>servername:portnumber:index</code>'' (with <code>index</code>
|
|
being a zero-based integer number), which indicate the server, TCP port
|
|
and certificate number. 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>
|
|
<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
|
|
source</description>
|
|
<syntax>SSLRandomSeed <em>context</em> <em>source</em>
|
|
[<em>bytes</em>]</syntax>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>
|
|
This configures one or more sources for seeding the Pseudo Random Number
|
|
Generator (PRNG) in OpenSSL at startup time (<em>context</em> is
|
|
<code>startup</code>) and/or just before a new SSL connection is established
|
|
(<em>context</em> 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 <em>source</em> 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 (when applicable) a randomly
|
|
chosen 1KB extract of the inter-process scoreboard structure of Apache.
|
|
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 <em>bytes</em> is specified, only the
|
|
first <em>bytes</em> number of bytes of the file form the entropy (and
|
|
<em>bytes</em> is given to <code>/path/to/source</code> as the first
|
|
argument). When <em>bytes</em> 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 <em>bytes</em> is specified, only the first
|
|
<em>bytes</em> number of bytes of its <code>stdout</code> contents
|
|
form the entropy. When <em>bytes</em> 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>
|
|
<example><title>Example</title>
|
|
<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
|
|
Cache</description>
|
|
<syntax>SSLSessionCache <em>type</em></syntax>
|
|
<default>SSLSessionCache none</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<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 <em>type</em>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
|
|
<module>mod_socache_dbm</module> is loaded.</p></li>
|
|
|
|
<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. To use this,
|
|
ensure that <module>mod_socache_shmcb</module> is loaded.</p></li>
|
|
|
|
<li><code>dc:UNIX:/path/to/socket</code>
|
|
|
|
<p>This makes use of the <a
|
|
href="http://www.distcache.org/">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
|
|
<module>mod_socache_dc</module> is loaded.</p></li>
|
|
|
|
</ul>
|
|
|
|
<example><title>Examples</title>
|
|
<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
|
|
the session cache to prevent corruption. This mutex can be configured
|
|
using the <directive module="core">Mutex</directive> directive.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLSessionCacheTimeout</name>
|
|
<description>Number of seconds before an SSL session expires
|
|
in the Session Cache</description>
|
|
<syntax>SSLSessionCacheTimeout <em>seconds</em></syntax>
|
|
<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, 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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLEngine</name>
|
|
<description>SSL Engine Operation Switch</description>
|
|
<syntax>SSLEngine on|off|optional</syntax>
|
|
<default>SSLEngine off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>
|
|
This directive toggles the usage of the SSL/TLS Protocol Engine. This
|
|
is should be used inside a <directive module="core"
|
|
type="section">VirtualHost</directive> 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>
|
|
<example><title>Example</title>
|
|
<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
|
|
Within HTTP/1.1. At this time no web browsers support RFC 2817.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLFIPS</name>
|
|
<description>SSL FIPS mode Switch</description>
|
|
<syntax>SSLFIPS on|off</syntax>
|
|
<default>SSLFIPS off</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProtocol</name>
|
|
<description>Configure usable SSL/TLS protocol versions</description>
|
|
<syntax>SSLProtocol [+|-]<em>protocol</em> ...</syntax>
|
|
<default>SSLProtocol all</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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) <em>protocol</em>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.</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">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>
|
|
<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</code>, respectively.</p></li>
|
|
</ul>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLProtocol TLSv1
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLCipherSuite</name>
|
|
<description>Cipher Suite available for negotiation in SSL
|
|
handshake</description>
|
|
<syntax>SSLCipherSuite <em>cipher-spec</em></syntax>
|
|
<default>SSLCipherSuite DEFAULT (depends on OpenSSL version)</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
<p>
|
|
This complex directive uses a colon-separated <em>cipher-spec</em> string
|
|
consisting of OpenSSL cipher specifications to configure the Cipher Suite the
|
|
client is permitted to negotiate in the SSL handshake phase. 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>
|
|
An SSL cipher specification in <em>cipher-spec</em> 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 border="1">
|
|
<columnspec><column width=".5"/><column width=".5"/></columnspec>
|
|
<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 <em>cipher-spec</em>. 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>
|
|
|
|
<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 adds
|
|
<code>!aNULL:!eNULL:!EXP</code> to any cipher string 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
|
|
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 '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>
|
|
</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"/>
|
|
<column width=".1"/><column width=".13"/><column width=".1"/>
|
|
<column width=".13"/></columnspec>
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLCertificateFile</name>
|
|
<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 a file with certificate data in PEM format.
|
|
At a 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 1.0.0 or later,
|
|
<code>openssl list-public-key-algorithms</code> will output a list
|
|
of supported algorithms.
|
|
</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 <directive module="mod_ssl">SSLCertificateChainFile</directive>.
|
|
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
|
|
<directive module="mod_ssl">SSLCertificateFile</directive>.
|
|
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
|
|
<directive module="mod_ssl">SSLCertificateKeyFile</directive>
|
|
directive. This practice is highly discouraged. If it is used,
|
|
the certificate files using such an embedded key must be configured
|
|
after the certificates using a separate key file. If the private
|
|
key is encrypted, the pass phrase dialog is forced at startup time.
|
|
</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>
|
|
<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 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>
|
|
|
|
<p>
|
|
The private key may also be combined with the certificate in the file given by
|
|
<directive module="mod_ssl">SSLCertificateFile</directive>, but this practice
|
|
is highly discouraged. If it is used, the certificate files using such
|
|
an embedded key must be configured after the certificates using a separate
|
|
key file.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLCertificateChainFile</name>
|
|
<description>File of PEM-encoded Server CA Certificates</description>
|
|
<syntax>SSLCertificateChainFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<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
|
|
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 <directive
|
|
module="mod_ssl">SSLCACertificatePath</directive> 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 <directive
|
|
module="mod_ssl">SSLCACertificatePath</directive> 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>
|
|
<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
|
|
Client Auth</description>
|
|
<syntax>SSLCACertificatePath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<em>hash-value</em><code>.N</code>. And you should always make sure this directory
|
|
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
|
|
for Client Auth</description>
|
|
<syntax>SSLCACertificateFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<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
|
|
for defining acceptable CA names</description>
|
|
<syntax>SSLCADNRequestFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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 neither of the directives <directive
|
|
module="mod_ssl">SSLCADNRequestPath</directive> or <directive
|
|
module="mod_ssl">SSLCADNRequestFile</directive> are given, then the
|
|
set of acceptable CA names sent to the client is the names of all the
|
|
CA certificates given by the <directive
|
|
module="mod_ssl">SSLCACertificateFile</directive> and <directive
|
|
module="mod_ssl">SSLCACertificatePath</directive> 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, <directive
|
|
module="mod_ssl">SSLCADNRequestPath</directive> and/or <directive
|
|
module="mod_ssl">SSLCADNRequestFile</directive> 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><directive module="mod_ssl">SSLCADNRequestFile</directive> must
|
|
specify an <em>all-in-one</em> file containing a concatenation of
|
|
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
|
|
defining acceptable CA names</description>
|
|
<syntax>SSLCADNRequestPath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
|
|
<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 <directive
|
|
module="mod_ssl">SSLCADNRequestFile</directive> 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
|
|
<em>hash-value</em><code>.N</code>. And you should always make sure
|
|
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
|
|
Client Auth</description>
|
|
<syntax>SSLCARevocationPath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<em>hash-value</em><code>.rN</code>. And you should always make sure this directory
|
|
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
|
|
Client Auth</description>
|
|
<syntax>SSLCARevocationFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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 <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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLVerifyClient</name>
|
|
<description>Type of Client Certificate verification</description>
|
|
<syntax>SSLVerifyClient <em>level</em></syntax>
|
|
<default>SSLVerifyClient none</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
<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 <em>level</em>:</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.</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 browsers 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>
|
|
<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
|
|
Certificate verification</description>
|
|
<syntax>SSLVerifyDepth <em>number</em></syntax>
|
|
<default>SSLVerifyDepth 1</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
<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
|
|
<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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLOptions</name>
|
|
<description>Configure various SSL engine run-time options</description>
|
|
<syntax>SSLOptions [+|-]<em>option</em> ...</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>Options</override>
|
|
|
|
<usage>
|
|
<p>
|
|
This directive can be used to control various run-time options on a
|
|
per-directory basis. Normally, if multiple <code>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>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 <em>option</em>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><em>n</em> (with <em>n</em> = 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><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>
|
|
|
|
<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>
|
|
This <em>forces</em> forbidden access when <code>SSLRequireSSL</code> or
|
|
<code>SSLRequire</code> successfully decided that access should be
|
|
forbidden. Usually the default is that in the case where a ``<code>Satisfy
|
|
any</code>'' directive is used, and other access restrictions are passed,
|
|
denial of access due to <code>SSLRequireSSL</code> or
|
|
<code>SSLRequire</code> is overridden (because that's how the Apache
|
|
<code>Satisfy</code> mechanism should work.) But for strict access restriction
|
|
you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in
|
|
combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an
|
|
additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has
|
|
decided to deny access.</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>
|
|
<example><title>Example</title>
|
|
<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
|
|
HTTP request</description>
|
|
<syntax>SSLRequireSSL</syntax>
|
|
<contextlist><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
<p><!-- XXX: I think the syntax is wrong -->
|
|
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>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLRequireSSL
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLRequire</name>
|
|
<description>Allow access only when an arbitrarily complex
|
|
boolean expression is true</description>
|
|
<syntax>SSLRequire <em>expression</em></syntax>
|
|
<contextlist><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<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
|
|
requirement specification is an arbitrarily complex boolean expression
|
|
containing any number of access checks.</p>
|
|
<p>
|
|
The <em>expression</em> 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 <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>
|
|
<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
|
|
to find zero or more instances of the X.509 certificate extension
|
|
identified by the given <em>object ID</em> (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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
</note>
|
|
|
|
</usage>
|
|
<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>
|
|
<name>SSLRenegBufferSize</name>
|
|
<description>Set the size for the SSL renegotiation buffer</description>
|
|
<syntax>SSLRenegBufferSize <var>bytes</var></syntax>
|
|
<default>SSLRenegBufferSize 131072</default>
|
|
<contextlist><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
|
|
<p>If an SSL renegotiation is required in per-location context, for
|
|
example, any use of <directive
|
|
module="mod_ssl">SSLVerifyClient</directive> in a Directory or
|
|
Location block, then <module>mod_ssl</module> 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>
|
|
|
|
<note type="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></note>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLRenegBufferSize 262144
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLStrictSNIVHostCheck</name>
|
|
<description>Whether to allow non-SNI clients to access a name-based virtual
|
|
host.
|
|
</description>
|
|
<syntax>SSLStrictSNIVHostCheck on|off</syntax>
|
|
<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>
|
|
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>
|
|
|
|
<note type="warning"><p>
|
|
This option is only available if httpd was compiled against an SNI capable
|
|
version of OpenSSL.
|
|
</p></note>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLStrictSNIVHostCheck on
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyMachineCertificatePath</name>
|
|
<description>Directory of PEM-encoded client certificates and keys to be used by the proxy</description>
|
|
<syntax>SSLProxyMachineCertificatePath <em>directory</em></syntax>
|
|
<contextlist><context>server config</context></contextlist>
|
|
<override>Not applicable</override>
|
|
|
|
<usage>
|
|
<p>
|
|
This directive sets the directory where you keep the certificates and
|
|
keys used for authentication of the proxy server to remote servers.
|
|
</p>
|
|
<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.</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/"
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyMachineCertificateFile</name>
|
|
<description>File of concatenated PEM-encoded client certificates and keys to be used by the proxy</description>
|
|
<syntax>SSLProxyMachineCertificateFile <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 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, in order of preference. Use this directive alternatively
|
|
or additionally to <code>SSLProxyMachineCertificatePath</code>.
|
|
</p>
|
|
<note type="warning">
|
|
<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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyVerify</name>
|
|
<description>Type of remote server Certificate verification</description>
|
|
<syntax>SSLProxyVerify <em>level</em></syntax>
|
|
<default>SSLProxyVerify none</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context> </contextlist>
|
|
|
|
<usage>
|
|
|
|
<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 <em>level</em>:</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>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLProxyVerify require
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyVerifyDepth</name>
|
|
<description>Maximum depth of CA Certificates in Remote Server
|
|
Certificate verification</description>
|
|
<syntax>SSLProxyVerifyDepth <em>number</em></syntax>
|
|
<default>SSLProxyVerifyDepth 1</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context> </contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<directive module="mod_ssl">SSLProxyCACertificatePath</directive>), etc.</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLProxyVerifyDepth 10
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyCheckPeerExpire</name>
|
|
<description>Whether to check if remote server certificate is expired
|
|
</description>
|
|
<syntax>SSLProxyCheckPeerExpire on|off</syntax>
|
|
<default>SSLProxyCheckPeerExpire on</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLProxyCheckPeerExpire on
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyCheckPeerCN</name>
|
|
<description>Whether to check the remote server certificate's CN field
|
|
</description>
|
|
<syntax>SSLProxyCheckPeerCN on|off</syntax>
|
|
<default>SSLProxyCheckPeerCN on</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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.
|
|
</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>
|
|
<syntax>SSLProxyEngine on|off</syntax>
|
|
<default>SSLProxyEngine off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>
|
|
This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This
|
|
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 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>
|
|
<highlight language="config">
|
|
<VirtualHost _default_:443>
|
|
SSLProxyEngine on
|
|
#...
|
|
</VirtualHost>
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyProtocol</name>
|
|
<description>Configure usable SSL protocol flavors for proxy usage</description>
|
|
<syntax>SSLProxyProtocol [+|-]<em>protocol</em> ...</syntax>
|
|
<default>SSLProxyProtocol all</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
<override>Options</override>
|
|
|
|
<usage>
|
|
<!-- XXX Why does this have an override and not .htaccess context? -->
|
|
<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 <directive module="mod_ssl">SSLProtocol</directive>
|
|
for additional information.
|
|
</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLProxyCipherSuite</name>
|
|
<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:+EXP</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
<usage>
|
|
<p>Equivalent to <code>SSLCipherSuite</code>, but for the proxy connection.
|
|
Please refer to <directive module="mod_ssl">SSLCipherSuite</directive>
|
|
for additional information.</p>
|
|
</usage>
|
|
|
|
</directivesynopsis>
|
|
<directivesynopsis>
|
|
<name>SSLProxyCACertificatePath</name>
|
|
<description>Directory of PEM-encoded CA Certificates for
|
|
Remote Server Auth</description>
|
|
<syntax>SSLProxyCACertificatePath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<em>hash-value</em><code>.N</code>. And you should always make sure this directory
|
|
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
|
|
for Remote Server Auth</description>
|
|
<syntax>SSLProxyCACertificateFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<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
|
|
Remote Server Auth</description>
|
|
<syntax>SSLProxyCARevocationPath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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
|
|
<em>hash-value</em><code>.rN</code>. And you should always make sure this directory
|
|
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
|
|
Remote Server Auth</description>
|
|
<syntax>SSLProxyCARevocationFile <em>file-path</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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 <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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLUserName</name>
|
|
<description>Variable name to determine user name</description>
|
|
<syntax>SSLUserName <em>varname</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>AuthConfig</override>
|
|
|
|
<usage>
|
|
<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 <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>
|
|
|
|
<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 on|off</syntax>
|
|
<default>SSLHonorCipherOrder off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<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>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLCryptoDevice</name>
|
|
<description>Enable use of a cryptographic hardware accelerator</description>
|
|
<syntax>SSLCryptoDevice <em>engine</em></syntax>
|
|
<default>SSLCryptoDevice builtin</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
|
|
<example><title>Example</title>
|
|
<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 on|off</syntax>
|
|
<default>SSLOCSPEnable off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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.</p>
|
|
|
|
<p>The OCSP responder used is either extracted from the certificate
|
|
itself, or derived by configuration; see the
|
|
<directive module="mod_ssl">SSLOCSPDefaultResponder</directive> and
|
|
<directive module="mod_ssl">SSLOCSPOverrideResponder</directive>
|
|
directives.</p>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLVerifyClient on
|
|
SSLOCSPEnable on
|
|
SSLOCSPDefaultResponder "http://responder.example.com:8888/responder"
|
|
SSLOCSPOverrideResponder on
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLOCSPDefaultResponder</name>
|
|
<description>Set the default responder URI for OCSP validation</description>
|
|
<syntax>SSLOCSDefaultResponder <em>uri</em></syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<p>This option sets the default OCSP responder to use. If <directive
|
|
module="mod_ssl">SSLOCSPOverrideResponder</directive> is not enabled,
|
|
the URI given will be used only if no responder URI is specified in
|
|
the certificate being verified.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSLOCSPOverrideResponder</name>
|
|
<description>Force use of the default responder URI for OCSP validation</description>
|
|
<syntax>SSLOCSPOverrideResponder on|off</syntax>
|
|
<default>SSLOCSPOverrideResponder off</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context></contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
</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 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>
|
|
|
|
<usage>
|
|
<p>As originally specified, all versions of the SSL and TLS protocols
|
|
(up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle
|
|
attack
|
|
(<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555">CVE-2009-3555</a>)
|
|
during a renegotiation. This vulnerability allowed an attacker to
|
|
"prefix" a chosen plaintext to the HTTP request as seen by the web
|
|
server. A protocol extension was developed which fixed this
|
|
vulnerability if supported by both client and server.</p>
|
|
|
|
<p>If <module>mod_ssl</module> is linked against OpenSSL version 0.9.8m
|
|
or later, by default renegotiation is only supported with
|
|
clients supporting the new protocol extension. If this directive is
|
|
enabled, renegotiation will be allowed with old (unpatched) clients,
|
|
albeit insecurely.</p>
|
|
|
|
<note type="warning"><title>Security warning</title>
|
|
<p>If this directive is enabled, SSL connections will be vulnerable to
|
|
the Man-in-the-Middle prefix attack as described
|
|
in <a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555">CVE-2009-3555</a>.</p>
|
|
</note>
|
|
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
SSLInsecureRenegotiation on
|
|
</highlight>
|
|
</example>
|
|
|
|
<p>The <code>SSL_SECURE_RENEG</code> environment variable can be used
|
|
from an SSI or CGI script to determine whether secure renegotiation is
|
|
supported for a given SSL connection.</p>
|
|
|
|
</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>
|
|
|
|
<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
|
|
<directive module="core">Mutex</directive> directive.
|
|
</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>
|
|
</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.
|
|
A new ticket key only gets used after restarting the web server.
|
|
All existing session tickets become invalid after a restart.</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/man1.0.2/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>
|