From cc72d0659cd7f591cce779a4afda775bb8518242 Mon Sep 17 00:00:00 2001 From: jvoisin Date: Wed, 9 Jan 2019 20:55:25 +0100 Subject: Rename a documentation file --- doc/source/encryption.rst | 142 ---------------------------------------------- 1 file changed, 142 deletions(-) delete mode 100644 doc/source/encryption.rst (limited to 'doc/source/encryption.rst') diff --git a/doc/source/encryption.rst b/doc/source/encryption.rst deleted file mode 100644 index 856927d..0000000 --- a/doc/source/encryption.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _cookie-encryption-page: - -Cookies -======= - -Some cookies-related features might prevent other extensions from hooking -the `setcookie `__ -function. Pay attention to the loading order of your extensions in this case. - -auto_cookie_secure -"""""""""""""""""" - -:ref:`auto_cookie_secure `, disabled by default, -will automatically mark cookies as `secure -`_ 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 `, disabled by default, will add the `samesite -`_ attribute to -cookies. It `prevents CSRF `_ but is -not implemented by `all web browsers `_ -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 -""""""""""""""""" - -The encryption is done via the `tweetnacl library `_, -thus using `curve25519 `__, `xsalsa20 `__ and `poly1305 `__ for the encryption. We chose this -library because of its portability, license (public-domain), 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 in the ``sp.global.secret_key`` - option. It's recommended to use something like ``head -c 256 /dev/urandom | tr -dc - 'a-zA-Z0-9'`` as a value. - * An optional environment variable, such as ``REMOTE_ADDR`` (remote IP address) or the *extended master secret* from TLS connections (`RFC7627 `_) in the ``sp.global.cookie_env_var`` option. - * The `user-agent `__. - - -.. warning:: - - To use this feature, you **must** set the :ref:`global.secret_key ` variable - and **should** set the :ref:`global.cookie_env_var ` one too. - This design decision prevents an attacker from - `trivially bruteforcing `_ - 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, -so does Snuffleupagus. - - -Session cookie -.............. - -For the session cookie, the encryption happens server-side: Nothing is -encrypted in the cookie: neither the cookie's name (usually ``PHPSESSID``) nor -its content (the session's name). What is in fact encrypted, is the session's -content, on the server (usually stored in ``/tmp/sess_`` files). - -:ref:`Session encryption `, 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 -.................. - -For the non-session cookie, the cookie's name is left untouched, only its value is encrypted. - -:ref:`Cookie encryption `, 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 `__ -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 `_ -the ``REMOTE_ADDR`` one, tying the validity of the cookie to the IP address of the user; -unfortunately, nowadays, people are `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 `_) -instead. The will make the validity of the cookie TLS-dependent, by using the ``SSL_SESSION_ID`` variable. - -- In `Apache `_, - it is possible to enable by adding ``SSLOptions StdEnvVars`` in your Apache2 configuration. -- In `nginx `_, - 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. -- cgit v1.3