aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/HTTP-COOKIES123
-rw-r--r--docs/HTTP-COOKIES.md104
-rw-r--r--docs/Makefile.am10
3 files changed, 109 insertions, 128 deletions
diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES
deleted file mode 100644
index 0e43ba760..000000000
--- a/docs/HTTP-COOKIES
+++ /dev/null
@@ -1,123 +0,0 @@
-Updated: July 3, 2012 (https://curl.haxx.se/docs/http-cookies.html)
- _ _ ____ _
- ___| | | | _ \| |
- / __| | | | |_) | |
- | (__| |_| | _ <| |___
- \___|\___/|_| \_\_____|
-
-
-HTTP Cookies
-
- 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. 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
- 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: https://curl.haxx.se/rfc/cookie_spec.html
-
- In 2011, RFC6265 (https://www.ietf.org/rfc/rfc6265.txt) was finally published
- and details how cookies work within HTTP.
-
- 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 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.
-
- 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.
-
- 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)
-
- 1.4 Cookies with libcurl
-
- 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
-
- 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.
-
- 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
- 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/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md
new file mode 100644
index 000000000..a1b283454
--- /dev/null
+++ b/docs/HTTP-COOKIES.md
@@ -0,0 +1,104 @@
+# HTTP Cookies
+
+## Cookie overview
+
+ Cookies are `name=contents` pairs that a HTTP server tells the client to
+ hold and then the client sends back those to the server on subsequent
+ requests to the same domains and 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](https://curl.haxx.se/rfc/cookie_spec.html).
+
+ In 2011, [RFC6265](https://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 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.
+
+## 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 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`
+
+ 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 b202a5dd8..1fcc0cf9a 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -33,11 +33,11 @@ SUBDIRS = examples libcurl
CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES)
-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 INSTALL.devcpp \
- MAIL-ETIQUETTE HTTP-COOKIES SECURITY RELEASE-PROCEDURE SSL-PROBLEMS \
+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 INSTALL.devcpp \
+ MAIL-ETIQUETTE HTTP-COOKIES.md SECURITY RELEASE-PROCEDURE SSL-PROBLEMS \
HTTP2.md ROADMAP.md CODE_OF_CONDUCT.md CODE_STYLE.md
MAN2HTML= roffit < $< >$@