svn commit: r1938528 - in httpd/httpd/branches/2.4.x/docs/manual: misc mod

[js...@apache.org]

Author: jsl
Date: Sat Sep 26 07:16:47 2026
New Revision: 1938528

Log:
mod_ssl: Document mod_reqtimeout for TLS handshake timeouts (Bug 70215)

Add a "Connection and Handshake Timeouts" section to mod_ssl explaining
that HTTP-level timeouts such as TimeOut do not cover a client that stalls
during the TLS handshake, and that the handshake stage of mod_reqtimeout's
RequestReadTimeout must be configured to time such connections out.
Cross-reference RequestReadTimeout from the module summary.

Also update the RequestReadTimeout bullet in misc/security_tips.xml to
call out the TLS handshake stage.

No functional change; documentation only.

Backport of r1938527.

Modified:
   httpd/httpd/branches/2.4.x/docs/manual/misc/security_tips.xml
   httpd/httpd/branches/2.4.x/docs/manual/mod/mod_ssl.xml

Modified: httpd/httpd/branches/2.4.x/docs/manual/misc/security_tips.xml
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/misc/security_tips.xml	Sat Sep 26 05:05:36 2026	(r1938527)
+++ httpd/httpd/branches/2.4.x/docs/manual/misc/security_tips.xml	Sat Sep 26 07:16:47 2026	(r1938528)
@@ -74,8 +74,10 @@
 
     <ul>
       <li>The <directive module="mod_reqtimeout">RequestReadTimeout</directive>
-      directive allows to limit the time a client may take to send the
-      request.</li>
+      directive allows you to limit the time a client may take to complete
+      the TLS handshake and send the request. In particular, the
+      <code>handshake</code> stage times out clients that stall during the
+      TLS handshake.</li>
 
       <li>The <directive module="core">TimeOut</directive> directive
       should be lowered on sites that are subject to DoS attacks.

Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_ssl.xml
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_ssl.xml	Sat Sep 26 05:05:36 2026	(r1938527)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_ssl.xml	Sat Sep 26 07:16:47 2026	(r1938528)
@@ -40,6 +40,8 @@ to provide the cryptography engine.</p>
 <a href="../ssl/">SSL documentation</a>.</p>
 </summary>
 
+<seealso><directive module="mod_reqtimeout">RequestReadTimeout</directive></seealso>
+
 <section id="envvars"><title>Environment Variables</title>
 
 <p>This module can be configured to provide several items of SSL information
@@ -287,6 +289,29 @@ Require valid-user
 
 </section>
 
+<section id="timeouts"><title>Connection and Handshake Timeouts</title>
+
+<p>A client may open a TLS connection, receive the server certificate, and
+then stall without completing the handshake or sending a request. The
+HTTP-level timeouts, such as <directive module="core">TimeOut</directive>,
+do not reliably cover this situation, so the connection can be held open
+indefinitely.</p>
+
+<p>To limit the time a client may take to complete the TLS handshake, load
+<module>mod_reqtimeout</module> and configure the <code>handshake</code>
+stage of <directive module="mod_reqtimeout">RequestReadTimeout</directive>:</p>
+
+<highlight language="config">
+RequestReadTimeout handshake=5
+</highlight>
+
+<p>The <code>handshake</code> stage is disabled by default and is available
+since httpd 2.4.39. See the
+<directive module="mod_reqtimeout">RequestReadTimeout</directive>
+documentation for details and more examples.</p>
+
+</section>
+
 <directivesynopsis>
 <name>SSLPassPhraseDialog</name>
 <description>Type of pass phrase dialog for encrypted private