From 7832438b7abedf567ce6376f99949f419abcdff1 Mon Sep 17 00:00:00 2001 From: kkadosh Date: Tue, 29 May 2018 19:34:16 +0000 Subject: Support session encryption Implement session encryption.--- doc/source/config.rst | 100 ++--------------------------------- doc/source/encryption.rst | 132 ++++++++++++++++++++++++++++++++++++++++++++++ doc/source/features.rst | 9 ++-- doc/source/index.rst | 1 + 4 files changed, 139 insertions(+), 103 deletions(-) create mode 100644 doc/source/encryption.rst (limited to 'doc/source') diff --git a/doc/source/config.rst b/doc/source/config.rst index d8389b6..b5bcad4 100644 --- a/doc/source/config.rst +++ b/doc/source/config.rst @@ -68,7 +68,7 @@ This configuration variable contains parameters that are used by multiple featur sp.global.secret_key("44239bd400aa82e125337c9d4eb8315767411ccd"); - ``cookie_env_var``: A environment variable used as part of cookies encryption. - See the :ref:`relevant documentation `. + See the :ref:`relevant documentation ` Bugclass-killer features ------------------------ @@ -123,103 +123,9 @@ It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` m Cookies-related mitigations ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. warning:: - Those features are **not** available for session cookies `yet `_. - -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_config: - -cookie_encryption -""""""""""""""""" - -.. warning:: - - To use this feature, you **must** set the :ref:`global.secret_key ` - and the :ref:`global.cookie_env_var ` variables. - This design decision prevents an attacker from - `trivially bruteforcing `_ - or re-using session cookies. - -:ref:`cookie_secure `, 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;``. +Since snuffleupagus is providing several hardening features for cookies, +there is a :dedicated web page:`here ` about them. -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. readonly_exec ^^^^^^^^^^^^^ 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 `, 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_config: + +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, 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 `_) + * The user-agent. + + +.. warning:: + + To use this feature, you **must** set the :ref:`global.secret_key ` + and the :ref:`global.cookie_env_var ` variables. + 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, +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 `, 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 `, 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/features.rst b/doc/source/features.rst index 24c5074..08ad3d4 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -63,8 +63,8 @@ Examples of related vulnerabilities .. _cookie-encryption-feature: -Session-cookie stealing via XSS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Cookie stealing via XSS +^^^^^^^^^^^^^^^^^^^^^^^ The goto payload for XSS is often to steal cookies. Like *Suhosin*, we are encrypting the cookies with a secret key, @@ -79,10 +79,7 @@ This feature is roughly the same than the `Suhosin one `_, -thus using curve25519, xsalsa20 and poly1305 for the encryption. We chose this -library because of its portability, simplicity and reduced size (a single `.h` and -`.c` file.). + .. _fileupload-feature: diff --git a/doc/source/index.rst b/doc/source/index.rst index 28d0474..22cdcb8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,6 +19,7 @@ Documentation changelog faq papers + encryption Greetings --------- -- cgit v1.3