1 files changed, 132 insertions, 0 deletions

diff --git a/doc/source/encryption.rst b/doc/source/encryption.rst
new file mode 100644
index 0000000..8ac6861
--- /dev/null
+++ b/doc/source/encryption.rst
@@ -0,0 +1,132 @@
+.. _cookie-encryption-config:
+
+Cookies
+=======
+
+auto_cookie_secure
+""""""""""""""""""
+ 
+:ref:`auto_cookie_secure <auto-cookie-secure-feature>`, disabled by default,
+will automatically mark cookies as `secure
+<https://en.wikipedia.org/wiki/HTTP_cookie#Secure_cookie>`_ when the web page
+is requested over HTTPS.
+
+It can either be ``enabled`` or ``disabled``.
+
+::
+
+  sp.auto_cookie_secure.enable();
+  sp.auto_cookie_secure.disable();
+
+cookie_samesite
+"""""""""""""""
+ 
+:ref:`samesite <samesite-feature>`, disabled by default, will add the `samesite
+<https://tools.ietf.org/html/draft-west-first-party-cookies-07>`_ attribute to
+cookies. It `prevents CSRF <https://www.owasp.org/index.php/SameSite>`_ but is
+not implemented by `all web browsers <https://caniuse.com/#search=samesite>`_
+yet.
+
+It can either be set to ``strict`` or ``lax``:
+
+- The ``lax`` attribute prevents cookies from being sent cross-domain for
+  "dangerous" methods, like ``POST``, ``PUT`` or ``DELETE``.
+
+- The ``strict`` one prevents any cookies from beind sent cross-domain.
+
+::
+
+  sp.cookie.name("cookie1").samesite("lax");
+  sp.cookie.name("cookie2").samesite("strict");;
+
+.. _cookie-encryption_config:
+
+Cookie encryption
+"""""""""""""""""
+   
+The encryption is done via the `tweetnacl library <https://tweetnacl.cr.yp.to/>`_,
+thus using `curve25519<https://en.wikipedia.org/wiki/Curve25519>`__, `xsalsa20 <https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant>`__ and `poly1305 <https://en.wikipedia.org/wiki/Poly1305>`__ for the encryption. We chose this
+library because of its portability, simplicity and reduced size (a single `.h` and
+`.c` file.).
+
+The key is derived from multiple sources, such as :
+ * The ``secret_key`` provided in the configuration.
+ * An environment variable, such as the ``REMOTE_ADDR`` (remote IP address) or the *extended master secret* from TLS connections (`RFC7627 <https://tools.ietf.org/html/rfc7627>`_)
+ * The user-agent.
+
+
+.. warning::
+
+  To use this feature, you **must** set the :ref:`global.secret_key <config_global>`
+  and the :ref:`global.cookie_env_var <config_global>` variables.
+  This design decision prevents an attacker from
+  `trivially bruteforcing <https://www.idontplaydarts.com/2011/11/decrypting-suhosin-sessions-and-cookies/>`_
+  or re-using session cookies.
+  If the simulation mode isn’t specified in the configuration, snuffleupagus will drop any request that it was unable to decrypt.
+
+Since PHP doesn't handle session cookie and non-session cookie in the same way,
+thus we are providing two different options:
+
+ * For the session cookie, the encryption happens server-side: The cookie's value isn't encrypted, only the session content is.
+ * For the non-session cookie, the value is encrypted.
+
+Session cookie
+..............
+
+:ref:`Session encryption <cookie-encryption-feature>`, disabled by default, will activate transparent session encryption.
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
+
+::
+
+  sp.session.encrypt();
+  sp.session.simulation();
+
+
+Non-session cookie
+..................
+
+:ref:`Cookie encryption <cookie-encryption-feature>`, disabled by default, will activate transparent encryption of specific cookies.
+
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
+
+::
+
+  sp.cookie.name("my_cookie_name").encrypt();
+  sp.cookie.name("another_cookie_name").encrypt();
+
+
+Removing the user-agent part
+............................
+
+Some web browser extensions, such as `uMatrix <https://github.com/gorhill/uMatrix/wiki>`__
+might be configured to change the user-agent on a regular basis. If you think that
+some of your users might be using configurations like this, you might want to disable
+the mixing of the user-agent in the cookie's encryption key. The simplest way to do
+so is to set the environment variable ``HTTP_USER_AGENT`` to a fixed value before passing
+it to your php process.
+
+We think that this use case is too exotic to be worth implementing as a
+proper configuration directive.
+
+.. _env-var-config:
+
+Choosing the proper environment variable
+........................................
+
+It's up to you to choose a meaningful environment variable to derive the key from.
+Suhosin `is using <https://www.suhosin.org/stories/configuration.html#suhosin-session-cryptraddr>`_
+the ``REMOTE_ADDR`` one, tying the validity of the cookie to the IP address of the user;
+unfortunately, nowadays, people are `roaming <https://en.wikipedia.org/wiki/Roaming>`_ a lot on their smartphone,
+hopping from WiFi to 4G.
+
+This is why we recommend, if possible, to use the *extended master secret*
+from TLS connections (`RFC7627 <https://tools.ietf.org/html/rfc7627>`_)
+instead. The will make the validity of the cookie TLS-dependent, by using the ``SSL_SESSION_ID`` variable.
+
+- In `Apache <https://httpd.apache.org/docs/current/mod/mod_ssl.html>`_,
+  it is possible to enable by adding ``SSLOptions StdEnvVars`` in your Apache2 configuration.
+- In `nginx <https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables>`_,
+  you have to use ``fastcgi_param SSL_SESSION_ID $ssl_session_id if_not_empty;``.
+
+If you aren't using TLS (you should be), you can always use the ``REMOTE_ADDR`` one,
+or ``X-Real-IP`` if you're behind a reverse proxy.