Some final updates to 4.1 docs

source/index.rst

@@ -18,26 +18,23 @@ NWebsec - Security libraries for ASP.NET
    nwebsec/NWebsec-and-the-SDL
 
 
-NWebsec consists of several security libraries for ASP.NET applications. Consult the [[Documentation]] to see how it works.
+NWebsec consists of several security libraries for ASP.NET applications. Three of these libraries work together to remove version headers, control cache headers, stop potentially dangerous redirects, and set important security headers. They are collectively referred to as "NWebsec":
 
-You'll find the NWebsec packages on NuGet:
+* `NWebsec <https://nuget.org/packages/NWebsec/>`_
+* `NWebsec.Mvc <https://nuget.org/packages/NWebsec.Mvc/>`_
+* `NWebsec.Owin <https://nuget.org/packages/NWebsec.Owin/>`_
 
-* https://nuget.org/packages/NWebsec/
-* https://nuget.org/packages/NWebsec.Mvc/
-* https://nuget.org/packages/NWebsec.Owin/
-* https://nuget.org/packages/NWebsec.SessionSecurity/
-* https://nuget.org/packages/NWebsec.AzureStartupTasks/
+If you're not sure what "security headers" are, check out this blog post: `Security through HTTP response headers <http://www.dotnetnoob.com/2012/09/security-through-http-response-headers.html>`_.
 
-NWebsec/NWebsec.Mvc lets you remove version headers, control cache headers, stop potentially dangerous redirects, and set important security headers. If you're not sure what "security headers" are, check out this blog post: `Security through HTTP response headers <http://www.dotnetnoob.com/2012/09/security-through-http-response-headers.html>`_.
+There are also two stand-alone libraries. Since they don't follow the versions of the security header libraries, they are documented as separate projects. 
 
-NWebsec.Owin provides OWIN middleware to stop potentially dangerous redirects and set important security headers.
+* `NWebsec.SessionSecurity <https://nuget.org/packages/NWebsec.SessionSecurity/>`_ - `docs here <http://docs.nwebsec.com/projects/SessionSecurity/en/latest/>`_.
+* `NWebsec.AzureStartupTasks <https://nuget.org/packages/NWebsec.AzureStartupTasks/>`_ - `docs here <http://docs.nwebsec.com/projects/AzureStartupTasks/en/latest/>`_.
 
 NWebsec.SessionSecurity improves ASP.NET session security. Read more about the improvements in the blog post `Ramping up ASP.NET session security <http://www.dotnetnoob.com/2013/07/ramping-up-aspnet-session-security.html>`_.
 
 `NWebsec.AzureStartupTasks <https://github.com/NWebsec/NWebsec.AzureStartupTasks/wiki>`_ helps you harden the TLS configuration for Azure web role instances. Learn why you need to harden the default TLS configuration in the blog post `Hardening Windows Server 2008/2012 and Azure SSL/TLS configuration <http://www.dotnetnoob.com/2013/10/hardening-windows-server-20082012-and.html>`_.
 
-Did you now that the SDL requires countermeasures against session fixation attacks, and that certain security headers must set by your web application? No? See [[NWebsec and the SDL]] to learn more.
-
 Check out the `NWebsec demo site <http://www.nwebsec.com/>`_ to see the headers and session security improvements in action.
 
 To keep up with new releases or to give feedback, find `@NWebsec <https://twitter.com/NWebsec>`_ on Twitter. You can also get in touch at nwebsec (at) nwebsec (dot) com.

source/nwebsec/Breaking-changes.rst

@@ -21,7 +21,7 @@ Removed/moved all types from the **NWebsec.Csp** namespace
 
 Consequently, the following using statement will trigger a compilation error: 
 
-.. 	code-block::
+.. 	code-block:: c#
 
 	using NWebsec.Csp;
 
@@ -32,14 +32,14 @@ CSP attribute source configuration.
 
 With NWebsec.Mvc versions < 4 you would configure CSP sources with an enum. This made the code unnecessarily hard to read.
 
-.. 	code-block::
+.. 	code-block:: c#
 
 	[CspDefaultSrc(Self = Source.Enable)]
 	[CspDefaultSrc(Self = Source.Disable)]
 
 As of version four you configure them with a boolean. This makes makes the code easier to read.
 
