X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=de77f3d3562a50e673af1795b9c171f83fe8b5af;hp=fcb061521d4858218e432dd3cbd31f83d90bbb5d;hb=412316a7005df29b1adb30835848490210498ecb;hpb=d4cf8c70946f34cc9f46f9b5fe25962df77154ba diff --git a/caf.pod b/caf.pod index fcb0615..de77f3d 100644 --- a/caf.pod +++ b/caf.pod @@ -1,5 +1,20 @@ # -*- fundamental -*- +# This is part of CGI::Auth::Flexible, a perl CGI authentication module. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version, with the "CAF Login Exception" +# as published by Ian Jackson (version 1, or at your option any +# later version) as an Additional Permission. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. + + =head1 NAME CGI::Auth::Flexible - web authentication optionally using cookies @@ -133,10 +148,10 @@ interfaces for this: =head3 Simple applications -The simplist usage is to call C<< $request->check_ok() >> which will +The simplest usage is to call C<< $request->check_ok() >> which will check the user's authentication. If the user is not logged in it will generate a login form (or redirection or other appropriate page) and -return false; your application should not then processing that request +return false; your application should not then process that request any further. If the user is logged in it will return true. Various hooks are provided to customise the responses generated by @@ -145,13 +160,15 @@ C. After C returns true you should go ahead and process the request; you can use C<< $request->get_username >> to find out which user the request came from. +You may also need to call C and/or C +- see below. -=head2 Sophisticated applications +=head3 Sophisticated applications If you want to handle the control flow and to generate login forms, redirections, etc., yourself, you can say C<< $divert = $request->check_divert >>. This returns undef if -the user is logged in, or I if some kind of login +the user is logged in, or a I if some kind of login page or diversion should be generated. See L below for details of how to deal with the return value. @@ -159,16 +176,19 @@ details of how to deal with the return value. =head3 Mutation-ignorant applications -By default CGI::Auth::Flexible does not permit external links into -your site. All GET requests give a "click to continue" page which +By default CGI::Auth::Flexible does not permit external deep links +into your site. +All GET requests give a "click to continue" page which submits a form which loads your app's main page. In this configuration all your application's forms and AJAX requests should -use C. This restriction arises from complicated deficiencies -in the web's security architecture. +use C. Such applications are also not able to provide user-specific CSS stylesheets, javascript, favicons, etc. +This restriction arises from complicated deficiencies +in the web's security architecture. + =head3 Mutation-aware applications The alternative is for your application to always make a special check @@ -198,7 +218,7 @@ include a secret hidden form parameter for the benefit of CGI::Auth::Generic. This form parameter will be checked by C/C and should be ignored by your application. -By default the hidden parameter is called C. +By default the hidden parameter is called C. After calling C or C the value to put in your form can be obtained from C; C @@ -373,6 +393,8 @@ All of these are only valid after C or C has been called. (In the case of C it won't normally be sensible to call these functions unless C returned true.) +=over + =item C<< $authreq->get_divert() >> Returns the value previously returned by C. @@ -413,8 +435,12 @@ C will either return successfully, indicating that all is well and the request should proceed, or it will die, like C. +=back + =head1 RESPONSE-RELATED FUNCTIONS AND METHODS +=over + =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >> Convenience function which returns a url for a GET request to this @@ -462,7 +488,7 @@ Returns the value of the secret cookie. CGI::Auth::Flexible sets this cookie in the forms generated by C. You may also set it yourself (and indeed you must do so if you use C). -item C<< $authreq->_chain_params() >> +=item C<< $authreq->_chain_params() >> Returns a hash of the "relevant" parameters to this request, in a form suitable for C. This is all of the query @@ -490,7 +516,7 @@ parameter. I<$reqtype> is the request type (the value which will be passed to C and C. If you are supporting a new -I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea, +I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstream, or other users, to assign a unique request type name. This method may be called on an authreq or a verifier, in which case @@ -603,7 +629,7 @@ confidential for the user.) C<< XMLHttpRequest >> returning data of some other kind. (Possibly confidential for the user.) -=back. +=back =head1 DIVERT SPEC @@ -633,6 +659,10 @@ should be sent; C<''> means the cookie should be cleared. =item C +Provided with diversion kinds which involve +generating a redirection or indirection, +perhaps via a login form. + The extra hidden form parameters (and the C) which should be set when the subsequent request bounces back from the client, in the form used by C. @@ -710,6 +740,28 @@ We should generate a login form. The user is not yet logged in. We should redirect to our actual application, with the specified parameters. (The user has just logged in.) +=item C + +The user is logged in but the incoming form submission looks like it +was from a stale login session. Alternatively, it may have been +generated by an attacker's cross-site-scripting attack. + +Naive applications should generate a small page with a form or link to +our own main page without any parameters. + +A sophisticated application could infer from the submitted form +parameters what the user was allegedly trying to do. We could then +generate a fresh page showing what the intended action was, with a +fresh form which (if the user confirm) would resubmit that action. +B must be taken to avoid relying on the sanity and +coherence of the incoming form parameters. We B simply +reproduce the incoming parameters in the new form. It is essential +that the visual appearance of the generated form correctly shows to +the user what the action is that will be taken if the form is +submitted. If that action is dangerous, the form should not look like +the kind of confirmation pages which the user is likely to simply +click through without thinking. + =item C We should generate our main page but B @@ -722,6 +774,11 @@ submits our own main page without any parameters. (Applications which set C do not see this divert kind.) +=back + +Applications should die if they are presented with a divert kind that +they don't recognise. + =head1 SETTINGS C and C each take a list of settings, as @@ -748,10 +805,10 @@ When a hook's default implementation is mentioned and named, that function won't also be described in the section on the module's functions. -=over - =head2 GENERAL SETTINGS +=over + =item C The directory CGI::Auth::Generic should use for its data storage. @@ -881,7 +938,7 @@ Used by the default C hook. If you want users to be able to explicitly log out, you need to provide a logout button, something like -C<< > +C<< > The default is C<['caf_logout']> @@ -914,8 +971,6 @@ only flag on its cookie. The default is 1. -=back - =item C<< get_url($cgi,$authreq) >> Hook which returns the URL of this web application. By default, we @@ -974,8 +1029,6 @@ value of the cookie. Returns the HTTP method as a string. The default is to call C<< $cgi->request_method() >>. -=back - =item C<< is_https($cgi,$authreq) >> Returns a boolean indicating whether the request was over an encrypted @@ -1087,6 +1140,8 @@ Size of generated text entry fields. Default is 60. Some of CAF's HTML-generating functions need to invent form parameter names. They will all start with this string. Default: C. +=back + =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY =over @@ -1353,7 +1408,11 @@ xxx document construct_cookie fn xxx document @default_db_setup_statements xxx bugs wrong default random on Linux + xxx bugs wrong default random on *BSD + xxx bugs keys not shared should be in db + xxx rename caf_assocsecret default cookie name + xxx mention relationship between login_timeout and cookies