Updated docs

source/nwebsec/Configuration.rst

@@ -11,6 +11,7 @@ Configuration
    Redirect validation <Redirect-validation>
    Referrer policy <Configuring-referrerpolicy>
    Content-Security-Policy <Configuring-csp>
+   Upgrade-insecure-requests
    Strict-Transport-Security <Configuring-hsts>
    Public-Key-Pins <Configuring-hpkp>
    X-Frame-Options <Configuring-xfo>

source/nwebsec/Configuring-hsts.rst

@@ -2,13 +2,18 @@
 Configuring Strict-Transport-Security
 #####################################
 
-There are four configuration options:
+There are five configuration options:
 
 * **max-age** is a ``TimeSpan`` (see `TimeSpan.Parse <http://msdn.microsoft.com/en-us/library/se73z7b9.aspx>`_)
 * **includeSubdomains** adds *includeSubDomains* in the header, defaults to *false*
 * **preload** adds the *preload* directive, defaults to *false*. Max-age must be at least 18 weeks, and includeSubdomains must be enabled to use the preload directive. See the `Chromium HSTS docs <http://www.chromium.org/sts>`_ for details.
-* **httpsOnly** ensures that the HSTS header is set over secure connections only, defaults to *true*. 
+* **httpsOnly** ensures that the HSTS header is set over secure connections only, defaults to *true*.
+* **upgradeInsecureRequests** sets the HSTS header only for UAs that supports :doc:`Upgrade-insecure-requests`. This setting cannot be combined with **preload**.
 
+.. note::
+
+    **upgradeInsecureRequests** is intended to be used in combination with the :doc:`Upgrade-insecure-requests` CSP directive.
+
 =====================================================   =======================================================================
 Configuration                                           Resulting header
 =====================================================   =======================================================================
@@ -25,6 +30,8 @@ In web.config:
     <strict-Transport-Security max-age="365" />
     <strict-Transport-Security max-age="00:30:00" includeSubdomains="true" />
     <strict-Transport-Security max-age="365" includeSubdomains="true" preload="true"/>
+    <strict-Transport-Security max-age="365" upgradeInsecureRequests="true"/>
+
 
 :doc:`NWebsec.Owin`: Register the middleware in the OWIN startup class:
 
@@ -36,4 +43,5 @@ In web.config:
     {
         app.UseHsts(options => options.MaxAge(days:30).IncludeSubdomains());
         //app.UseHsts(options => options.MaxAge(days:365).IncludeSubdomains().Preload());
+        //app.UseHsts(options => options.MaxAge(days:365).UpgradeInsecureRequests());
     }

source/nwebsec/Configuring-referrerpolicy.rst

@@ -9,7 +9,7 @@ The Referrer Policy specification is under development at the time of writing, y
 .. note::
 
 	Initial browser support for referrer policy is through a meta tag. There have been changes to the policy keywords in the spec, which means that some browsers need to "catch up" with the spec.
-	Chrome has full support per October 2015, and Firefox will follow in November. Edge supports the old keywords in the spec and needs to catch up.
+	Chrome and Firefox are up to date per October 2015. Edge supports the old keywords in the spec and needs to catch up.
 
 NWebsec provides an HtmlHelper that lets you generate a meta tag with the referrer policy.
 

source/nwebsec/Upgrade-insecure-requests.rst

@@ -0,0 +1,72 @@
+#########################
+Upgrade Insecure Requests
+#########################
+
+``upgrade-insecure-requests`` is the latest addition to the CSP directives, but note that it lives in a `separate specification <http://www.w3.org/TR/upgrade-insecure-requests/>`_. Though it looks very innocent and straight forward to configure, there are some important considerations before employing it.
+
+The upgrade insecure requests CSP directive instructs browsers to upgrade all requests triggered by a page from HTTP to HTTPS. This lets site owners move legacy sites from HTTP to HTTPS without having to change every single link, and references to images, scripts and other content from HTTP to HTTPS to avoid mixed content issues.
+
+.. note::
+
+    Unless you're tasked with moving a legacy site that has been running on HTTP to HTTPS, and it has a bunch of hard coded references to HTTP resources on third party sites, ``upgrade-insecure-requests``
+    is not what you want. For new sites, the upcoming `Mixed Content <http://www.w3.org/TR/mixed-content/>`_ specification would be a better fit.
+
+************
+How it works
+************
+
+Say you have a site that has been running on http://www.example.com for years, and out of concern for your users' privacy you want to make the site available on https://www.example.com. You realize there's a daunting problem, http://www.example.com loads subresources (images, scripts etc.) from third party sites, these are all loaded over http:// and there's no easy way to change all those references to point to https://. These resources are regarded mixed content as soon as you move to https://www.example.com. The content is available over https:// on the third party sites, it's just that
+your're not able to update every reference to it.
+
+This is where ``upgrade-insecure-requests`` comes to the rescue. For browsers that support it, you can redirect users to https://www.example.com, and include a ``Content-Security-Policy: upgrade-insecure-requests`` header in the response. Conformant browsers will then load the page's resources from both same origin and third party sites over https://, and the mixed content problem goes away. The page and its subresources are all loaded over a (more) secure connection.
+
+You need to detect browser support for the ``upgrade-insecure-requests`` CSP directive. Redirecting non-conforming browsers to https:// will result in the mixed content issues. Fortunately, browsers will advertise their support through a request header:
+
+    Upgrade-Insecure-Requests: 1
+
+When you enable the ``upgrade-insecure-requests`` directive in NWebsec, conforming browsers will be redirected to https with a 307 status code in accordance with the spec. The directive will always be included in the CSP header, as non-conforming browsers will ignore it.
+
+This lets you gracefully move a legacy site from http to https as browser support for ``upgrade-insecure-requests`` improves over time.
+
+Strict-Transport-Security
+=========================
+As users are moved to https on your site, the Strict-Transport-Security (HSTS) header can ensure that you keep them there. NWebsec now supports setting the header only for UAs that support ``upgrade-insecure-requests``. This HSTS setting is useful in combination with ``upgrade-insecure-requests``, see :doc:`Configuring-hsts` for details.
+
+*************************************
+Configuring Upgrade Insecure Requests
+*************************************
+
+:doc:`NWebsec` lets you enable ``upgrade-insecure-requests`` with a single line in the CSP config:
+
+..  code-block:: xml
+
+    <nwebsec>
+      <httpHeaderSecurityModule>
+        <securityHttpHeaders>
+          <content-Security-Policy enabled="true">
+            <upgrade-insecure-requests enabled="true"  />          
+            <!--<upgrade-insecure-requests enabled="true" httpsPort="8443"  />-->
+          </content-Security-Policy>
+        </securityHttpHeaders>
+      </httpHeaderSecurityModule>
+    </nwebsec>
+
+:doc:`NWebsec.Owin` lets you do the same in your OWIN startup class:
+
+..  code-block:: c#
+
+    using NWebsec.Owin;
+    ...
+    public void Configuration(IAppBuilder app)
+    {
+        app.UseCsp(options => options.UpgradeInsecureRequests());
+        //app.UseCsp(options => options.UpgradeInsecureRequests(8443));
+    }
+
+.. note::
+
+    Remember to allow "same host redirects" if you're also using :doc:`Redirect-validation`.
+
+    Also note that NWebsec relies on the ``Request.IsSecureConnection`` for classic ASP.NET and the OWIN request scheme for OWIN apps
+    when determining whether to redirect from http to https. If you are behind a load balancer/reverse proxy that terminates the user's
+    https connection you must ensure that these properties are set correctly.