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. 135