diff options
Diffstat (limited to 'docs/en/cowboy/2.0/guide/cookies/index.html')
| -rw-r--r-- | docs/en/cowboy/2.0/guide/cookies/index.html | 135 |
1 files changed, 56 insertions, 79 deletions
diff --git a/docs/en/cowboy/2.0/guide/cookies/index.html b/docs/en/cowboy/2.0/guide/cookies/index.html index e4c982cc..0c957e61 100644 --- a/docs/en/cowboy/2.0/guide/cookies/index.html +++ b/docs/en/cowboy/2.0/guide/cookies/index.html @@ -71,108 +71,87 @@ <div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain
state on top of the stateless HTTP protocol.</p></div>
-<div class="paragraph"><p>Cowboy provides facilities for handling cookies. It is highly
-recommended to use them instead of writing your own, as the
-implementation of cookies can vary greatly between clients.</p></div>
+<div class="paragraph"><p>Cookies are a name/value store where the names and values are
+stored in plain text. They expire either after a delay
+or when the browser closes. They can be configured on a
+specific domain name or path, and restricted to secure
+resources (sent or downloaded over HTTPS), or restricted
+to the server (disallowing access from client-side scripts).</p></div>
+<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div>
<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent
request that matches the domain and path for which they were
-stored, including requests for static files. For this reason
-they can incur a cost which must be taken in consideration.</p></div>
-<div class="paragraph"><p>Also consider that, regardless of the options used, cookies
-are not to be trusted. They may be read and modified by any
-program on the user’s computer, but also by proxies. You
-should always validate cookie values before using them. Do
-not store any sensitive information in cookies either.</p></div>
-<div class="paragraph"><p>When explicitly setting the domain, the cookie will be sent
-for the domain and all subdomains from that domain. Otherwise
-the current domain will be used. The same is true for the
-path.</p></div>
-<div class="paragraph"><p>When the server sets cookies, they will only be available
-for requests that are sent after the client receives the
-response.</p></div>
-<div class="paragraph"><p>Cookies are sent in HTTP headers, therefore they must have
-text values. It is your responsibility to encode any other
-data type. Also note that cookie names are de facto case
-sensitive.</p></div>
-<div class="paragraph"><p>Cookies can be set for the client session (which generally
-means until the browser is closed), or it can be set for
-a number of seconds. Once it expires, or when the server
-says the cookie must exist for up to 0 seconds, the cookie
-is deleted by the client. To avoid this while the user
-is browsing your site, you should set the cookie for
-every request, essentially resetting the expiration time.</p></div>
-<div class="paragraph"><p>Cookies can be restricted to secure channels. This typically
-means that such a cookie will only be sent over HTTPS,
-and that it will only be available by client-side scripts
-that run from HTTPS webpages.</p></div>
-<div class="paragraph"><p>Finally, cookies can be restricted to HTTP and HTTPS requests,
-essentially disabling their access from client-side scripts.</p></div>
+stored, until they expire. This can create a non-negligible
+cost.</p></div>
+<div class="paragraph"><p>Cookies should not be considered secure. They are stored on
+the user’s computer in plain text, and can be read by any
+program. They can also be read by proxies when using clear
+connections. Always validate the value before using it,
+and never store any sensitive information inside it.</p></div>
+<div class="paragraph"><p>Cookies set by the server are only available in requests
+following the client reception of the response containing
+them.</p></div>
+<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to
+update the expiration time and avoid losing a cookie.</p></div>
<div class="sect1">
<h2 id="_setting_cookies">Setting cookies</h2>
<div class="sectionbody">
-<div class="paragraph"><p>By default, cookies you set are defined for the session.</p></div>
+<div class="paragraph"><p>By default cookies are defined for the duration of the session:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also make them expire at a specific point in the
-future.</p></div>
+<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>They can also be set for a duration in seconds:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [
- {<span style="color: #FF6600">max_age</span>, <span style="color: #993399">3600</span>}
-], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can delete cookies that have already been set. The value
-is ignored.</p></div>
+<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>, [
- {<span style="color: #FF6600">max_age</span>, <span style="color: #993399">0</span>}
-], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can restrict them to a specific domain and path.
-For example, the following cookie will be set for the domain
-<code>my.example.org</code> and all its subdomains, but only on the path
-<code>/account</code> and all its subdirectories.</p></div>
+<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
+<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options
+of the same name can be used:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, [
- {<span style="color: #FF6600">domain</span>, <span style="color: #FF0000">"my.example.org"</span>},
- {<span style="color: #FF6600">path</span>, <span style="color: #FF0000">"/account"</span>}
-], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can restrict the cookie to secure channels, typically HTTPS.</p></div>
+<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>,
+ #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>Cookies will be sent with requests to this domain and all
+its subdomains, and to resources on this path or deeper
+in the path hierarchy.</p></div>
+<div class="paragraph"><p>To restrict cookies to secure channels (typically resources
+available over HTTPS):</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [
- {<span style="color: #FF6600">secure</span>, <span style="color: #000080">true</span>}
-], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can restrict the cookie to client-server communication
-only. Such a cookie will not be available to client-side scripts.</p></div>
+<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req2</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, [
- {<span style="color: #FF6600">http_only</span>, <span style="color: #000080">true</span>}
-], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
+ #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Cookies may also be set client-side, for example using
Javascript.</p></div>
</div>
@@ -180,15 +159,12 @@ Javascript.</p></div> <div class="sect1">
<h2 id="_reading_cookies">Reading cookies</h2>
<div class="sectionbody">
-<div class="paragraph"><p>As we said, the client sends cookies with every request.
-But unlike the server, the client only sends the cookie
-name and value.</p></div>
-<div class="paragraph"><p>Cowboy provides two different ways to read cookies. You
-can either parse them as a list of key/value pairs, or
-match them into a map, optionally applying constraints
-to the values or providing a default if they are missing.</p></div>
-<div class="paragraph"><p>You can parse the cookies and then use standard library
-functions to access individual values.</p></div>
+<div class="paragraph"><p>The client only ever sends back the cookie name and value.
+All other options that can be set are never sent back.</p></div>
+<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both
+involve parsing the cookie header(s) and so should not
+be called repeatedly.</p></div>
+<div class="paragraph"><p>You can get all cookies as a key/value list:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
@@ -196,7 +172,10 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #009900">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>),
{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can match the cookies into a map.</p></div>
+<div class="paragraph"><p>Or you can perform a match against cookies and retrieve
+only the ones you need, while at the same time doing
+any required post processing using <a href="../constraints">constraints</a>.
+This function returns a map:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
@@ -206,8 +185,7 @@ http://www.gnu.org/software/src-highlite --> <div class="paragraph"><p>You can use constraints to validate the values while matching
them. The following snippet will crash if the <code>id</code> cookie is
not an integer number or if the <code>lang</code> cookie is empty. Additionally
-the <code>id</code> cookie value will be converted to an integer term, saving
-you a conversion step.</p></div>
+the <code>id</code> cookie value will be converted to an integer term:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
@@ -216,18 +194,17 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="color: #009900">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
<div class="paragraph"><p>Note that if two cookies share the same name, then the map value
will be a list of the two cookie values.</p></div>
-<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div>
<div class="paragraph"><p>A default value can be provided. The default will be used
if the <code>lang</code> cookie is not found. It will not be used if
-the cookie is found but has an empty value.</p></div>
+the cookie is found but has an empty value:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>#{<span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000"><<</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">>></span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If no default is provided and the value is missing, the
-query string is deemed invalid and the process will crash.</p></div>
+<div class="paragraph"><p>If no default is provided and the value is missing, an
+exception is thrown.</p></div>
</div>
</div>
|