| 1 |
= cow_cookie(3) |
| 2 |
|
| 3 |
== Name |
| 4 |
|
| 5 |
cow_cookie - Cookies |
| 6 |
|
| 7 |
== Description |
| 8 |
|
| 9 |
The module `cow_cookie` provides functions for parsing |
| 10 |
and manipulating cookie headers. |
| 11 |
|
| 12 |
== Exports |
| 13 |
|
| 14 |
* link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)] - Parse a cookie header |
| 15 |
* link:man:cow_cookie:parse_set_cookie(3)[cow_cookie:parse_set_cookie(3)] - Parse a set-cookie header |
| 16 |
* link:man:cow_cookie:cookie(3)[cow_cookie:cookie(3)] - Generate a cookie header |
| 17 |
* link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)] - Generate a set-cookie header |
| 18 |
|
| 19 |
== Types |
| 20 |
|
| 21 |
=== cookie_attrs() |
| 22 |
|
| 23 |
[source,erlang] |
| 24 |
---- |
| 25 |
cookie_attrs() :: #{ |
| 26 |
expires => calendar:datetime(), |
| 27 |
max_age => calendar:datetime(), |
| 28 |
domain => binary(), |
| 29 |
path => binary(), |
| 30 |
secure => true, |
| 31 |
http_only => true, |
| 32 |
same_site => default | none | strict | lax |
| 33 |
} |
| 34 |
---- |
| 35 |
|
| 36 |
Cookie attributes parsed from the set-cookie header. |
| 37 |
The attributes must be passed as-is to a cookie store |
| 38 |
engine for processing, along with the cookie name and value. |
| 39 |
More information about the attributes can be found in |
| 40 |
https://tools.ietf.org/html/rfc6265[RFC 6265]. |
| 41 |
|
| 42 |
=== cookie_opts() |
| 43 |
|
| 44 |
[source,erlang] |
| 45 |
---- |
| 46 |
cookie_opts() :: #{ |
| 47 |
domain => binary(), |
| 48 |
http_only => boolean(), |
| 49 |
max_age => non_neg_integer(), |
| 50 |
path => binary(), |
| 51 |
same_site => default | none | strict | lax, |
| 52 |
secure => boolean() |
| 53 |
} |
| 54 |
---- |
| 55 |
|
| 56 |
Options for the set-cookie header. They are added to the |
| 57 |
header as attributes. More information about the options |
| 58 |
can be found in https://tools.ietf.org/html/rfc6265[RFC 6265]. |
| 59 |
|
| 60 |
The following options are defined: |
| 61 |
|
| 62 |
domain:: |
| 63 |
|
| 64 |
Hosts to which the cookie will be sent. By default it will |
| 65 |
only be sent to the origin server. |
| 66 |
|
| 67 |
http_only:: |
| 68 |
|
| 69 |
Whether the cookie should be restricted to HTTP requests, or |
| 70 |
it should also be exposed to other APIs, for example Javascript. |
| 71 |
By default there are no restrictions. |
| 72 |
|
| 73 |
max_age:: |
| 74 |
|
| 75 |
Maximum lifetime of the cookie, in seconds. By default the |
| 76 |
cookie is kept for the duration of the session. |
| 77 |
|
| 78 |
path:: |
| 79 |
|
| 80 |
Path to which the cookie will be sent. By default it will |
| 81 |
be sent to the current "directory" of the effective request URI. |
| 82 |
|
| 83 |
same_site:: |
| 84 |
|
| 85 |
Whether the cookie should be sent along with cross-site |
| 86 |
requests. This attribute is currently non-standard but is in |
| 87 |
the process of being standardized. Please refer to the |
| 88 |
https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7[RFC 6265 (bis) draft] |
| 89 |
for details. |
| 90 |
+ |
| 91 |
The default value for this attribute may vary depending on |
| 92 |
user agent and configuration. Browsers are known to be more |
| 93 |
strict over TCP compared to TLS. |
| 94 |
|
| 95 |
secure:: |
| 96 |
|
| 97 |
Whether the cookie should be sent only on secure channels |
| 98 |
(for example TLS). Note that this does not guarantee the |
| 99 |
integrity of the cookie, only its confidentiality during |
| 100 |
transfer. By default there are no restrictions. |
| 101 |
|
| 102 |
== Changelog |
| 103 |
|
| 104 |
* *2.12*: The `same_site` attribute and option may now be |
| 105 |
set to `default`. |
| 106 |
* *2.10*: The `same_site` attribute and option may now be |
| 107 |
set to `none`. |
| 108 |
* *2.9*: The `cookie_attrs` type was added. |
| 109 |
* *1.0*: Module introduced. |
| 110 |
|
| 111 |
== See also |
| 112 |
|
| 113 |
link:man:cowlib(7)[cowlib(7)], |
| 114 |
https://tools.ietf.org/html/rfc6265[RFC 6265] |