mod_md: some strong advice about the consequences of permanent MDRequireHttps in the manual
@@ -494,14 +494,34 @@ 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>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
@@ -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>
