From 33ee67112f3b9a0010a4ed92b3ee8321f2da969a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jul 2012 09:03:08 +0200 Subject: HTTP-COOKIES: added cookie documentation --- docs/HTTP-COOKIES | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/HTTP-COOKIES (limited to '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. -- cgit v1.2.1 From ae8f08ee5919fe6ab5a2850f3151077baf7077de Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jul 2012 10:54:46 +0200 Subject: HTTP-COOKIES: use the FAQ document layout --- docs/HTTP-COOKIES | 97 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 43 deletions(-) (limited to 'docs/HTTP-COOKIES') diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES index 660c0b3d0..4fccb9d9e 100644 --- a/docs/HTTP-COOKIES +++ b/docs/HTTP-COOKIES @@ -1,45 +1,58 @@ - HTTP Cookies +Updated: July 3, 2012 (http://curl.haxx.se/docs/http-cookies.html) + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| -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. +HTTP Cookies -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. + 1. Cookie overview + 2. Cookies saved to disk + 3. Cookies with curl the command line tool + 4. Cookies with libcurl + 5. Cookies with javascript -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 +1. Cookie overview -In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published -and details how cookies work within HTTP. + 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 saved to disk -===================== + 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. -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. + Cookies are set to the client with the Set-Cookie: header and are sent to + servers with the Cookie: header. -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. + 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 -cookies with curl the command line tool -======================================= + In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published + and details how cookies work within HTTP. -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. +2. Cookies saved to disk -Command line options: + 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. + +3. 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 @@ -57,10 +70,9 @@ Command line options: tell curl to start the cookie engine and write cookies to the given file after the request(s) -cookies with libcurl -==================== +4. Cookies with libcurl -libcurl options: + libcurl options: CURLOPT_COOKIE @@ -89,16 +101,15 @@ libcurl options: Extract cookie information from the internal cookie storage as a linked list. -cookies with javascript -======================= +5. 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. + 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. + 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. + 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. -- cgit v1.2.1 From 016dabcf047a5788812d86bdbd69b2da7f9faee1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jul 2012 11:10:41 +0200 Subject: HTTP-COOKIES: clarified and modified layout --- docs/HTTP-COOKIES | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) (limited to 'docs/HTTP-COOKIES') diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES index 4fccb9d9e..818e161ee 100644 --- a/docs/HTTP-COOKIES +++ b/docs/HTTP-COOKIES @@ -8,15 +8,18 @@ Updated: July 3, 2012 (http://curl.haxx.se/docs/http-cookies.html) HTTP Cookies - 1. Cookie overview - 2. Cookies saved to disk - 3. Cookies with curl the command line tool - 4. Cookies with libcurl - 5. Cookies with javascript + 1. HTTP Cookies + 1.1 Cookie overview + 1.2 Cookies saved to disk + 1.3 Cookies with curl the command line tool + 1.4 Cookies with libcurl + 1.5 Cookies with javascript ============================================================================== -1. Cookie overview +1. HTTP Cookies + + 1.1 Cookie 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 @@ -36,18 +39,21 @@ HTTP Cookies In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published and details how cookies work within HTTP. -2. Cookies saved to disk + 1.2 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. + The netscape 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. + + When libcurl saves a cookiejar, it creates a file header of its own in which + there is a URL mention that will link to the web version of this document. -3. Cookies with curl the command line tool + 1.3 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. @@ -70,9 +76,11 @@ HTTP Cookies tell curl to start the cookie engine and write cookies to the given file after the request(s) -4. Cookies with libcurl + 1.4 Cookies with libcurl - libcurl options: + libcurl offers several ways to enable and interface the cookie engine. These + options are the ones provided by the native API. libcurl bindings may offer + access to them using other means. CURLOPT_COOKIE @@ -101,7 +109,7 @@ HTTP Cookies Extract cookie information from the internal cookie storage as a linked list. -5. Cookies with javascript + 1.5 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 -- cgit v1.2.1