Merge branch 'main' into feature/docs-basic-entries

docs/configuration/Cache-Control.md

@@ -0,0 +1,49 @@
+---
+title: Cache-Control
+nav_order: 7
+parent: Configuration
+layout: page
+---
+
+The Mozilla Developer Network describes the Cache-Control header like this:
+
+{: .quote }
+> The HTTP Cache-Control header holds directives (instructions) in both requests and responses that control caching in browsers and shared caches (e.g., Proxies, CDNs).
+>
+> source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+
+A Cache-Control header can be added in one of two ways, either using the default middleware options:
+
+```csharp
+app.UseSecureHeadersMiddleware();
+```
+
+The above adds the Cache-Control header with a `no-store, max-age=0` value.
+
+Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
+
+```csharp
+var customConfig = SecureHeadersMiddlewareBuilder
+    .CreateBuilder()
+    .UseCacheControl()
+    .Build();
+
+app.UseSecureHeadersMiddleware(customConfig);
+```
+
+The above adds the Cache-Control header with a `no-store, max-age=0` value.
+
+## Full Options
+
+The Cache-Control header object (known internally as `CacheControl`) has the following options:
+
+- bool: `Private`
+- int: `MaxAge`
+- bool: `NoCache`
+- bool: `MustReevaluate`
+- bool: `NoStore`
+
+These values can be set when creating a new instance of the `ReferrerPolicyOptions` object, or by calling the `UseCacheControl` extension method on the `SecureHeadersMiddlewareConfiguration` class.
+
+{: .warning }
+> It's worth noting that the default values for this header mean that no content will be cached in the browser. You may need to evaluate this default value on a case-by-case basis. 

docs/configuration/Content-Security-Policy.md

@@ -1,6 +1,6 @@
 ---
 title: Content-Security-Policy
-nav_order: 5
+nav_order: 4
 parent: Configuration
 layout: page
 ---

docs/configuration/Referrer-Policy.md

@@ -0,0 +1,53 @@
+---
+title: Referrer-Policy
+nav_order: 6
+parent: Configuration
+layout: page
+---
+
+The Mozilla Developer Network describes the Referrer-Policy header like this:
+
+{: .quote }
+> The HTTP Referrer-Policy response header controls how much referrer information (sent with the Referer header) should be included with requests.
+>
+> source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
+
+A Referrer-Policy header can be added in one of two ways, either using the default middleware options:
+
+```csharp
+app.UseSecureHeadersMiddleware();
+```
+
+The above adds the Referrer-Policy header with a `no-referrer` value.
+
+Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
+
+```csharp
+var customConfig = SecureHeadersMiddlewareBuilder
+    .CreateBuilder()
+    .UseReferrerPolicy()
+    .Build();
+
+app.UseSecureHeadersMiddleware(customConfig);
+```
+
+The above adds the Referrer-Policy header with a `no-referrer` value.
+
+## Full Options
+
+The Referrer-Policy header object (known internally as `ReferrerPolicy`) has the following options:
+
+- enum: `ReferrerPolicyOptions`
+
+The values available for the `ReferrerPolicyOptions` enum are:
+
+- `noReferrer`
+- `noReferrerWhenDowngrade`
+- `origin`
+- `originWhenCrossOrigin`
+- `sameOrigin`
+- `strictOrigin`
+- `strictWhenCrossOrigin`
+- `unsafeUrl`
+
+These values can be set when creating a new instance of the `ReferrerPolicyOptions` object, or by calling the `UseReferrerPolicy` extension method on the `SecureHeadersMiddlewareConfiguration` class.

docs/configuration/Strict-Transport-Security.md

@@ -28,12 +28,12 @@ The above adds the HSTS header with the following values:
 Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
 
 ```csharp
-var customHstsConfig = SecureHeadersMiddlewareBuilder
+var customConfig = SecureHeadersMiddlewareBuilder
     .CreateBuilder()
     .UseHsts(1200, false)
     .Build();
 
-app.UseSecureHeadersMiddleware(customHstsConfig);
+app.UseSecureHeadersMiddleware(customConfig);
 ```
 
 The above adds the HSTS header with the following values:

docs/configuration/X-Content-Type-Options.md

@@ -1,6 +1,6 @@
 ---
 title: X-Content-Type-Options
