1Updated: July 3, 2012 (http://curl.haxx.se/docs/http-cookies.html)
2                                  _   _ ____  _
3                              ___| | | |  _ \| |
4                             / __| | | | |_) | |
5                            | (__| |_| |  _ <| |___
6                             \___|\___/|_| \_\_____|
7
8
9HTTP Cookies
10
11 1. HTTP Cookies
12 1.1 Cookie overview
13 1.2 Cookies saved to disk
14 1.3 Cookies with curl the command line tool
15 1.4 Cookies with libcurl
16 1.5 Cookies with javascript
17
18==============================================================================
19
201. HTTP Cookies
21
22  1.1 Cookie overview
23
24  HTTP cookies are pieces of 'name=contents' snippets that a server tells the
25  client to hold and then the client sends back those the server on subsequent
26  requests to the same domains/paths for which the cookies were set.
27
28  Cookies are either "session cookies" which typically are forgotten when the
29  session is over which is often translated to equal when browser quits, or
30  the cookies aren't session cookies they have expiration dates after which
31  the client will throw them away.
32
33  Cookies are set to the client with the Set-Cookie: header and are sent to
34  servers with the Cookie: header.
35
36  For a very long time, the only spec explaining how to use cookies was the
37  original Netscape spec from 1994: http://curl.haxx.se/rfc/cookie_spec.html
38
39  In 2011, RFC6265 (https://www.ietf.org/rfc/rfc6265.txt) was finally published
40  and details how cookies work within HTTP.
41
42  1.2 Cookies saved to disk
43
44  Netscape once created a file format for storing cookies on disk so that they
45  would survive browser restarts. curl adopted that file format to allow
46  sharing the cookies with browsers, only to see browsers move away from that
47  format. Modern browsers no longer use it, while curl still does.
48
49  The netscape cookie file format stores one cookie per physical line in the
50  file with a bunch of associated meta data, each field separated with
51  TAB. That file is called the cookiejar in curl terminology.
52
53  When libcurl saves a cookiejar, it creates a file header of its own in which
54  there is a URL mention that will link to the web version of this document.
55
56  1.3 Cookies with curl the command line tool
57
58  curl has a full cookie "engine" built in. If you just activate it, you can
59  have curl receive and send cookies exactly as mandated in the specs.
60
61  Command line options:
62
63  -b, --cookie
64
65    tell curl a file to read cookies from and start the cookie engine, or if
66    it isn't a file it will pass on the given string. -b name=var works and so
67    does -b cookiefile.
68
69  -j, --junk-session-cookies
70
71    when used in combination with -b, it will skip all "session cookies" on
72    load so as to appear to start a new cookie session.
73
74  -c, --cookie-jar
75
76    tell curl to start the cookie engine and write cookies to the given file
77    after the request(s)
78
79  1.4 Cookies with libcurl
80
81  libcurl offers several ways to enable and interface the cookie engine. These
82  options are the ones provided by the native API. libcurl bindings may offer
83  access to them using other means.
84
85  CURLOPT_COOKIE
86
87    Is used when you want to specify the exact contents of a cookie header to
88    send to the server.
89
90  CURLOPT_COOKIEFILE
91
92    Tell libcurl to activate the cookie engine, and to read the initial set of
93    cookies from the given file. Read-only.
94
95  CURLOPT_COOKIEJAR
96
97    Tell libcurl to activate the cookie engine, and when the easy handle is
98    closed save all known cookies to the given cookiejar file. Write-only.
99
100  CURLOPT_COOKIELIST
101
102    Provide detailed information about a single cookie to add to the internal
103    storage of cookies. Pass in the cookie as a HTTP header with all the
104    details set, or pass in a line from a netscape cookie file. This option
105    can also be used to flush the cookies etc.
106
107  CURLINFO_COOKIELIST
108
109    Extract cookie information from the internal cookie storage as a linked
110    list.
111
112  1.5 Cookies with javascript
113
114  These days a lot of the web is built up by javascript. The webbrowser loads
115  complete programs that render the page you see. These javascript programs
116  can also set and access cookies.
117
118  Since curl and libcurl are plain HTTP clients without any knowledge of or
119  capability to handle javascript, such cookies will not be detected or used.
120
121  Often, if you want to mimic what a browser does on such web sites, you can
122  record web browser HTTP traffic when using such a site and then repeat the
123  cookie operations using curl or libcurl.
124