From 923d52944b6fb51d2a1a51e60997d9d02e7bde91 Mon Sep 17 00:00:00 2001 From: Brendan Taylor Date: Wed, 24 Nov 2010 00:21:10 -0700 Subject: document uzbl-cookie-manager and the cookie daemon protocol --- docs/README.cookies | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/README.cookies (limited to 'docs') diff --git a/docs/README.cookies b/docs/README.cookies new file mode 100644 index 0000000..148603f --- /dev/null +++ b/docs/README.cookies @@ -0,0 +1,63 @@ +# Cookies and Uzbl # + +The speed of cookie lookups is important, since a single page load can involve +dozens of HTTP requests, each of which needs a separate cookie lookup (since +another instance of uzbl may have obtained new cookies for a site). + +It is possible handle cookie lookup (and storage) using a `spawn_async` cookie +handler, but spawning new processes is inherently slow so a `talk_to_socket` +cookie daemon (like the default uzbl-cookie-manager) is recommended. + +## uzbl-cookie-manager ## + +uzbl-cookie-manager is a cookie daemon based on libsoup's SoupCookieJar. Cookies +are stored in a file in the Mozilla cookies.txt format (default location +$XDG_DATA_HOME/.local/share/cookies.txt). + +### uzbl-cookie-manager Whitelist ### + +If a whitelist file is present (default location +$XDG_CONFIG_HOME/uzbl/cookie_whitelist), then website attempts to set cookies +will be ignored unless the site's domain is present in the whitelist. + +The whitelist can contain comment lines beginning with `#`, and domain lines. A +domain line beginning with . will whitelist the given domain name and any +subdomain of it. Otherwise only exact matches of the domain are whitelisted. + +For instance, given this whitelist file: + + example.com + .uzbl.org + +uzbl-cookie-manager would accept cookies for example.com, uzbl.org and +www.uzbl.org, but ignore cookies set for www.example.com (and any other +domain that is not a subdomain of uzbl.org). + +## uzbl-cookie-daemon ## + +uzbl-cookie-daemon is a Python cookie daemon based on Python's cookielib. +Cookielib's lookup algorithm isn't very efficient for our needs, so +uzbl-cookie-daemon is noticeably slow. + +## Cookie Daemon Protocol ## + +When uzbl's `cookie_handler` variable is set to `talk_to_socket path`, uzbl +connects to the Unix domain socket located at `path`. uzbl will send a cookie +lookup request on this socket every time it makes an HTTP request. The format of +this lookup request is: + + GET\0scheme\0host\0path\0 + +where `\0` is the null character, `scheme` is the URL scheme (http or https), +`host` is the hostname from the URL and `path` is the requested path. The cookie +daemon should respond with the names and values of cookies that match the +request, in the format used by the `Cookie` header, terminated with a `\0`. + +When a website adds, deletes or changes a cookie, uzbl notifies the cookie +daemon with a request in the format: + + PUT\0scheme\0host\0path\0name=value\0 + +where `scheme`, `host` and `path` are (approximately) as above, and `name=value` +is the cookie name-value pair to store. The cookie daemon should respond by +writing `\0` to the socket. -- cgit v1.2.3