docs/HTTP-COOKIES

   1 Updated: July 3, 2012 (https://curl.haxx.se/docs/http-cookies.html)
   2                                   _   _ ____  _
   3                               ___| | | |  _ \| |
   4                              / __| | | | |_) | |
   5                             | (__| |_| |  _ <| |___
   6                              \___|\___/|_| \_\_____|
   7
   8
   9 HTTP 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
  20 1. 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: https://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.