From 09a0d2ebd1c832977b46be6d0cbd7b42944ffc49 Mon Sep 17 00:00:00 2001
From: Lowell Abbott <lowell.abbott@gmail.com>
Date: Tue, 23 May 2017 12:26:43 -0700
Subject: [PATCH] Re-order by semantic. Fix link on flask-talismand and re-word
 many concepts

---
 docs/security.rst | 59 ++++++++++++++++++++++++++---------------------
 1 file changed, 33 insertions(+), 26 deletions(-)

diff --git a/docs/security.rst b/docs/security.rst
index 120600cc..59767139 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -109,37 +109,37 @@ Security Headers
 ----------------
 
 This section contains a list of 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>`. 
+To configure HTTPS and handle the headers listed below we suggest the package `flask-talisman <https://github.com/GoogleCloudPlatform/flask-talisman>`_. 
 
-Content Security Policy (CSP)
------------------------------
+HTTP Strict Transport Security (HSTS)
+-------------------------------------
 
-Enhance security and prevents common web vulnerabilities such as cross-site scripting and MITM related attacks.
+Redirects http requests to https on all urls, preventing Man-in-the-middle (MITM) attacks.
 
 Example:
 
 .. sourcecode:: none
    
-   Content-Security-Policy: default-src https:; script-src 'nonce-{random}'; object-src '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 `Content Security Policy <https://csp.withgoogle.com/docs/index.html>`_.
+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)
+------------------------------
 
-Redirects http requests to https on all urls, preventing 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.
 
 Example:
 
 .. 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>`_. 
+   Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubDomains][; report-uri="reportURI"] 
+
+See also `Public Key Pinning <https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning>`_.
 
-X-FRAME-OPTIONS (Clickjacking protection)
+X-Frame-Options (Clickjacking protection)
 -----------------------------------------
 
 Prevents the client from clicking page elements outside of the website, avoiding hijacking or UI redress attacks.
@@ -155,7 +155,7 @@ See also `X-Frame-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/Hea
 X-Content-Type-Options
 ----------------------
 
-Prevents XSS by blocking requests on clients and forcing them to read the content type instead of first opening it.
+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.
 
 .. sourcecode:: none
    
@@ -163,28 +163,35 @@ Prevents XSS by blocking requests on clients and forcing them to read the conten
 
 See also `X-Content-Type-Options <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options>`_. 
 
-Cookie options
---------------
+Content Security Policy (CSP)
+-----------------------------
 
-For setting cookies on client-side storage.
+Enhances security and prevents common web vulnerabilities such as cross-site scripting (XSS) and Man-in-the-middle (MITM) related attacks.
 
 Example:
 
 .. sourcecode:: none
    
-   Set-Cookie: [cookie-name]=[cookie-value] 
+   Content-Security-Policy: default-src https:; script-src 'nonce-{random}'; object-src 'none'
 
-See also `HTTP cookies <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies>`_ .
+See also `Content Security Policy <https://csp.withgoogle.com/docs/index.html>`_.
 
-HTTP Public Key Pinning (HPKP)
-------------------------------
+Cookie options
+--------------
+
+While these headers are not directly security related, they have important options that may affect your flask application.
 
-For associating clients with web servers through a certificate key and prevent MITM attacks.
+- ``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.  
 
 Example:
 
 .. sourcecode:: none
+   
+   Set-Cookie: [cookie-name]=[cookie-value] 
 
-   Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubDomains][; report-uri="reportURI"] 
+See also:
 
-See also `Public Key Pinning <https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning>`_.
+-  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>`_.