PHP: rfc:same-site-cookie

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Same Site Cookie ======
  * Version: 0.9
  * Date: 2017-07-16
  * Author of RFC and creator of PR: Frederik Bosch, f.bosch@genkgo.nl
  * Author of original patch: xistence at 0x90 dot nl
  * Status: Implemented (PHP 7.3 via commit [[https://github.com/php/php-src/commit/08b9310|08b9310]] and [[https://github.com/php/php-src/commit/2b58ab2|2b58ab2]].)
  * First Published at: https://wiki.php.net/rfc/same-site-cookie

===== Introduction =====
Same-site cookies allow servers to mitigate the risk of CSRF and information leakage attacks by asserting that a particular cookie should only be sent with requests initiated from the same registrable domain. The technology is currently [[https://tools.ietf.org/html/draft-west-first-party-cookies-07|a proposed web standard]]. However, same site cookies are already  adopted by Chrome and planned by [[https://caniuse.com/#search=samesite|planned by Firefox]]. Major PHP frameworks already implemented this through a custom Set-Cookie header call. The RFC will try to convince voters that same site cookies should be available as a core language feature.

===== How the samesite flag works =====

Cookies are issued using the Set-Cookie header. When issuing a cookie, one can set a key and value together with flags for the browser to determine whether the cookie should be accessible. A typical cookie might look like this.

<code>
Set-Cookie: key=value; path=/; domain=example.org; HttpOnly
</code>

As many will know, this opens doors for CSRF attacks, an attack that forces an end user to execute unwanted actions on a web application in which they're currently authenticated. Authentication state is saved through the use of (session) cookies. The cookie is the key for having access to the application. When using samesite, the developer can specify if and when the cookie should be accessible when a request originates from another registrable domain.

According to the proposed standard, there are now two possibilities for a cookie that is using the samesite flag: "Lax" and "Strict". The difference between Lax and Strict is the accessibility of the cookie in requests originating from another registrable domain using the HTTP GET method. Cookies using Lax will be accessible in a **GET** request originated from another registrable domain, whereas cookies using Strict will not be accessible in a GET request originated from another registrable domain. There is no difference with POST methods: the browser should not allow the cookie to be accessed in a POST request originating from another registrable domain.

A cookie that is issued using the samesite flag, might look as follows.

<code>
Set-Cookie: key=value; path=/; domain=example.org; HttpOnly; SameSite=Lax
</code>

===== Proposal =====

In order to add this <php>samesite</php> flag when issuing cookies, four core functions will be affected by this RFC.

  - setcookie
  - setrawcookie
  - session_set_cookie_params
  - session_get_cookie_params

The first three functions have a similar function signature. This RFC proposes two possibilities to change these three functions. The first possibility is to add an additional argument to these functions. The second possibility is to allow an array of options in which all the cookie options will be moved into.

When voting, one can decide to (a) accept/reject the RFC via the additional argument (b) accept/reject the RFC via the array of options solution.


==== setcookie ====
1. Add an additional <php>samesite</php> argument to the setcookie function.

<code php>
bool setcookie ( string $name [, string $value = "" [, int $expire = 0 [, string $path = "" [, string $domain = "" [, bool $secure = false [, bool $httponly = false [, string $samesite = "" ]]]]]]] )
</code>

2. Modify setcookie as such that the function also allows an array of options. The keys within $options that have affect to the Set-Cookie header are: path, domain, secure, httponly and samesite. The default values for these options will remain untouched. The default value for samesite will be the empty string.

<code php>
bool setcookie ( string $name [, string $value = "" [, int $expire = 0 [, string $path = "" [, string $domain = "" [, bool $secure = false [, bool $httponly = false]]]]]] )
bool setcookie ( string $name [, string $value = "" [, int $expire = 0 [, array $options ]]] )
</code>

==== setrawcookie ====
1. Add an additional <php>samesite</php> argument to the setrawcookie function.

<code php>
bool setrawcookie ( string $name [, string $value [, int $expire = 0 [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false [, string $samesite = "" ] ]]]]]] )
</code>

2. Modify setrawcookie as such that the function also allows an array of options. The keys within $options that have affect to the Set-Cookie header are: path, domain, secure, httponly and samesite. The default values for these options will remain untouched. The default value for samesite will be the empty string.

<code php>
bool setrawcookie ( string $name [, string $value = "" [, int $expire = 0 [, string $path = "" [, string $domain = "" [, bool $secure = false [, bool $httponly = false]]]]]] )
bool setrawcookie ( string $name [, string $value = "" [, int $expire = 0 [, array $options ]]] )
</code>

==== session_set_cookie_params ====
1. Add an additional <php>samesite</php> argument to the session_set_cookie_param function.

<code php>
void session_set_cookie_params ( int $lifetime [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false [, string $samesite = "" ]]]]] )
</code>

2. Modify session_set_cookie_param as such that the function also allows an array of options. The keys within $options that have affect to the Set-Cookie header are: path, domain, secure, httponly and samesite. The default values for these options will remain untouched. The default value for samesite will be the empty string.

