xref: /curl/docs/HTTP-COOKIES.md (revision 86d33001)
1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3
4SPDX-License-Identifier: curl
5-->
6
7# HTTP Cookies
8
9## Cookie overview
10
11  Cookies are `name=contents` pairs that an HTTP server tells the client to
12  hold and then the client sends back those to the server on subsequent
13  requests to the same domains and paths for which the cookies were set.
14
15  Cookies are either "session cookies" which typically are forgotten when the
16  session is over which is often translated to equal when browser quits, or
17  the cookies are not session cookies they have expiration dates after which
18  the client throws them away.
19
20  Cookies are set to the client with the Set-Cookie: header and are sent to
21  servers with the Cookie: header.
22
23  For a long time, the only spec explaining how to use cookies was the
24  original [Netscape spec from 1994](https://curl.se/rfc/cookie_spec.html).
25
26  In 2011, [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt) was finally
27  published and details how cookies work within HTTP. In 2016, an update which
28  added support for prefixes was
29  [proposed](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-prefixes-00),
30  and in 2017, another update was
31  [drafted](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01)
32  to deprecate modification of 'secure' cookies from non-secure origins. Both
33  of these drafts have been incorporated into a proposal to
34  [replace](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-11)
35  RFC 6265. Cookie prefixes and secure cookie modification protection has been
36  implemented by curl.
37
38  curl considers `http://localhost` to be a *secure context*, meaning that it
39  allows and uses cookies marked with the `secure` keyword even when done over
40  plain HTTP for this host. curl does this to match how popular browsers work
41  with secure cookies.
42
43## Super cookies
44
45  A single cookie can be set for a domain that matches multiple hosts. Like if
46  set for `example.com` it gets sent to both `aa.example.com` as well as
47  `bb.example.com`.
48
49  A challenge with this concept is that there are certain domains for which
50  cookies should not be allowed at all, because they are *Public
51  Suffixes*. Similarly, a client never accepts cookies set directly for the
52  top-level domain like for example `.com`. Cookies set for *too broad*
53  domains are generally referred to as *super cookies*.
54
55  If curl is built with PSL (**Public Suffix List**) support, it detects and
56  discards cookies that are specified for such suffix domains that should not
57  be allowed to have cookies.
58
59  if curl is *not* built with PSL support, it has no ability to stop super
60  cookies.
61
62## Cookies saved to disk
63
64  Netscape once created a file format for storing cookies on disk so that they
65  would survive browser restarts. curl adopted that file format to allow
66  sharing the cookies with browsers, only to see browsers move away from that
67  format. Modern browsers no longer use it, while curl still does.
68
69  The Netscape cookie file format stores one cookie per physical line in the
70  file with a bunch of associated meta data, each field separated with
71  TAB. That file is called the cookie jar in curl terminology.
72
73  When libcurl saves a cookie jar, it creates a file header of its own in
74  which there is a URL mention that links to the web version of this document.
75
76## Cookie file format
77
78  The cookie file format is text based and stores one cookie per line. Lines
79  that start with `#` are treated as comments. An exception is lines that
80  start with `#HttpOnly_`, which is a prefix for cookies that have the
81  `HttpOnly` attribute set.
82
83  Each line that specifies a single cookie consists of seven text fields
84  separated with TAB characters. A valid line must end with a newline
85  character.
86
87### Fields in the file
88
89  Field number, what type and example data and the meaning of it:
90
91  0. string `example.com` - the domain name
92  1. boolean `FALSE` - include subdomains
93  2. string `/foobar/` - path
94  3. boolean `TRUE` - send/receive over HTTPS only
95  4. number `1462299217` - expires at - seconds since Jan 1st 1970, or 0
96  5. string `person` - name of the cookie
97  6. string `daniel` - value of the cookie
98
99## Cookies with curl the command line tool
100
101  curl has a full cookie "engine" built in. If you just activate it, you can
102  have curl receive and send cookies exactly as mandated in the specs.
103
104  Command line options:
105
106  `-b, --cookie`
107
108  tell curl a file to read cookies from and start the cookie engine, or if it
109  is not a file it passes on the given string. `-b name=var` works and so does
110  `-b cookiefile`.
111
112  `-j, --junk-session-cookies`
113
114  when used in combination with -b, it skips all "session cookies" on load so
115  as to appear to start a new cookie session.
116
117  `-c, --cookie-jar`
118
119  tell curl to start the cookie engine and write cookies to the given file
120  after the request(s)
121
122## Cookies with libcurl
123
124  libcurl offers several ways to enable and interface the cookie engine. These
125  options are the ones provided by the native API. libcurl bindings may offer
126  access to them using other means.
127
128  `CURLOPT_COOKIE`
129
130  Is used when you want to specify the exact contents of a cookie header to
131  send to the server.
132
133  `CURLOPT_COOKIEFILE`
134
135  Tell libcurl to activate the cookie engine, and to read the initial set of
136  cookies from the given file. Read-only.
137
138  `CURLOPT_COOKIEJAR`
139
140  Tell libcurl to activate the cookie engine, and when the easy handle is
141  closed save all known cookies to the given cookie jar file. Write-only.
142
143  `CURLOPT_COOKIELIST`
144
145  Provide detailed information about a single cookie to add to the internal
146  storage of cookies. Pass in the cookie as an HTTP header with all the
147  details set, or pass in a line from a Netscape cookie file. This option can
148  also be used to flush the cookies etc.
149
150  `CURLOPT_COOKIESESSION`
151
152  Tell libcurl to ignore all cookies it is about to load that are session
153  cookies.
154
155  `CURLINFO_COOKIELIST`
156
157  Extract cookie information from the internal cookie storage as a linked
158  list.
159
160## Cookies with JavaScript
161
162  These days a lot of the web is built up by JavaScript. The web browser loads
163  complete programs that render the page you see. These JavaScript programs
164  can also set and access cookies.
165
166  Since curl and libcurl are plain HTTP clients without any knowledge of or
167  capability to handle JavaScript, such cookies are not detected or used.
168
169  Often, if you want to mimic what a browser does on such websites, you can
170  record web browser HTTP traffic when using such a site and then repeat the
171  cookie operations using curl or libcurl.
172