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