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/cookies.rst | 142 ++++++++++++++++++++++++++++++++++++++++++++++ doc/source/encryption.rst | 142 ---------------------------------------------- doc/source/index.rst | 2 +- 3 files changed, 143 insertions(+), 143 deletions(-) create mode 100644 doc/source/cookies.rst delete mode 100644 doc/source/encryption.rst (limited to 'doc') diff --git a/doc/source/cookies.rst b/doc/source/cookies.rst new file mode 100644 index 0000000..856927d --- /dev/null +++ b/doc/source/cookies.rst @@ -0,0 +1,142 @@ +.. _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. 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 22cdcb8..955cebb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,7 +19,7 @@ Documentation changelog faq papers - encryption + cookies Greetings --------- -- cgit v1.3