|
|
@@ -0,0 +1,282 @@
|
|
|
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="headers"
|
|
|
+ xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
|
+ <info>
|
|
|
+ <title>Security Headers</title>
|
|
|
+ </info>
|
|
|
+ <para>This section discusses Spring Security's support for adding various security headers to the response.</para>
|
|
|
+ <section>
|
|
|
+ <title>Default Security Headers</title>
|
|
|
+ <para>Spring Security allows users to easily inject the default security headers to assist in protecting their
|
|
|
+ application.
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <link linkend="headers-cache-control">Cache Control</link>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <link linkend="headers-content-type-options">Content Type Options</link>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <link linkend="headers-hsts">HTTP Strict Transport Security</link>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <link linkend="headers-frame-options">X-Frame-Options</link>
|
|
|
+ </listitem>
|
|
|
+ <listitem>
|
|
|
+ <link linkend="headers-xss-protection">X-XSS-Protection</link>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist></para>
|
|
|
+ <para>While each of these headers are considered best practice, it should be noted that not all clients
|
|
|
+ utilize the headers, so additional testing is encouraged. If you are using Spring Security's XML namespace support,
|
|
|
+ you can easily add all of the default headers with the
|
|
|
+ <link linkend="nsa-headers"><headers></link> element with no child elements:</para>
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<http ...>
|
|
|
+ ...
|
|
|
+ <headers />
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>If you are using Spring Security's Java configuration, all of the default security headers are added by default.
|
|
|
+ They can be disabled using the Java configuration below:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers().disable()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+ <section xml:id="headers-cache-control">
|
|
|
+ <title>Cache Control</title>
|
|
|
+ <para>In the past Spring Security required you to provide your own cache control for your web application. This
|
|
|
+ seemed reasonable at the time, but browser caches have evolved to include caches for secure connections as
|
|
|
+ well. This means that a user may view an authenticated page, log out, and then a malicious user can use the
|
|
|
+ browser history to view the cached page. To help mitigate this Spring Security has added cache control support
|
|
|
+ which will insert the following headers into you response.</para>
|
|
|
+ <programlisting><![CDATA[Cache-Control: no-cache, no-store, max-age=0, must-revalidate
|
|
|
+Pragma: no-cache]]></programlisting>
|
|
|
+ <para>Simply adding the <link linkend="nsa-headers"><headers /></link> element with no child elements will
|
|
|
+ automatically add Cache Control and quite a few other protections. However, if you only want cache control, you can
|
|
|
+ enable this feature using Spring Security's XML namespace with the
|
|
|
+ <link linkend="nsa-cache-control"><cache-control /></link> element.</para>
|
|
|
+ <programlisting langauage="xml"><![CDATA[<http ...>
|
|
|
+ ...
|
|
|
+ <headers>
|
|
|
+ <cache-control />
|
|
|
+ </headers>
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>Similarly, you can enable only cache control within Java Configuration with the following:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers()
|
|
|
+ .cacheControl()
|
|
|
+ .and()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ <para>If you actually want to cache specific responses, your application can selectively invoke
|
|
|
+ <link xlink:href="http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletResponse.html#setHeader(java.lang.String, java.lang.String)">HttpServletResponse.setHeader(String,String)</link>
|
|
|
+ to override the header set by Spring Security. This is useful to ensure things
|
|
|
+ like CSS, JavaScript, and images are properly cached.</para>
|
|
|
+ <para>When using Spring Web MVC, this is typically done within your configuration. For example, the following configuration will
|
|
|
+ ensure that the cache headers are set for all of your resources:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebMvc
|
|
|
+public class WebMvcConfiguration extends WebMvcConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ public void addResourceHandlers(ResourceHandlerRegistry registry) {
|
|
|
+ registry
|
|
|
+ .addResourceHandler("/resources/**")
|
|
|
+ .addResourceLocations("/resources/")
|
|
|
+ .setCachePeriod(31556926);
|
|
|
+ }
|
|
|
+
|
|
|
+ // ...
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+ <section xml:id="headers-content-type-options">
|
|
|
+ <title>Content Type Options</title>
|
|
|
+ <para>Historically browsers, including Internet Explorer, would try to guess the content type of a request using
|
|
|
+ <link xlink:href="http://en.wikipedia.org/wiki/Content_sniffing">content sniffing</link>. This
|
|
|
+ allowed browsers to improve the user experience by guessing the content type on resources that had not specified the content type.
|
|
|
+ For example, if a browser encountered a JavaScript file that did not have the content type specified, it would be able to guess the content
|
|
|
+ type and then execute it.</para>
|
|
|
+ <note>
|
|
|
+ <para>There are many additional things one should do (i.e. only display the document in a distinct domain, ensure
|
|
|
+ Content-Type header is set, sanitize the document, etc) when allowing content to be uploaded. However, these measures
|
|
|
+ are out of the scope of what Spring Security provides. It is also important to point out when disabling content sniffing,
|
|
|
+ you must specify the content type in order for things to work properly.</para>
|
|
|
+ </note>
|
|
|
+ <para>The problem with content sniffing is that this allowed malicious users to use polyglots (i.e. a file that is valid as multiple content
|
|
|
+ types) to execute XSS attacks. For example, some sites may allow users to submit a valid postscript document to a website and view it. A malicious
|
|
|
+ user might create a <link xlink:href="http://webblaze.cs.berkeley.edu/papers/barth-caballero-song.pdf">postscript document that is also a valid
|
|
|
+ JavaScript file</link> and execute a XSS attack with it.</para>
|
|
|
+ <para>Content sniffing can be disabled by adding the following header to our response:</para>
|
|
|
+ <programlisting><![CDATA[X-Content-Type-Options: nosniff]]></programlisting>
|
|
|
+ <para>Just as with the cache control element, the nosniff directive is added by default when using the <headers /> element with no child elements.
|
|
|
+ However, if you want more control over which headers are added you can use the
|
|
|
+ <link linkend="nsa-content-type-options"><content-type-options></link> element as shown below:</para>
|
|
|
+ <programlisting language="xml"><![CDATA[<http ...>
|
|
|
+ ...
|
|
|
+ <headers>
|
|
|
+ <content-type-options />
|
|
|
+ </headers>
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>The X-Content-Type-Options header is added by default with Spring Security Java configuration. If you want more control over the headers, you can
|
|
|
+ explicitly specify the content type options with the following:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers()
|
|
|
+ .contentTypeOptions()
|
|
|
+ .and()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+ <section xml:id="headers-hsts">
|
|
|
+ <title>HTTP Strict Transport Security (HSTS)</title>
|
|
|
+ <para>When you type in your bank's website, do you enter mybank.example.com or do you enter https://mybank.example.com? If you
|
|
|
+ omit the https protocol, you are potentially vulnerable to
|
|
|
+ <link xlink:href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">Man in the Middle attacks</link>. Even if the website performs a redirect
|
|
|
+ to https://mybank.example.com a malicious user could intercept the initial HTTP request and manipulate the response (i.e.
|
|
|
+ redirect to https://mibank.example.com and steal their credentials).</para>
|
|
|
+ <para>Many users omit the https protocol and this is why <link xlink:href="http://tools.ietf.org/html/rfc6797">HTTP Strict Transport Security (HSTS)</link>
|
|
|
+ was created. Once mybank.example.com is added as a <link xlink:href="http://tools.ietf.org/html/rfc6797#section-5.1">HSTS host</link>, a browser can
|
|
|
+ know ahead of time that any request to mybank.example.com should be interpreted as
|
|
|
+ https://mybank.example.com. This greatly reduces the possibility of a Man in the Middle attack occurring.</para>
|
|
|
+ <note>
|
|
|
+ <para>In accordance with <link xlink:href="http://tools.ietf.org/html/rfc6797#section-7.2">RFC6797</link>, the HSTS header is only injected into HTTPS
|
|
|
+ responses. In order for the browser to acknowledge the header, the browser must first trust the CA that signed the SSL certificate used to make the
|
|
|
+ connection (not just the SSL certificate).</para>
|
|
|
+ </note>
|
|
|
+ <para>One way for a site to be marked as a HSTS host is to have the host preloaded into the browser. Another is to add the
|
|
|
+ "Strict-Transport-Security" header to the response. For example the following would instruct the browser to treat the domain as an HSTS
|
|
|
+ host for a year (there are approximately 31536000 seconds in a year):</para>
|
|
|
+ <programlisting><![CDATA[Strict-Transport-Security: max-age=31536000 ; includeSubDomains]]></programlisting>
|
|
|
+ <para>The optional includeSubDomains directive instructs Spring Security that subdomains (i.e. secure.mybank.example.com) should also be
|
|
|
+ treated as an HSTS domain.</para>
|
|
|
+ <para>As with the other headers, Spring Security adds the previous header to the response when the <headers> element is specified with
|
|
|
+ no child elements. It is also automatically added when you are using Java Configuration. You can also only use HSTS headers with the
|
|
|
+ <link linkend="nsa-hsts"><hsts></link> element as shown below:</para>
|
|
|
+ <programlisting language="xml"><![CDATA[<http ...>
|
|
|
+ ...
|
|
|
+ <headers>
|
|
|
+ <hsts />
|
|
|
+ </headers>
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>Similarly, you can enable only HSTS headers with Java Configuration:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers()
|
|
|
+ .hsts()
|
|
|
+ .and()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+ <section xml:id="headers-frame-options">
|
|
|
+ <title>X-Frame-Options</title>
|
|
|
+ <para>Allowing your website to be added to a frame can be a security issue. For example, using clever CSS styling users
|
|
|
+ could be tricked into clicking on something that they were not intending (
|
|
|
+ <link xlink:href="http://www.youtube.com/watch?v=3mk0RySeNsU">video demo</link>). For example, a user that is logged
|
|
|
+ into their bank might click a button that grants access to other users. This sort of attack is known as
|
|
|
+ <link xlink:href="http://en.wikipedia.org/wiki/Clickjacking">Clickjacking</link>.</para>
|
|
|
+ <note>
|
|
|
+ <para>Another modern approach to dealing with clickjacking is using a <link xlink:href="http://www.w3.org/TR/CSP/">Content
|
|
|
+ Security Policy</link>. Spring Security does not provide
|
|
|
+ support for this as the specification is not released and it is quite a bit more complicated. To stay up to date with this
|
|
|
+ issue and to see how you can implement it with Spring Security refer to
|
|
|
+ <link xlink:href="https://jira.springsource.org/browse/SEC-2117">SEC-2117</link> </para>
|
|
|
+ </note>
|
|
|
+ <para>There are a number ways to mitigate clickjacking attacks. For example, to protect legacy browsers from clickjacking attacks you
|
|
|
+ can use
|
|
|
+ <link xlink:href="https://www.owasp.org/index.php/Clickjacking_Defense_Cheat_Sheet#Best-for-now_Legacy_Browser_Frame_Breaking_Script">frame
|
|
|
+ breaking code</link>. While not perfect, the frame breaking code is the best you can do for the legacy browsers.</para>
|
|
|
+ <para>A more modern approach to address clickjacking is to use
|
|
|
+ <link xlink:href="https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options">X-Frame-Options</link> header:</para>
|
|
|
+ <programlisting><![CDATA[X-Frame-Options: DENY]]></programlisting>
|
|
|
+ <para>The X-Frame-Options response header instructs the browser to prevent any site with this header in the response from being rendered
|
|
|
+ within a frame. As with the other response headers, this is automatically included when the <headers> element is specified with no
|
|
|
+ child elements. You can also explicitly specify the <link linkend="nsa-frame-options">frame-options</link> element to control which headers
|
|
|
+ are added to the response.</para>
|
|
|
+ <programlisting language="xml"><![CDATA[<http ...>
|
|
|
+ ...
|
|
|
+ <headers>
|
|
|
+ <frame-options />
|
|
|
+ </headers>
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>Similarly, you can enable only frame options within Java Configuration with the following:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers()
|
|
|
+ .frameOptions()
|
|
|
+ .and()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+ <section xml:id="xss-protection">
|
|
|
+ <title>X-XSS-Protection</title>
|
|
|
+ <para>Some browsers have built in support for filtering out
|
|
|
+ <link xlink:href="https://www.owasp.org/index.php/Testing_for_Reflected_Cross_site_scripting_(OWASP-DV-001)">reflected
|
|
|
+ XSS attacks</link>. This is by no means full proof, but does assist in XSS protection.</para>
|
|
|
+ <para>The filtering is typically enabled by default, so adding the header typically just ensures it is enabled and
|
|
|
+ instructs the browser what to do when a XSS attack is detected. For example, the filter might try to change the
|
|
|
+ content in the least invasive way to still render everything. At times, this type of replacement can become a
|
|
|
+ <link xlink:href="http://hackademix.net/2009/11/21/ies-xss-filter-creates-xss-vulnerabilities/">XSS
|
|
|
+ vulnerability in itself</link>. Instead, it is best to block the content rather than attempt to fix it. To do this we can
|
|
|
+ add the following header:</para>
|
|
|
+ <programlisting><![CDATA[X-XSS-Protection: 1; mode=block]]></programlisting>
|
|
|
+ <para>This header is included by default when the <headers> element is specified with no child elements. We can explicitly
|
|
|
+ state it using the <link linkend="nsa-xss-protection">xss-protection</link> element as shown below:</para>
|
|
|
+ <programlisting language="xml"><![CDATA[<http ...>
|
|
|
+ ...
|
|
|
+ <headers>
|
|
|
+ <xss-protection />
|
|
|
+ </headers>
|
|
|
+</http>]]></programlisting>
|
|
|
+ <para>Similarly, you can enable only xss protection within Java Configuration with the following:</para>
|
|
|
+ <programlisting language="java"><![CDATA[@EnableWebSecurity
|
|
|
+@Configuration
|
|
|
+public class WebSecurityConfig extends
|
|
|
+ WebSecurityConfigurerAdapter {
|
|
|
+
|
|
|
+ @Override
|
|
|
+ protected void configure(HttpSecurity http) throws Exception {
|
|
|
+ http
|
|
|
+ .headers()
|
|
|
+ .xssProtection()
|
|
|
+ .and()
|
|
|
+ ...;
|
|
|
+ }
|
|
|
+}]]></programlisting>
|
|
|
+ </section>
|
|
|
+
|
|
|
+</chapter>
|
Rob Winch