From 33ee67112f3b9a0010a4ed92b3ee8321f2da969a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jul 2012 09:03:08 +0200 Subject: [PATCH] HTTP-COOKIES: added cookie documentation --- docs/HTTP-COOKIES | 104 ++++++++++++++++++++++++++++++++++++++++++++++ docs/Makefile.am | 4 +- 2 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 docs/HTTP-COOKIES diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES new file mode 100644 index 000000000..660c0b3d0 --- /dev/null +++ b/docs/HTTP-COOKIES @@ -0,0 +1,104 @@ + HTTP Cookies + +Overview +======== + +HTTP cookies are pieces of 'name=contents' snippets that a server tells the +client to hold and then the client sends back those the server on subsequent +requests to the same domains/paths for which the cookies were set. + +Cookies are either "session cookies" which typically are forgotten when the +session is over which is often translated to equal when browser quits, or the +cookies aren't session cookies they have expiration dates after which the +client will throw them away. + +Cookies are set to the client with the Set-Cookie: header and are sent to +servers with the Cookie: header. + +For a very long time, the only spec explaining how to use cookies was the +original Netscape spec from 1994: http://curl.haxx.se/rfc/cookie_spec.html + +In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published +and details how cookies work within HTTP. + +cookies saved to disk +===================== + +Netscape once created a file format for storing cookies on disk so that they +would survive browser restarts. curl adopted that file format to allow sharing +the cookies with browsers, only to see browsers move away from that +format. Modern browsers no longer use it, while curl still does. + +The cookie file format stores one cookie per physical line in the file with a +bunch of associated meta data, each field separated with TAB. That file is +called the cookiejar in curl terminology. + +cookies with curl the command line tool +======================================= + +curl has a full cookie "engine" built in. If you just activate it, you can +have curl receive and send cookies exactly as mandated in the specs. + +Command line options: + + -b, --cookie + + tell curl a file to read cookies from and start the cookie engine, or if + it isn't a file it will pass on the given string. -b name=var works and so + does -b cookiefile. + + -j, --junk-session-cookies + + when used in combination with -b, it will skip all "session cookies" on + load so as to appear to start a new cookie session. + + -c, --cookie-jar + + tell curl to start the cookie engine and write cookies to the given file + after the request(s) + +cookies with libcurl +==================== + +libcurl options: + + CURLOPT_COOKIE + + Is used when you want to specify the exact contents of a cookie header to + send to the server. + + CURLOPT_COOKIEFILE + + Tell libcurl to activate the cookie engine, and to read the initial set of + cookies from the given file. Read-only. + + CURLOPT_COOKIEJAR + + Tell libcurl to activate the cookie engine, and when the easy handle is + closed save all known cookies to the given cookiejar file. Write-only. + + CURLOPT_COOKIELIST + + Provide detailed information about a single cookie to add to the internal + storage of cookies. Pass in the cookie as a HTTP header with all the + details set, or pass in a line from a netscape cookie file. This option + can also be used to flush the cookies etc. + + CURLINFO_COOKIELIST + + Extract cookie information from the internal cookie storage as a linked + list. + +cookies with javascript +======================= + +These days a lot of the web is built up by javascript. The webbrowser loads +complete programs that render the page you see. These javascript programs can +also set and access cookies. + +Since curl and libcurl are plain HTTP clients without any knowledge of or +capability to handle javascript, such cookies will not be detected or used. + +Often, if you want to mimic what a browser does on such web sites, you can +record web browser HTTP traffic when using such a site and then repeat the +cookie operations using curl or libcurl. diff --git a/docs/Makefile.am b/docs/Makefile.am index 9edf05fde..0701ba823 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +# Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -36,7 +36,7 @@ EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS \ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS \ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL \ $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \ - MAIL-ETIQUETTE + MAIL-ETIQUETTE HTTP-COOKIES MAN2HTML= roffit < $< >$@