Document disabling of CSP via $g_custom_headers

Fixes #19576
mantisbt · Apr 5, 2015 · f26298d · f26298d
1 parent 2191daa
commit f26298d
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 1 deletion.
diff --git a/config_defaults_inc.php b/config_defaults_inc.php
@@ -3384,13 +3384,20 @@
 ###########
 
 /**
- * An array of headers to be sent with each page.
+ * An array of custom headers to be sent with each page.
+ *
  * For example, to allow your MantisBT installation to be viewed in a frame in
  * IE6 when the frameset is not at the same hostname as the MantisBT install,
  * you need to add a P3P header. You could try something like
  * 'P3P: CP="CUR ADM"' in your config file, but make sure to check that the
  * your policy actually matches with what you are promising. See
  * http://msdn.microsoft.com/en-us/library/ms537343.aspx for more information.
+ *
+ * Even though this is not recommended, you could use this setting to disable
+ * previously sent headers. For example, assuming you didn't want to benefit
+ * from Content Security Policy, you could add 'Content-Security-Policy:' to
+ * the array.
+ *
  * @global array $g_custom_headers
  */
 $g_custom_headers = array();

diff --git a/docbook/Admin_Guide/en-US/config/security.xml b/docbook/Admin_Guide/en-US/config/security.xml
@@ -6,6 +6,43 @@
 	<title>Security and Cryptography</title>
 
 	<variablelist>
+		<varlistentry>
+			<term>Content Security Policy</term>
+			<listitem>
+				<para>Amongst other things, MantisBT relies on
+					<ulink url="http://en.wikipedia.org/wiki/Content_Security_Policy">
+						Content Security Policy</ulink> (CSP), which is a
+					<ulink url="http://www.w3.org/TR/CSP/">
+						W3C candidate recommendation</ulink>
+					improving the system's security against
+					<ulink url="http://en.wikipedia.org/wiki/Cross-site_scripting">
+						cross-site scripting (XSS)</ulink>
+					and other, similar types of attacks.
+					It is  currently supported in
+					<ulink url="http://caniuse.com/#feat=contentsecuritypolicy">
+						recent versions of many browsers</ulink>.
+				</para>
+				<note>
+					<para>CSP may cause issues in certain situations (e.g.
+						during development), or when using plugins relying on
+						externally hosted resources such as images or scripts.
+					</para>
+				</note>
+				<para>MantisBT currently does not provide any mechanism for
+					plugins to notify the Core of 'safe' external domains.
+					Because of that, even though it is not recommended for
+					obvious security reasons, you may wish to disable CSP.
+					You can do so by specifying a <emphasis>Custom Header</emphasis>
+					in your <literal>config_inc.php</literal> file
+					(see <xref linkend="admin.config.webserver" />).
+				</para>
+				<warning>
+					<para>Disabling Content Security Policy is a security risk !
+					</para>
+				</warning>
+			</listitem>
+		</varlistentry>
+
 		<varlistentry>
 			<term>$g_crypto_master_salt</term>
 			<listitem>

diff --git a/docbook/Admin_Guide/en-US/config/webserver.xml b/docbook/Admin_Guide/en-US/config/webserver.xml
@@ -59,5 +59,38 @@
 			</listitem>
 		</varlistentry>
 
+		<varlistentry>
+			<term>$g_custom_headers</term>
+			<listitem>
+				<para>An array of custom headers to be sent with each page.
+				</para>
+				<para>For example, to allow your MantisBT installation to be
+					viewed in a frame in IE6 when the frameset is not at the
+					same hostname as the MantisBT install, you need to add a
+					P3P header. You could try something like
+<programlisting>
+$g_custom_headers = array( 'P3P: CP="CUR ADM"' );
+</programlisting>
+					in your config file, but make sure to check that your policy
+					actually matches with what you are promising. See
+					<ulink url="http://msdn.microsoft.com/en-us/library/ms537343.aspx">
+						MSDN</ulink> for more information.
+				</para>
+				<para>Even though it is not recommended, you could also use
+					this setting to disable previously sent headers. For example,
+					assuming you didn't want to benefit from Content Security
+					Policy (CSP), you could set:
+<programlisting>
+$g_custom_headers = array( 'Content-Security-Policy:' );
+</programlisting>
+				</para>
+				<warning>
+					<para>Disabling CSP is a security risk, it is strongly
+						recommended that you leave it as Mantis defines it.
+					</para>
+				</warning>
+			</listitem>
+		</varlistentry>
+
 	</variablelist>
 </section>