-nav_order: 4
+nav_order: 3
 parent: Configuration
 layout: page
 ---
@@ -23,12 +23,12 @@ The above adds the X-Content-Type-Options header with a `nosniff` value.
 Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
 
 ```csharp
-var customHstsConfig = SecureHeadersMiddlewareBuilder
+var customConfig = SecureHeadersMiddlewareBuilder
     .CreateBuilder()
     .UseContentTypeOptions()
     .Build();
 
-app.UseSecureHeadersMiddleware(customHstsConfig);
+app.UseSecureHeadersMiddleware(customConfig);
 ```
 
 The above adds the X-Content-Type-Options header with a `nosniff` value.

docs/configuration/X-Frame-Options.md

@@ -25,12 +25,12 @@ The above adds the X-Frame-Options header with a `deny` value.
 Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
 
 ```csharp
-var customHstsConfig = SecureHeadersMiddlewareBuilder
+var customConfig = SecureHeadersMiddlewareBuilder
     .CreateBuilder()
     .UseXFrameOptions(XFrameOptions.Sameorigin)
     .Build();
 
-app.UseSecureHeadersMiddleware(customHstsConfig);
+app.UseSecureHeadersMiddleware(customConfig);
 ```
 
 The above adds the X-Frame-Options header with a `Sameorigin` value.
@@ -40,7 +40,7 @@ This allows any <frame>, <iframe>, <embed> or <object> elements to be included o
 
 ## Full Options
 
-The X-Frame-Options header object (known internally as `UseXFrameOptions`) has the following options:
+The X-Frame-Options header object (known internally as `XFrameOptionsConfiguration`) has the following options:
 
 - enum: `XFrameOptions`
 
@@ -50,4 +50,3 @@ The values available for the `XFrameOptions` enum are:
 - `Sameorigin`
 
 These values can be set when creating a new instance of the `HstsConfiguration` object, or by calling the `UseHsts` extension method on the `SecureHeadersMiddlewareConfiguration` class.
-

docs/configuration/X-Permitted-Cross-Domain-Policies.md

@@ -0,0 +1,55 @@
+---
+title: X-Permitted-Cross-Domain-Policies
+nav_order: 5
+parent: Configuration
+layout: page
+---
+
+The Mozilla Developer Network describes the X-Permitted-Cross-Domain-Policies header like this:
+
+{: .quote }
+> Specifies if a cross-domain policy file (crossdomain.xml) is allowed. The file may define a policy to grant clients, such as Adobe's Flash Player (now obsolete), Adobe Acrobat, Microsoft Silverlight (now obsolete), or Apache Flex, permission to handle data across domains that would otherwise be restricted due to the Same-Origin Policy.
+>
+> source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+
+{: .note} 
+> It is worth noting that the X-Permitted-Cross-Domain-Policies header was originally created when browsers would make use of Adobe's Flash Player, Adobe Acrobat, Microsoft Silverlight, or Apache Flex and that two of those technologies are now obsolete.
+> 
+> Whilst those technologies are obsolete, it's still worth having this header present as a "belt-and-braces" check against any future vulnerabilities which might mask themselves as any of the obsolete technologies it was invented to protect.
+
+An X-Permitted-Cross-Domain-Policies header can be added in one of two ways, either using the default middleware options:
+
+```csharp
+app.UseSecureHeadersMiddleware();
+```
+
+The above adds the X-Permitted-Cross-Domain-Policies header with a `none` value.
+
+Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
+
+```csharp
+var customConfig = SecureHeadersMiddlewareBuilder
+    .CreateBuilder()
+    .UsePermittedCrossDomainPolicies()
+    .Build();
+
+app.UseSecureHeadersMiddleware(customConfig);
+```
+
+The above adds the X-Permitted-Cross-Domain-Policies header with a `none` value.
+
+## Full Options
+
+The X-Permitted-Cross-Domain-Policies header object (known internally as `PermittedCrossDomainPolicyConfiguration`) has the following options:
+
+- enum: `XPermittedCrossDomainOptionValue`
+
+The values available for the `XPermittedCrossDomainOptionValue` enum are:
+
+- `none`
+- `masterOnly`
+- `byContentType`
+- `byFtpFileType`
+- `all`
+
+These values can be set when creating a new instance of the `XPermittedCrossDomainOptionValue` object, or by calling the `UsePermittedCrossDomainPolicies` extension method on the `SecureHeadersMiddlewareConfiguration` class.

