| 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.haxx.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 web sites, you can |
| 133 |
record web browser HTTP traffic when using such a site and then repeat the |
| 134 |
cookie operations using curl or libcurl. |