mod_md: some strong advice about the consequences of permanent MDRequireHttps in...

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

diff --git a/docs/manual/mod/mod_md.xml b/docs/manual/mod/mod_md.xml
index 05b973a1f9cfa921b913861718031e71362209c4..17c5708bde0925dfdf3ce893be7749bc0effbb09 100644 (file)
--- a/docs/manual/mod/mod_md.xml
+++ b/docs/manual/mod/mod_md.xml
@@ -494,15 +494,35 @@ MDRequireHttps temporary
                 </highlight>
             </example>
             <p>you announce that you want all traffic via http: URLs to be redirected 
-            to the https: ones, for now. If you want client to no longer use the
+            to the https: ones, for now. This is safe and you can remove this again at
+            any time.
+            </p><p>
+                <strong>The following has consequences: </strong>if you want client to <strong>no longer</strong> use the
              http: URLs, configure:
             </p>
-            <example><title>Example</title>
+            <example><title>Permanent (for at least half a year!)</title>
                 <highlight language="config">
 MDRequireHttps permanent                
                 </highlight>
             </example>
-            <p>You can achieve the same with mod_alias and some Redirect configuration, 
+            <p>This does two things:
+            </p>
+            <ol>
+                <li>All request to the <code>http:</code> resources are redirected to the
+                    same url with the <code>https:</code> scheme using the <code>301</code>
+                status code. This tells clients that this is intended to be forever and
+                the should update any links they have accodingly.
+                </li>
+                <li>All answers to <code>https:</code> requests will carry the header
+                    <code>Strict-Transport-Security</code> with a life time of half a year.
+                    This tells the browser that it <strong>never</strong> (for half a year) shall use <code>http:</code>
+                    when talking to this domain name. Browsers will, after having seen this, refuse
+                    to contact your unencrypted site. This prevents malicious middleware to
+                    downgrade connections and listen/manipulate the traffic. Which is good. But
+                    you cannot simply take it back again.
+                </li>
+            </ol>
+            <p>You can achieve the same with mod_alias and some Redirect configuration,
             basically. If you do it yourself, please make sure to exclude the paths 
             /.well-known/* from your redirection, otherwise mod_md might have trouble 
             signing on new certificates.
@@ -513,21 +533,10 @@ MDRequireHttps permanent
             <example><title>Example</title>
                 <highlight language="config">
 &lt;ManagedDomain xxx.yyy&gt;
-  MDRequireHttps permanent
+  MDRequireHttps temporary
 &lt;/ManagedDomain&gt;
                 </highlight>
             </example>
-            <p>When you configure MDRequireHttps permanent, an additional security 
-            feature is automatically applied: HSTS. This adds the header 
-            Strict-Transport-Security to responses sent out via https:. 
-            Basically, this instructs the browser to only perform secure 
-            communications with that domain. This instruction holds for the 
-            amount of time specified in the header as 'max-age'. 
-            This is about half a year as generated by mod_md.
-            </p><p>
-            It is therefore advisable to first test the MDRequireHttps temporary 
-            configuration and switch to permanent only once that works satisfactory.
-            </p>
         </usage>
     </directivesynopsis>