Home | History | Annotate | Download | only in docs 
      1 Updated: July 3, 2012 (http://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: 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