X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=6ddc56e647929e40678f68ceb2f33877b6e4ae7b;hp=ab45ac096b306a6fdfbb4af03c19de8974909d4d;hb=8ab1e1db8a676282fd82a8c1c9cdae62111fd784;hpb=cdb13789e4025ebc1ab10ce6784ffad7a222a35a

diff --git a/caf.pod b/caf.pod
index ab45ac0..6ddc56e 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
@@ -473,11 +488,12 @@ Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
 cookie in the forms generated by C<check_ok>.  You may also set it
 yourself (and indeed you must do so if you use C<check_divert>).
 
-=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<url_with_query_params>.  This is all of the query
-parameters which are not related to CGI::Auth::Flexible.  The
+parameters which are not related to CGI::Auth::Flexible's authentication
+arrangements.  (The srcdump request parameters B<are> included.)  The
 PATH_INFO from the request is returned as the parameter C<< '' >>.
 
 =back
@@ -654,7 +670,8 @@ the form used by C<url_with_query_params>.
 
 The contents of this hashref does not include the CAF-specific
 parameters such as the secret cookie, those which follow from the kind
-of diversion requested, etc.
+of diversion requested, etc.  (But they may include the
+srcdump_param_name, so that srcdump_needlogin can work properly.)
 
 It is correct to always include the contents of C<Params> as hidden
 parameters in the urls for all redirections, and as hidden input
@@ -725,6 +742,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<STALE>
+
+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<Great care> must be taken to avoid relying on the sanity and
+coherence of the incoming form parameters.  We B<MUST NOT> 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<MAINPAGEONLY>
 
 We should generate our main page but B<ignoring all form parameters>
@@ -739,6 +778,9 @@ kind.)
 
 =back
 
+Applications should die if they are presented with a divert kind that
+they don't recognise.
+
 =head1 SETTINGS
 
 C<new_verifier> and C<new_request> each take a list of settings, as
@@ -1106,6 +1148,11 @@ names.  They will all start with this string.  Default: C<caf__>.
 
 =over
 
+=item C<srcdump_needlogin>
+
+Boolean: do users need to log in to be able to download the source
+code for the whole application ?  Default: 0.
+
 =item C<srcdump_param_name>
 
 Form parameter name used to indicate that this is a source download