diff options
Diffstat (limited to 'doc/cookiejar.n')
| -rw-r--r-- | doc/cookiejar.n | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/doc/cookiejar.n b/doc/cookiejar.n new file mode 100644 index 0000000..0d8b81a --- /dev/null +++ b/doc/cookiejar.n @@ -0,0 +1,217 @@ +'\" +'\" Copyright (c) 2014-2018 Donal K. Fellows. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH "cookiejar" n 0.1 http "Tcl Bundled Packages" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +cookiejar \- Implementation of the Tcl http package cookie jar protocol +.SH SYNOPSIS +.nf +\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR? + +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? +\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR? +\fB::http::cookiejar new\fR ?\fIfilename\fR? + +\fIcookiejar\fR \fBdestroy\fR +\fIcookiejar\fR \fBforceLoadDomainData\fR +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +.fi +.SH DESCRIPTION +.PP +The cookiejar package provides an implementation of the http package's cookie +jar protocol using an SQLite database. It provides one main command, +\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to +create a cookie jar that manages a particular HTTP session. +.PP +The database management policy can be controlled at the package level by the +\fBconfigure\fR method on the \fB::http::cookiejar\fR class object: +.TP +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR? +. +If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a +copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is +supplied, just the value of the named option is returned. If both +\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed +to be the given value. +.RS +.PP +Supported options are: +.TP +\fB\-domainfile \fIfilename\fR +. +A file (defaulting to within the cookiejar package) with a description of the +list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains +\fImust not\fR accept cookies set upon them. Note that the list of such +domains is both security-sensitive and \fInot\fR constant and should be +periodically refetched. Cookie jars maintain their own cache of the domain +list. +.TP +\fB\-domainlist \fIurl\fR +. +A URL to fetch the list of top-level domains (e.g., \fB.com\fR or +\fB.co.jp\fR) from. Such domains \fImust not\fR accept cookies set upon +them. Note that the list of such domains is both security-sensitive and +\fInot\fR constant and should be periodically refetched. Cookie jars maintain +their own cache of the domain list. +.TP +\fB\-domainrefresh \fIintervalMilliseconds\fR +. +The number of milliseconds between checks of the \fI\-domainlist\fR for new +domains. +.TP +\fB\-loglevel \fIlevel\fR +. +The logging level of this package. The logging level must be (in order of +decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or +\fBerror\fR. +.TP +\fB\-offline \fIflag\fR +. +Allows the cookie managment engine to be placed into offline mode. In offline +mode, the list of domains is read immediately from the file configured in the +\fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it +also makes the \fB\-domainrefresh\fR option be effectively ignored. +.TP +\fB\-purgeold \fIintervalMilliseconds\fR +. +The number of milliseconds between checks of the database for expired +cookies; expired cookies are deleted. +.TP +\fB\-retain \fIcookieCount\fR +. +The maximum number of cookies to retain in the database. +.TP +\fB\-vacuumtrigger \fIdeletionCount\fR +. +A count of the number of persistent cookie deletions to go between vacuuming +the database. +.RE +.PP +Cookie jar instances may be made with any of the standard TclOO instance +creation methods (\fBcreate\fR or \fBnew\fR). +.TP +\fB::http::cookiejar new\fR ?\fIfilename\fR? +. +If a \fIfilename\fR argument is provided, it is the name of a file containing +an SQLite database that will contain the persistent cookies maintained by the +cookie jar; the database will be created if the file does not already +exist. If \fIfilename\fR is not supplied, the database will be held entirely within +memory, which effectively forces all cookies within it to be session cookies. +.SS "INSTANCE METHODS" +.PP +The following methods are supported on the instances: +.TP +\fIcookiejar\fR \fBdestroy\fR +. +This is the standard TclOO destruction method. It does \fInot\fR delete the +SQLite database if it is written to disk. Callers are responsible for ensuring +that the cookie jar is not in use by the http package at the time of +destruction. +.TP +\fIcookiejar\fR \fBforceLoadDomainData\fR +. +This method causes the cookie jar to immediately load (and cache) the domain +list data. The domain list will be loaded from the \fB\-domainlist\fR +configured a the package level if that is enabled, and otherwise will be +obtained from the \fB\-domainfile\fR configured at the package level. +.TP +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR +. +This method obtains the cookies for a particular HTTP request. \fIThis +implements the http cookie jar protocol.\fR +.TP +\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR +. +This method is called by the \fBstoreCookie\fR method to get a decision on +whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and +\fIpath\fR. This is checked immediately before the database is updated but +after the built-in security checks are done, and should return a boolean +value; if the value is false, the operation is rejected and the database is +not modified. The supported \fIoperation\fRs are: +.RS +.TP +\fBdelete\fR +. +The \fIdomain\fR is seeking to delete a cookie. +.TP +\fBsession\fR +. +The \fIdomain\fR is seeking to create or update a session cookie. +.TP +\fBset\fR +. +The \fIdomain\fR is seeking to create or update a persistent cookie (with a +defined lifetime). +.PP +The default implementation of this method just returns true, but subclasses of +this class may impose their own rules. +.RE +.TP +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR +. +This method stores a single cookie from a particular HTTP response. Cookies +that fail security checks are ignored. \fIThis implements the http cookie jar +protocol.\fR +.TP +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR? +. +This method looks a cookie by exact host (or domain) matching. If neither +\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is +stored is returned. If just \fIhost\fR (which may be a hostname or a domain +name) is supplied, the list of cookie keys stored for that host is returned. +If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is +returned; it is an error if no such host or key match exactly. +.SH "EXAMPLES" +.PP +The simplest way of using a cookie jar is to just permanently configure it at +the start of the application. +.PP +.CS +package require http +\fBpackage require cookiejar\fR + +set cookiedb ~/.tclcookies.db +http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb] + +# No further explicit steps are required to use cookies +set tok [http::geturl http://core.tcl.tk/] +.CE +.PP +To only allow a particular domain to use cookies, perhaps because you only +want to enable a particular host to create and manipulate sessions, create a +subclass that imposes that policy. +.PP +.CS +package require http +\fBpackage require cookiejar\fR + +oo::class create MyCookieJar { + superclass \fBhttp::cookiejar\fR + + method \fBpolicyAllow\fR {operation domain path} { + return [expr {$domain eq "my.example.com"}] + } +} + +set cookiedb ~/.tclcookies.db +http::configure -cookiejar [MyCookieJar new $cookiedb] + +# No further explicit steps are required to use cookies +set tok [http::geturl http://core.tcl.tk/] +.CE +.SH "SEE ALSO" +http(n), oo::class(n), sqlite3(n) +.SH KEYWORDS +cookie, internet, security policy, www +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |