Cwikius-Spring/spring-security
1
0
Fork 0
mirror of synced 2026-08-05 17:57:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

HTTP Public Key Pinning

Browse Source 
HTTP Public Key Pinning (HPKP) is a security mechanism which allows HTTPS websites
to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates.
(For example, sometimes attackers can compromise certificate authorities,
 and then can mis-issue certificates for a web origin.)
The HTTPS web server serves a list of public key hashes, and on subsequent connections
clients expect that server to use 1 or more of those public keys in its certificate chain.

This commit will add this new functionality.

Fixes gh-3706
This commit is contained in:
Tim Ysewyn
2016-02-18 23:18:42 +01:00
committed by Rob Winch
parent 8fbc7e0d2c
commit 331c7e91b7
15 changed files with 5030 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/src/docs/asciidoc/index.adoc
+135 -1
View File
@@ -3809,6 +3809,70 @@ protected void configure(HttpSecurity http) throws Exception {
}
----
[[headers-hpkp]]
==== HTTP Public Key Pinning (HPKP)
HTTP Public Key Pinning (HPKP) is a security feature that tells a web client to associate a specific cryptographic public key with a certain web server to prevent Man in the Middle (MITM) attacks with forged certificates.
To ensure the authenticity of a server's public key used in TLS sessions, this public key is wrapped into a X.509 certificate which is usually signed by a certificate authority (CA). Web clients such as browsers trust a lot of these CAs, which can all create certificates for arbitrary domain names.
If an attacker is able to compromise a single CA, they can perform MITM attacks on various TLS connections. HPKP can circumvent this threat for the HTTPS protocol by telling the client which public key belongs to a certain web server.
HPKP is a Trust on First Use (TOFU) technique. The first time a web server tells a client via a special HTTP header which public keys belong to it, the client stores this information for a given period of time.
When the client visits the server again, it expects a certificate containing a public key whose fingerprint is already known via HPKP. If the server delivers an unknown public key, the client should present a warning to the user.
[NOTE]
====
Because the UA needs to validate the pins against the SSL certificate chain, the HPKP header is only injected into HTTPS responses.
====
Enabling this feature for your site is as simple as returning the Public-Key-Pins HTTP header when your site is accessed over HTTPS. For example the following would instruct the browser to only report pin validation failures to a given URI for 2 pins:
[source]
----
Public-Key-Pins-Report-Only: max-age=5184000 ; pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=" ; pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=" ; report-uri="http://example.net/pkp-report" ; includeSubDomains
----
The optional includeSubDomains directive instructs the browser to also validate subdomains with the given pins.
Opposed to the other headers, Spring Security does not add HPKP by default. You can customize HPKP headers with the <<nsa-hpkp,<hpkp>>> element as shown below:
[source,xml]
----
<http>
<!-- ... -->
<headers>
<hpkp
include-subdomains="true"
report-uri="http://example.net/pkp-report">
<pins>
<pin algorithm="sha256">d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=</pin>
<pin algorithm="sha256">E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=</pin>
</pins>
</hpkp>
</headers>
</http>
----
Similarly, you can enable HPKP headers with Java Configuration:
[source,java]
----
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.httpPublicKeyPinning()
.includeSubdomains(true)
.reportUri("http://example.net/pkp-report")
.addSha256Pins("d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=", "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
}
}
----
[[headers-frame-options]]
==== X-Frame-Options
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 (http://www.youtube.com/watch?v=3mk0RySeNsU[video demo]). 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 http://en.wikipedia.org/wiki/Clickjacking[Clickjacking].
@@ -6894,7 +6958,7 @@ END;
[[appendix-namespace]]
== The Security Namespace
This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). If you haven't used the namespace before, please read the <<ns-config,introductory chapter>> on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. The namespace is written in http://www.relaxng.org/[RELAX NG] Compact format and later converted into an XSD schema. If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/master/config/src/main/resources/org/springframework/security/config/spring-security-4.0.rnc[schema file] directly.
This appendix provides a reference to the elements available in the security namespace and information on the underlying beans they create (a knowledge of the individual classes and how they work together is assumed - you can find more information in the project Javadoc and elsewhere in this document). If you haven't used the namespace before, please read the <<ns-config,introductory chapter>> on namespace configuration, as this is intended as a supplement to the information there. Using a good quality XML editor while editing a configuration based on the schema is recommended as this will provide contextual information on which elements and attributes are available as well as comments explaining their purpose. The namespace is written in http://www.relaxng.org/[RELAX NG] Compact format and later converted into an XSD schema. If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/master/config/src/main/resources/org/springframework/security/config/spring-security-4.1.rnc[schema file] directly.
[[nsa-web]]
=== Web Application Security
@@ -7065,6 +7129,7 @@ This element allows for configuring additional (security) headers to be send wit
** `X-Frame-Options` - Can be set using the <<nsa-frame-options,frame-options>> element. The http://en.wikipedia.org/wiki/Clickjacking#X-Frame-Options[X-Frame-Options ] header can be used to prevent clickjacking attacks.
** `X-XSS-Protection` - Can be set using the <<nsa-xss-protection,xss-protection>> element. The http://en.wikipedia.org/wiki/Cross-site_scripting[X-XSS-Protection ] header can be used by browser to do basic control.
** `X-Content-Type-Options` - Can be set using the <<nsa-content-type-options,content-type-options>> element. The http://blogs.msdn.com/b/ie/archive/2008/09/02/ie8-security-part-vi-beta-2-update.aspx[X-Content-Type-Options] header prevents Internet Explorer from MIME-sniffing a response away from the declared content-type. This also applies to Google Chrome, when downloading extensions.
** `Public-Key-Pinning` or `Public-Key-Pinning-Report-Only` - Can be set using the <<nsa-hpkp,hpkp>> element. This allows HTTPS websites to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates.
[[nsa-headers-attributes]]
===== <headers> Attributes
@@ -7095,6 +7160,7 @@ Optional attribute that specifies to disable Spring Security's HTTP response hea
* <<nsa-content-type-options,content-type-options>>
* <<nsa-frame-options,frame-options>>
* <<nsa-header,header>>
* <<nsa-hpkp,hpkp>>
* <<nsa-hsts,hsts>>
* <<nsa-xss-protection,xss-protection>>
@@ -7155,6 +7221,74 @@ The RequestMatcher instance to be used to determine if the header should be set.
[[nsa-hpkp]]
==== <hpkp>
When enabled adds the https://tools.ietf.org/html/rfc7469[Public Key Pinning Extension for HTTP] header to the response for any secure request. This allows HTTPS websites to resist impersonation by attackers using mis-issued or otherwise fraudulent certificates.
[[nsa-hpkp-attributes]]
===== <hpkp> Attributes
[[nsa-hpkp-disabled]]
* **disabled**
Specifies if HTTP Public Key Pinning (HPKP) should be disabled. Default true.
[[nsa-hpkp-include-subdomains]]
* **include-sub-domains**
Specifies if subdomains should be included. Default false.
[[nsa-hpkp-max-age-seconds]]
* **max-age-seconds**
Sets the value for the max-age directive of the Public-Key-Pins header. Default 60 days.
[[nsa-hpkp-report-only]]
* **report-only**
Specifies if the browser should only report pin validation failures. Default true.
[[nsa-hpkp-report-uri]]
* **report-uri**
Specifies the URI to which the browser should report pin validation failures.
[[nsa-hpkp-parents]]
===== Parent Elements of <hpkp>
* <<nsa-headers,headers>>
[[nsa-pins]]
==== <pins>
The list of pins
[[nsa-pins-children]]
===== Child Elements of <pins>
* <<nsa-pin,pin>>
[[nsa-pin]]
==== <pin>
A pin is specified using the base64-encoded SPKI fingerprint as value and the cryptographic hash algorithm as attribute
[[nsa-pin-attributes]]
===== <pin> Attributes
[[nsa-pin-algorithm]]
* **algorithm**
The cryptographic hash algorithm. Default is SHA256.
[[nsa-pin-parents]]
===== Parent Elements of <pin>
* <<nsa-pins,pins>>
[[nsa-frame-options]]
==== <frame-options>
When enabled adds the http://tools.ietf.org/html/draft-ietf-websec-x-frame-options[X-Frame-Options header] to the response, this allows newer browsers to do some security checks and prevent http://en.wikipedia.org/wiki/Clickjacking[clickjacking] attacks.