-.. 	code-block::
+.. 	code-block:: c#
 
 	[CspDefaultSrc(Self = true)]
 	[CspDefaultSrc(Self = false)]
@@ -61,12 +61,12 @@ To enable it for all responses you must set the httpsOnly attribute to false in
 
 Or you specify that it should be included in all responses for the OWIN middleware:
 
-..	code-block::
+..	code-block:: c#
 
 	app.UseHsts(options => options.MaxAge(days:18*7).AllResponses());
 
 ***********
 NWebsec 3.x
 ***********
 
-The  `<suppressVersionHttpHeaders>`  configuration setting is no longer supported.
+The  ``<suppressVersionHttpHeaders>``  configuration setting is no longer supported.

source/nwebsec/Configuration.rst

@@ -19,13 +19,13 @@ Configuration
    X-Robots-Tag <Configuring-xrt>
    Suppressing-version-headers
 
-This is the documentation for NWebsec 4.x web.config.
-
-Those running an older versions should consult [[Breaking changes]] before upgrading major versions and can find old versions of this document here: [[Configuration 3.x]].
+Those running an older versions should consult :doc:`Breaking-changes` before upgrading major versions.
 
 You're strongly advised to upgrade if you're still running NWebsec 2.x, as you can run into issues with async requests due to changes in ASP.NET.
 
-## Web.config
+**********
+Web.config
+**********
 
 Only the most basic configuration is added to web.config when installing the NWebsec library with the NuGet package manager. Here's an example of what's added to web.config:
 
@@ -67,8 +67,7 @@ Only the most basic configuration is added to web.config when installing the NWe
 
 The NWebsec config section is declared, the module is loaded, custom http headers will be cleared, the NWebsec configuration directory is declared as a hidden segment, and an empty NWebsec configuration section is added.
 
