Testing: Increase timeout again

[cgi-auth-flexible.git] / caf.pod

diff --git a/caf.pod b/caf.pod
index ab45ac096b306a6fdfbb4af03c19de8974909d4d..6ddc56e647929e40678f68ceb2f33877b6e4ae7b 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -1,5 +1,20 @@
 # -*- fundamental -*-
 
 # -*- 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
 =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>).
 
 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
 
 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
 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
 
 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
 
 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.)
 
 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>
 =item C<MAINPAGEONLY>
 
 We should generate our main page but B<ignoring all form parameters>


@@ -739,6 +778,9 @@ kind.)
 
 =back
 
 
 =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
 =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
 
 
 =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
 =item C<srcdump_param_name>
 
 Form parameter name used to indicate that this is a source download