root
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Actions 12 Packages Projects Releases Wiki Activity

SEC-2285: Added headers to to reference

This commit is contained in:
Rob Winch 2013-08-28 00:54:52 -05:00
parent 9483226d02
commit 69aac09e1d
2 changed files with 283 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

282
docs/manual/src/docbook/headers.xml Normal file
View File

@ -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">&lt;headers&gt;</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">&lt;headers /&gt;</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">&lt;cache-control /&gt;</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 &lt;headers /&gt; 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">&lt;content-type-options&gt;</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 &lt;headers&gt; 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">&lt;hsts&gt;</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 &lt;headers&gt; 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 &lt;headers&gt; 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>

1
docs/manual/src/docbook/index.xml
View File

@ -131,6 +131,7 @@
<xi:include href="basic-and-digest-auth.xml"/> <xi:include href="basic-and-digest-auth.xml"/>
<xi:include href="remember-me-authentication.xml"/> <xi:include href="remember-me-authentication.xml"/>
<xi:include href="csrf.xml"/> <xi:include href="csrf.xml"/>
<xi:include href="headers.xml"/>
<xi:include href="session-mgmt.xml"/> <xi:include href="session-mgmt.xml"/>
<xi:include href="anon-auth-provider.xml"/> <xi:include href="anon-auth-provider.xml"/>
</part> </part>