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