docs/configuration/X-XSS-Protection.md

@@ -1,6 +1,6 @@
 ---
 title: X-XSS-Protection
-nav_order: 3
+nav_order: 8
 parent: Configuration
 layout: page
 ---
@@ -25,12 +25,12 @@ The above adds the X-XSS-Protection header with a "0" value.
 Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code:
 
 ```csharp
-var customHstsConfig = SecureHeadersMiddlewareBuilder
+var customConfig = SecureHeadersMiddlewareBuilder
     .CreateBuilder()
     .UseXssProtection()
     .Build();
 
-app.UseSecureHeadersMiddleware(customHstsConfig);
+app.UseSecureHeadersMiddleware(customConfig);
 ```
 
 The above adds the X-XSS-Protection header with a "0" value.

src/Extensions/SecureHeadersMiddlewareBuilder.cs

@@ -256,7 +256,7 @@ public static SecureHeadersMiddlewareConfiguration UseReferrerPolicy
         /// </exception>
         public static SecureHeadersMiddlewareConfiguration UseCacheControl
         (this SecureHeadersMiddlewareConfiguration config,
-            bool @private = true, int maxAge = 31536000, bool noCache = false, bool noStore = false,
+            bool @private = false, int maxAge = 0, bool noCache = false, bool noStore = true,
             bool mustRevalidate = false)
         {
             config.UseCacheControl = true;

src/Models/CacheControl.cs

@@ -11,6 +11,7 @@ public class CacheControl : IConfigurationBase
         /// Whether all or part of the HTTP response message is intended for a
         /// single user and must not be cached by a shared cache.
         /// </summary>
+        /// <remarks>
         /// The following is taken from the MDN article for cache-control
         ///    If you forget to add private to a response with personalized content,
         ///    then that response can be stored in a shared cache and end up being
@@ -63,8 +64,8 @@ public class CacheControl : IConfigurationBase
         [ExcludeFromCodeCoverage]
         protected CacheControl() { }
 
-        public CacheControl(bool @private, int maxAge = 86400, bool noCache = false,
-            bool noStore = false, bool mustRevalidate = false)
+        public CacheControl(bool @private, int maxAge = 0, bool noCache = false,
+            bool noStore = true, bool mustRevalidate = false)
         {
             Private = @private;
             MaxAge = maxAge;
@@ -86,22 +87,23 @@ public string BuildHeaderValue()
                 return stringBuilder.ToString();
             }
 
-            if (NoStore)
+            if (Private)
             {
-                stringBuilder.Append("no-store");
+                stringBuilder.Append("private");
                 return stringBuilder.ToString();
             }
 
-            stringBuilder.Append("max-age=");
-            stringBuilder.Append(MaxAge);
             if (MustRevalidate)
             {
-                stringBuilder.Append(", must-revalidate");
+                stringBuilder.Append("must-revalidate");
+                return stringBuilder.ToString();
             }
 
-            if (Private)
+            stringBuilder.Append($"max-age={MaxAge},");
+            if (NoStore)
             {
-                stringBuilder.Append(", private");
+                stringBuilder.Append("no-store");
+                return stringBuilder.ToString();
             }
 
             return stringBuilder.ToString();

src/OwaspHeaders.Core.csproj

@@ -8,7 +8,7 @@
 
     <!-- NuGet metadata -->
     <PackageId>OwaspHeaders.Core</PackageId>
-    <Version>9.2.3</Version>
+    <Version>9.3.0</Version>
     <Authors>Jamie Taylor</Authors>
     <Company>RJJ Software Ltd</Company>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>

tests/OwaspHeaders.Core.Tests/SecureHeadersMiddlewareExtensionTests/SecureHeadersMiddlewareTests.cs

@@ -79,7 +79,7 @@ public void BuildDefaultConfiguration_Returns_Valid_Configuration()
 
         // Cache-Control
         Assert.True(response.UseCacheControl);
-        Assert.Equal("max-age=31536000, private", response.CacheControl.BuildHeaderValue());
+        Assert.Equal("max-age=0,no-store", response.CacheControl.BuildHeaderValue());
 
         // X-XSS-Protection
         Assert.True(response.UseXssProtection);