SEC-2285: Added headers to to reference
This commit is contained in:
Rob Winch
parent
9483226d02
commit
69aac09e1d
|
|
@ -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>
|
||||
|
|
@ -131,6 +131,7 @@
|
|||
<xi:include href="basic-and-digest-auth.xml"/>
|
||||
<xi:include href="remember-me-authentication.xml"/>
|
||||
<xi:include href="csrf.xml"/>
|
||||
<xi:include href="headers.xml"/>
|
||||
<xi:include href="session-mgmt.xml"/>
|
||||
<xi:include href="anon-auth-provider.xml"/>
|
||||
</part>
|
||||
|
|
|
|||
Loading…
Reference in New Issue