Return to HTTP-COOKIES.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

Annotation of embedaddon/curl/docs/HTTP-COOKIES.md, revision 1.1

1.1     ! misho       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.