-You'll probably notice that configuration is also added to the `<system.webserver>` section in order to load the NWebsec *httpHeaderModule* . If you're running on IIS 6 or in Classic Pipeline Mode you will have to do some manual changes to your web.config to load the module, see [IIS 6 or IIS 7 Classic Pipeline Mode
-](#iis-6-or-iis-7-classic-pipeline-mode).
+You'll probably notice that configuration is also added to the `<system.webserver>` section in order to load the NWebsec *httpHeaderModule* . If you're running on IIS 6 or in Classic Pipeline Mode you will have to do some manual changes to your web.config to load the module, see :ref:`classic-pipeline`.
 
 The configuration schema gives you intellisense for all NWebsec configuration elements, so feel free to start of with the empty section and add the security headers you need.
 
@@ -151,6 +150,8 @@ For the curious, here's a complete configuration section with all headers disabl
 
   </configuration>
 
+.. _classic-pipeline:
+
 ************************************
 IIS 6 or IIS 7 Classic Pipeline Mode
 ************************************

source/nwebsec/Configuring-csp.rst

@@ -14,7 +14,8 @@ Chrome and Firefox have partial support for CSP Level 2.
 
 A page's content security policy is set through the following headers:
 
-* **Content-Security-Policy** and **Content-Security-Policy-Report-Only**
+* **Content-Security-Policy**
+* **Content-Security-Policy-Report-Only**
 
 **********************
 CSP support in NWebsec

source/nwebsec/Configuring-hpkp.rst

@@ -11,7 +11,10 @@ There are four configuration options, as well as a list of certs to pin and/or a
 * **certificates** specifies a list of certificates (by thumbprints) that should be pinned. 
 * **pins** specifies a list of pinning values for certificates that should be pinned
 
-The following examples assume that we supply the pinning values: n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE= and d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=
+The following examples assume that we supply the pinning values: 
+
+* n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE=
+* d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=
 
 .. |br| raw:: html
 
@@ -23,7 +26,7 @@ Configuration
 max-age="00:00:00"                                                                        Public-Key-Pins: max-age=0
 max-age="12:00:00"                                                                        Public-Key-Pins: max-age=43200;pin-sha256="n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE=";pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM="
 max-age="365" |br| includeSubdomains="true"                                               Public-Key-Pins: max-age=31536000;includeSubdomains;pin-sha256="n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE=";pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM="
-max-age="365" |br| includeSubdomains="true" |br| report-uri="https://report.nwebsec.com/  Public-Key-Pins: max-age=1;includeSubdomains;pin-sha256="n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE=";pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";report-uri="https://report.nwebsec.com/" |
+max-age="365" |br| includeSubdomains="true" |br| report-uri="https://report.nwebsec.com/  Public-Key-Pins: max-age=31536000;includeSubdomains;pin-sha256="n3dNcH43TClpDuyYl55EwbTTAuj4T7IloK4GNaH1bnE=";pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";report-uri="https://report.nwebsec.com/" |
 ========================================================================================  ==============================================================================
 
 In web.config:

source/nwebsec/Configuring-xrt.rst

@@ -12,7 +12,7 @@ REP gives some control over which content search engines will index on your site
 
 In addition to `robots.txt <http://www.robotstxt.org/>`_ and meta tags, some of the major search engines support REP through an HTTP header. The following header is the equivalent to the aforementioned meta tag:
 
-..
+::
 
   X-Robots-Tag: noindex, nofollow
 

source/nwebsec/NWebsec.Mvc.rst

@@ -2,9 +2,9 @@
 NWebsec.Mvc
 ###########
 
-NWebsec.Mvc lets you configure the [[HttpHeaderModule]] through MVC ActionFilter attributes. MVC 3 or newer is supported. By decorating controllers and actions with attributes, the HttpHeaderModule's [[Configuration]] is overridden. This is how it works:
+NWebsec.Mvc lets you configure NWebsec through MVC ActionFilter attributes. MVC 3 or newer is supported. By decorating controllers and actions with attributes, the :doc:`NWebsec` configuration is overridden. This is how it works:
 
-NWebsec.Mvc depends on the NWebsec package, which includes the HttpHeaderModule. This module relies on its [[Configuration]], if there is any. Now, the attributes in NWebsec.Mvc lets you override the HttpHeaderModule's configuration, here's the order in which the final configuration is calculated:
+NWebsec.Mvc depends on the NWebsec package, which includes the HttpHeaderModule. This module relies on its :doc:`Configuration`, if there is any. Now, the attributes in NWebsec.Mvc lets you override the HttpHeaderModule's configuration, here's the order in which the final configuration is calculated:
 
 #. Web.config
 #. MVC global filter
@@ -17,9 +17,7 @@ This gives a fair amount of flexibility. Do your stuff in config or in MVC, or b
 The attributes
 **************
 
-Most elements from the [[Configuration]] have an MVC attribute counterpart, see [[Configuring security headers]] to learn what their settings are.
-
-The Content Security Policy attributes are a bit special, see [[Configuring Content Security Policy]] for details. 
+Most elements from the :doc:`Configuration` have an MVC attribute counterpart.
 
 Now back to the attributes — they are probably best explained in code. Here are the attributes registered as global filters in Global.asax in a typical MVC app:
 

source/nwebsec/NWebsec.Owin.rst

@@ -27,4 +27,4 @@ Note that the middleware has been developed and tested under Katana.
 Documentation
 *************
 
-The middleware is documented alongside the web.config and MVC attributes. Refer to the [[NWebsec]] documentation for samples.
+The middleware is documented alongside the web.config and MVC attributes. Refer to the :doc:`Configuration` for samples.

source/nwebsec/NWebsec.rst

@@ -2,28 +2,22 @@
 NWebsec
 #######
 
-NWebsec currently consists of a [[HttpHeaderModule]] that lets you manage HTTP headers. It can remove version headers, as well as output various security HTTP headers.
+NWebsec provides an `HTTP Module <https://msdn.microsoft.com/library/ms178468.aspx>`_ that controls which headers are sent in the response from an ASP.NET application. The HTTP Module works for both Web Forms application and MVC applications as it hooks into the `ASP.NET/IIS pipeline <http://msdn.microsoft.com/en-us/library/bb470252.aspx>`_. There, it makes changes to the HTTP header collection according to the NWebsec configuration.
 
-* See [[Getting started]] if you're the impatient type.
-* See [[Configuration]] to study NWebsec's configuration section.
-* See [[Configuring cache headers]] to set secure cache headers.
-* See [[Suppressing version headers]] to figure out how you can get rid of version headers.
-* See [[Redirect validation]] to avoid unvalidated redirect vulnerabilities.
-* See [[Configuring X-Robots-Tag]] to learn how to use the Robots Exclusion Protocol (REP) through HTTP headers.
-* See [[Configuring security headers]] for a detailed explanation on how to configure each security header.
-* See [[Configuring Content Security Policy]] to learn more about the Content Security Policy header.
-* See [[NWebsec.Mvc]] to discover how you can configure security headers for your MVC application through the NWebsec MVC attributes.
+The Http Module lets you set common security headers without any code changes, it is loaded and configured strictly through web.config.  This is a quick win for the security of ASP.NET applications. Security of legacy applications can be improved quite easily as well. The flexibility of the configuration means that various parts of an application can run with different configurations.
+
+The NWebsec library is a "configuration only" install, it requires no code changes to your application. You'll find it on `NuGet <http://www.nuget.org/packages/NWebsec/>`_, or you can download the assemblies from the `GitHub releases <https://github.com/NWebsec/NWebsec/releases>`_. See :doc:`Configuration` to learn how to configure it.
 
 ****************
 Security headers
 ****************
 
 Supported security headers are:
 
-* X-Frame-Options
+* Content-Security-Policy / Content-Security-Policy-Report-Only
 * Strict-Transport-Security
+* Public-Key-Pins / Public-Key-Pins-Report-Only
+* X-Frame-Options
+* X-XSS-Protection
 * X-Content-Type-Options
 * X-Download-Options
-* X-XSS-Protection
-* Content-Security-Policy / Content-Security-Policy-Report-Only
-* Public-Key-Pins / Public-Key-Pins-Report-Only

source/nwebsec/getting-started.rst

@@ -16,15 +16,15 @@ For non-MVC apps use the following:
 
     Install-Package NWebsec
 
-Alternatively, you can get the latest version of the assemblies under `releases <https://github.com/NWebsec/NWebsec/releases>`_ if you want to add them by hand. In that case, refer to [[Configuration]] to also edit the configuration by hand. 
+Alternatively, you can get the latest version of the assemblies under `releases <https://github.com/NWebsec/NWebsec/releases>`_ if you want to add them by hand. In that case, refer to :doc:`Configuration` to also edit the configuration by hand. 
 
 Now it's time to start securing your application! It's good practice to remove the version headers added by ASP.NET and IIS, so you'd want to *suppress version headers* for your web application. The NuGet installation procedure will make some modifications to the web.config to disable version headers.
 
 To avoid various attacks carried out through iframes, the *X-Frame-Options header* should be enabled. MIME sniffing is a source to many problems, including security issues, so you'd want to run with the *X-Content-Type-Options header*.
 
 For applications that run over SSL/TLS, you should most definitely employ the *Strict-Transport-Security header* — instructing the browser to interact with anything on your domain over a secured connection only.
 
-Unless your application needs to redirect users to arbitrary sites on the internet, you'd want *redirect validation* enabled. There might be a few sites you'd want to whitelist for redirects, in particular if you use WIF or Google/Facebook/any other external authentication provider. Consult the [[Configuration]] docs if you run into trouble.
+Unless your application needs to redirect users to arbitrary sites on the internet, you'd want *redirect validation* enabled. There might be a few sites you'd want to whitelist for redirects, in particular if you use WIF or Google/Facebook/any other external authentication provider. Consult :doc:`Redirect-validation` if you run into trouble.
 
 So, for an application running over http the following is a reasonable starting point for your web.config:
 
@@ -70,6 +70,6 @@ NWebsec lets you add other security headers as well, but these are more tightly
 * `Using Content Security Policy to Prevent Cross-Site Scripting (XSS) <http://blog.sendsafely.com/post/42277333593/using-content-security-policy-to-prevent-cross-site>`_
 * `Retrofitting Code for Content Security Policy <http://blog.sendsafely.com/post/50303516209/retrofitting-code-for-content-security-policy>`_
 
-See [[Configuring Content Security Policy]] to learn how to enable CSP, this is where the real job starts. Good luck! :)
+See :doc:`Configuring-csp` to learn how to enable CSP, this is where the real job starts. Good luck! :)
 
-Note also that security headers can be enabled through MVC attributes, refer to [[NWebsec.Mvc]] for details.
+Note also that security headers can be enabled through MVC attributes, refer to :doc:`NWebsec.Mvc` for details.