<code php>
void session_set_cookie_params ( int $lifetime [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false ]]]] )
void session_set_cookie_params ( int $lifetime [, array $options ] )
</code>

==== session_get_cookie_params ====
The return value of the session_get_cookie_params function will have an extra key <php>samesite</php> in the returned array.

<code php>
array(
  "lifetime" => 0,             // The lifetime of the cookie in seconds.
  "path" => "/",               // The path where information is stored.
  "domain" => "example.org",   // The domain of the cookie.
  "secure" => true,            // The cookie should only be sent over secure connections.
  "httponly" => true,          // The cookie can only be accessed through the HTTP protocol.
  "samesite" => "Strict"       // The cookie can only be accessed if it was initiated from the same registrable domain.
)
</code>

===== Pros and cons: why or why not to adopt this RFC =====
The first and foremost reasons to accept this RFC is that developers will be able to better secure their PHP applications. It fits the step PHP is already making with the upcoming availability of libsodium. With this feature, the language would make another step in helping developers to write secure code.

But, there is a risk involved when using samesite //as additional argument// to setcookie, setrawcookie and session_set_cookie_params. The samesite cookie might not become a standard which might lead browsers to eventually drop the flag. If that would be the case, the <php>setcookie</php>, <php>setrawcookie</php> and <php>session_set_cookie_params</php> functions would have a useless samesite argument. For the record, the HttpOnly flag became a standard in 2011. The argument to set(raw)cookie function was already added with PHP 5.2.0 in November 2006, almost 5 years ahead of the standard.

Furthermore, I should point out that the setcookie, setrawcookie and session_set_cookie_params functions are becoming lengthy functions when another parameter will be added. But one can argue that this is the //result of the design of the function itself//. To overcome this, there are two options. One is the proposed array syntax for the three mentioned functions. The other is to define a new function with a better API. There is already someone [[https://externals.io/message/99885|working on this proposal via http_cookie_set and http_cookie_remove]].

The author believes strongly that the pros weigh up to the cons. At this moment more than 50% of the global used browsers support the samesite flag. And another major browser is already working on it, being Firefox. How many PHP installations could we make more secure? We should add samesite to the core of PHP. The only question is: "What is the best route to take?". Since the additional argument solution comes with the two downsides mentioned in the two paragraphs above, the author advice would be to allow an array of options to the setcookie, setrawcookie  and session_set_cookie_params functions.


===== Backward Incompatible Changes =====
There are no backward incompatible changes.

===== Proposed PHP Version(s) =====
Next PHP 7.x. Since deadlines have passed for 7.2, this will be 7.3.

===== RFC Impact =====

==== php.ini defaults ====
The following ini values will be added.

  * session.cookie_samesite

The default value is the empty string in both default development and production php.ini.

===== Future Scope =====
When this RFC will be rejected, it could mean that the current cookie functions should be left untouched and that PHP needs new functions for cookies with a better API.

===== Proposed Voting Choices =====
This RFC requires a 50%+1 majority. If both questions pass, only the one with most votes will be implemented.


=== First implementation suggestion ===


<doodle title="Add samesite argument to setcookie, setrawcookie and session_set_cookie_params functions?" auth="f.bosch@genkgo.nl" voteType="single" closed="true">
   * Yes
   * No
</doodle>

=== Second implementation suggestion ===

<doodle title="Allow setcookie, setrawcookie and session_set_cookie_params to accept an array of options as fourth/second parameter, with the possible options being path, domain, secure, httponly and samesite?" auth="f.bosch@genkgo.nl" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
  * [[https://github.com/php/php-src/pull/2613|Github PR #2613 containing the additional argument solution]]
  * Github PR with the array of options solution will be created when this RFC gets accepted
  * Implemented via [[https://github.com/php/php-src/commit/08b9310]] and [[https://github.com/php/php-src/commit/2b58ab2]]
  * Documented via [[https://github.com/php/doc-en/commit/ffe8f84ec5ec175a2b8ddf23a569d4e621866d76]]

===== References =====
  * [[https://bugs.php.net/bug.php?id=72230|PHP BUG #72230 Add SameSite Cookies to setcookie()]]
  * [[https://tools.ietf.org/html/draft-west-first-party-cookies-07|Proposal of SameSite cookie as standard]]
  * [[https://scotthelme.co.uk/csrf-is-dead/|CSRF is dead]]
  * [[https://caniuse.com/#search=samesite|browsers that implement SameSite cookie]]

===== Errata =====

The actually implemented alternative signatures of the functions have been slightly changed from the original RFC. See the documentation in the PHP manual for details: 
  * [[http://php.net/manual/en/function.setcookie.php|setcookie()]]
  * [[http://php.net/manual/en/function.setrawcookie.php|setrawcookie()]]
  * [[http://php.net/manual/en/function.session-set-cookie-params.php|session_set_cookie_params()]]
Page Tools
