1# HTTP Cookies
2
3## Cookie overview
4
5  Cookies are `name=contents` pairs that a HTTP server tells the client to
6  hold and then the client sends back those to the server on subsequent
7  requests to the same domains and paths for which the cookies were set.
8
9  Cookies are either "session cookies" which typically are forgotten when the
10  session is over which is often translated to equal when browser quits, or
11  the cookies aren't session cookies they have expiration dates after which
12  the client will throw them away.
13
14  Cookies are set to the client with the Set-Cookie: header and are sent to
15  servers with the Cookie: header.
16
17  For a very long time, the only spec explaining how to use cookies was the
18  original [Netscape spec from 1994](https://curl.se/rfc/cookie_spec.html).
19
20  In 2011, [RFC6265](https://www.ietf.org/rfc/rfc6265.txt) was finally
21  published and details how cookies work within HTTP. In 2016, an update which
22  added support for prefixes was
23  [proposed](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-prefixes-00),
24  and in 2017, another update was
25  [drafted](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-alone-01)
26  to deprecate modification of 'secure' cookies from non-secure origins. Both
27  of these drafts have been incorporated into a proposal to
28  [replace](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02)
29  RFC6265. Cookie prefixes and secure cookie modification protection has been
30  implemented by curl.
31
32## Cookies saved to disk
33
34  Netscape once created a file format for storing cookies on disk so that they
35  would survive browser restarts. curl adopted that file format to allow
36  sharing the cookies with browsers, only to see browsers move away from that
37  format. Modern browsers no longer use it, while curl still does.
38
39  The netscape cookie file format stores one cookie per physical line in the
40  file with a bunch of associated meta data, each field separated with
41  TAB. That file is called the cookiejar in curl terminology.
42
43  When libcurl saves a cookiejar, it creates a file header of its own in which
44  there is a URL mention that will link to the web version of this document.
45
46## Cookie file format
47
48  The cookie file format is text based and stores one cookie per line. Lines
49  that start with `#` are treated as comments.
50
51  Each line that each specifies a single cookie consists of seven text fields
52  separated with TAB characters. A valid line must end with a newline
53  character.
54
55### Fields in the file
56
57  Field number, what type and example data and the meaning of it:
58
59  0. string `example.com` - the domain name
60  1. boolean `FALSE` - include subdomains
61  2. string `/foobar/` - path
62  3. boolean `TRUE` - send/receive over HTTPS only
63  4. number `1462299217` - expires at - seconds since Jan 1st 1970, or 0
64  5. string `person` - name of the cookie
65  6. string `daniel` - value of the cookie
66
67## Cookies with curl the command line tool
68
69  curl has a full cookie "engine" built in. If you just activate it, you can
70  have curl receive and send cookies exactly as mandated in the specs.
71
72  Command line options:
73
74  `-b, --cookie`
75
76  tell curl a file to read cookies from and start the cookie engine, or if it
77  isn't a file it will pass on the given string. -b name=var works and so does
78  -b cookiefile.
79
80  `-j, --junk-session-cookies`
81
82  when used in combination with -b, it will skip all "session cookies" on load
83  so as to appear to start a new cookie session.
84
85  `-c, --cookie-jar`
86
87  tell curl to start the cookie engine and write cookies to the given file
88  after the request(s)
89
90## Cookies with libcurl
91
92  libcurl offers several ways to enable and interface the cookie engine. These
93  options are the ones provided by the native API. libcurl bindings may offer
94  access to them using other means.
95
96  `CURLOPT_COOKIE`
97
98  Is used when you want to specify the exact contents of a cookie header to
99  send to the server.
100
101  `CURLOPT_COOKIEFILE`
102
103  Tell libcurl to activate the cookie engine, and to read the initial set of
104  cookies from the given file. Read-only.
105
106  `CURLOPT_COOKIEJAR`
107
108  Tell libcurl to activate the cookie engine, and when the easy handle is
109  closed save all known cookies to the given cookiejar file. Write-only.
110
111  `CURLOPT_COOKIELIST`
112
113  Provide detailed information about a single cookie to add to the internal
114  storage of cookies. Pass in the cookie as a HTTP header with all the details
115  set, or pass in a line from a netscape cookie file. This option can also be
116  used to flush the cookies etc.
117
118  `CURLINFO_COOKIELIST`
119
120  Extract cookie information from the internal cookie storage as a linked
121  list.
122
123## Cookies with javascript
124
125  These days a lot of the web is built up by javascript. The webbrowser loads
126  complete programs that render the page you see. These javascript programs
127  can also set and access cookies.
128
129  Since curl and libcurl are plain HTTP clients without any knowledge of or
130  capability to handle javascript, such cookies will not be detected or used.
131
132  Often, if you want to mimic what a browser does on such websites, you can
133  record web browser HTTP traffic when using such a site and then repeat the
134  cookie operations using curl or libcurl.
135