Browse Source

clean up security header docs

[ci skip]
pull/2340/head
David Lord 8 years ago
parent
commit
8eff9bda3d
No known key found for this signature in database
GPG Key ID: 7A1C87E3F5BC42A8
  1. 121
      docs/security.rst

121
docs/security.rst

@ -108,90 +108,101 @@ arrays.
Security Headers
----------------
This section contains a list of HTTP security headers supported by Flask.
To configure HTTPS and handle the headers listed below we suggest the package `flask-talisman <https://github.com/GoogleCloudPlatform/flask-talisman>`_.
Browsers recognize various response headers in order to control security. We
recommend reviewing each of the headers below for use in your application.
The `Flask-Talisman`_ extension can be used to manage HTTPS and the security
headers for you.
HTTP Strict Transport Security (HSTS)
-------------------------------------
Redirects HTTP requests to HTTPS on all URLs, preventing man-in-the-middle (MITM) attacks.
Example:
.. _Flask-Talisman: https://github.com/GoogleCloudPlatform/flask-talisman
.. sourcecode:: none
Strict-Transport-Security: max-age=<expire-time
Strict-Transport-Security: max-age=<expire-time>; includeSubDomains
Strict-Transport-Security: max-age=<expire-time>; preload
See also `Strict Transport Security <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_.
HTTP Strict Transport Security (HSTS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HTTP Public Key Pinning (HPKP)
------------------------------
Tells the browser to convert all HTTP requests to HTTPS, preventing
man-in-the-middle (MITM) attacks. ::
This enables your web server to authenticate with a client browser using a specific certificate key to prevent man-in-the-middle (MITM) attacks.
response.haders['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains'
Example:
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
.. sourcecode:: none
Content Security Policy (CSP)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubDomains][; report-uri="reportURI"]
Tell the browser where it can load various types of resource from. This header
should be used whenever possible, but requires some work to define the correct
policy for your site. A very strict policy would be::
See also `Public Key Pinning <https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning>`_.
response.headers['Content-Security-Policy'] = "default-src: 'self'"
X-Frame-Options (Clickjacking Protection)
-----------------------------------------
- https://csp.withgoogle.com/docs/index.html
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
Prevents the client from clicking page elements outside of the website, avoiding hijacking or UI redress attacks.
X-Content-Type-Options
~~~~~~~~~~~~~~~~~~~~~~
.. sourcecode:: none
Forces the browser to honor the response content type instead of trying to
detect it, which can be abused to generate a cross-site scripting (XSS)
attack. ::
X-Frame-Options: DENY
X-Frame-Options: SAMEORIGIN
X-Frame-Options: ALLOW-FROM https://example.com/
response.headers['X-Content-Type-Options'] = 'nosniff'
See also `X-Frame-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options>`_.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
X-Content-Type-Options
----------------------
X-Frame-Options
~~~~~~~~~~~~~~~
This header prevents Cross-site scripting (XSS) by blocking requests on clients and forcing them to first read and validate the content-type before reading any of the contents of the request.
Prevents external sites from embedding your site in an ``iframe``. This
prevents a class of attacks where clicks in the outer frame can be translated
invisibly to clicks on your page's elements. This is also known as
"clickjacking". ::
.. sourcecode:: none
response.headers['X-Frame-Options'] = 'SAMEORIGIN'
X-Content-Type-Options: nosniff
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
See also `X-Content-Type-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options>`_.
X-XSS-Protection
~~~~~~~~~~~~~~~~
Content Security Policy (CSP)
-----------------------------
The browser will try to prevent reflected XSS attacks by not loading the page
if the request contains something that looks like JavaScript and the response
contains the same data. ::
Enhances security and prevents common web vulnerabilities such as cross-site scripting (XSS) and man-in-the-middle (MITM) related attacks.
response.headers['X-XSS-Protection'] = '1; mode=block'
Example:
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
.. sourcecode:: none
Set-Cookie options
~~~~~~~~~~~~~~~~~~
Content-Security-Policy: default-src https:; script-src 'nonce-{random}'; object-src 'none'
These options can be added to a ``Set-Cookie`` header to improve their
security. Flask has configuration options to set these on the session cookie.
They can be set on other cookies too.
See also `Content Security Policy <https://csp.withgoogle.com/docs/index.html>`_.
- ``Secure`` limits cookies to HTTPS traffic only.
- ``HttpOnly`` protects the contents of cookies from being read with
JavaScript.
- ``SameSite`` ensures that cookies can only be requested from the same
domain that created them. It is not supported by Flask yet.
Cookie Options
--------------
::
While these headers are not directly security related, they have important options that may affect your Flask application.
app.config.update(
SESSION_COOKIE_SECURE=True,
SESSION_COOKIE_HTTPONLY=True,
)
- ``Secure`` limits your cookies to HTTPS traffic only.
- ``HttpOnly`` protects the contents of your cookie from being visible to XSS.
- ``SameSite`` ensures that cookies can only be requested from the same domain that created them but this feature is not yet fully supported across all browsers.
response.set_cookie('username', 'flask', secure=True, httponly=True)
Example:
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies
.. sourcecode:: none
HTTP Public Key Pinning (HPKP)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set-Cookie: [cookie-name]=[cookie-value]
This tells the browser to authenticate with the server using only the specific
certificate key to prevent MITM attacks.
See also:
.. warning::
Be careful when enabling this, as it is very difficult to undo if you set up
or upgrade your key incorrectly.
- Mozilla guide to `HTTP cookies <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies>`_.
- `OWASP HTTP Only <https://www.owasp.org/index.php/HttpOnly>`_.
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning

Loading…
Cancel
Save