From: Joe Orton <jorton@apache.org>
Date: Fri, 4 Dec 2020 14:21:06 +0000 (+0000)
Subject: Document mod_ssl client certificate handling w/SSLProxyMachineCertificate*.
X-Git-Tag: 2.5.0-alpha2-ci-test-only~1114
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=af27fb4e5c9bf8b9c6412c6355b3969c242d2609;p=thirdparty%2Fapache%2Fhttpd.git

Document mod_ssl client certificate handling w/SSLProxyMachineCertificate*.
[skip ci]

PR: 63936


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1884097 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_ssl.html.en.utf8 b/docs/manual/mod/mod_ssl.html.en.utf8
index 64549570828..7c7ad496f87 100644
--- a/docs/manual/mod/mod_ssl.html.en.utf8
+++ b/docs/manual/mod/mod_ssl.html.en.utf8
@@ -1942,10 +1942,31 @@ 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>
+This referenced file is simply the concatenation of the various
+PEM-encoded certificate files. Use this directive alternatively or
+additionally to <code>SSLProxyMachineCertificatePath</code>.  The referenced file can contain any number of pairs of client
+certificate and associated private key.  Each pair can be specified in
+either (certificate, key) or (key, certificate) order.</p>
+
+<p>When challenged to provide a client certificate by a remote server,
+the server should provide a list of <em>acceptable certificate
+authority names</em> in the challenge.  If such a list is <em>not</em>
+provided, <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will use the first configured
+client cert/key.  If a list of CA names <em>is</em> provided,
+<code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> will iterate through that list, and attempt
+to find a configured client cert which was issued either directly by
+that CA, or indirectly via any number of intermediary CA certificates.
+The chain of intermediate CA certificates can be built from those
+configured with <code class="directive"><a href="#sslproxymachinecertificatechainfile">SSLProxyMachineCertificateChainFile</a></code>.  The
+first configured matching certificate will then be supplied in
+response to the challenge.</p>
+
+<p>If the list of CA names <em>is</em> provided by the remote server,
+and <em>no</em> matching client certificate can be found, no client
+certificate will be provided by <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>, which will
+likely fail the SSL/TLS handshake (depending on the remote server
+configuration).</p>
+
 <div class="warning">
 <p>Currently there is no support for encrypted private keys</p>
 </div>
@@ -1971,13 +1992,13 @@ must be converted, eg. using
 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The proxy section context is allowed in httpd 2.4.30 and later</td></tr>
 </table>
 <p>
-This directive sets the directory where you keep the certificates and
-keys used for authentication of the proxy server to remote servers.
+This directive sets the directory where you keep the client
+certificates and keys used for authentication of the proxy server to
+remote servers.
 </p>
 <p>
-mod_ssl will attempt to load every file inside the specified
-directory, but will ignore any sub-directories. Each file should
-contain a PEM-encoded certificate and matching private key.
+mod_ssl will attempt to load every file inside the specified directory
+as if it was configured individually with <code class="directive"><a href="#sslproxymachinecertificatefile">SSLProxyMachineCertificateFile</a></code>.
 </p>
 <div class="warning">
 <p>Currently there is no support for encrypted private keys</p>
diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml
index bbb0123b43a..6cee399b4fe 100644
--- a/docs/manual/mod/mod_ssl.xml
+++ b/docs/manual/mod/mod_ssl.xml
@@ -1838,13 +1838,14 @@ SSLStrictSNIVHostCheck on
 
 <usage>
 <p>
-This directive sets the directory where you keep the certificates and
-keys used for authentication of the proxy server to remote servers.
+This directive sets the directory where you keep the client
+certificates and keys used for authentication of the proxy server to
+remote servers.
 </p>
 <p>
-mod_ssl will attempt to load every file inside the specified
-directory, but will ignore any sub-directories. Each file should
-contain a PEM-encoded certificate and matching private key.
+mod_ssl will attempt to load every file inside the specified directory
+as if it was configured individually with <directive
+module="mod_ssl">SSLProxyMachineCertificateFile</directive>.
 </p>
 <note type="warning">
 <p>Currently there is no support for encrypted private keys</p>
@@ -1879,10 +1880,32 @@ 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>
+This referenced file is simply the concatenation of the various
+PEM-encoded certificate files. Use this directive alternatively or
+additionally to <code>SSLProxyMachineCertificatePath</code>.  The referenced file can contain any number of pairs of client
+certificate and associated private key.  Each pair can be specified in
+either (certificate, key) or (key, certificate) order.</p>
+
+<p>When challenged to provide a client certificate by a remote server,
+the server should provide a list of <em>acceptable certificate
+authority names</em> in the challenge.  If such a list is <em>not</em>
+provided, <module>mod_ssl</module> will use the first configured
+client cert/key.  If a list of CA names <em>is</em> provided,
+<module>mod_ssl</module> will iterate through that list, and attempt
+to find a configured client cert which was issued either directly by
+that CA, or indirectly via any number of intermediary CA certificates.
+The chain of intermediate CA certificates can be built from those
+configured with <directive
+module="mod_ssl">SSLProxyMachineCertificateChainFile</directive>.  The
+first configured matching certificate will then be supplied in
+response to the challenge.</p>
+
+<p>If the list of CA names <em>is</em> provided by the remote server,
+and <em>no</em> matching client certificate can be found, no client
+certificate will be provided by <module>mod_ssl</module>, which will
+likely fail the SSL/TLS handshake (depending on the remote server
+configuration).</p>
+
 <note type="warning">
 <p>Currently there is no support for encrypted private keys</p>
 </note>