chiark / gitweb /
Testing: Provide srcdump-login test
[cgi-auth-flexible.git] / caf.pod
diff --git a/caf.pod b/caf.pod
index 2088fe5..6ddc56e 100644 (file)
--- 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<check_ok>.
 After C<check_ok> 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<check_mutate> and/or C<check_nonpage>
+- 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<divert spec> if some kind of login
+the user is logged in, or I<divert spec> if some kind of login
 page or diversion should be generated.  See L</DIVERT SPEC> 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<POST>.  This restriction arises from complicated deficiencies
-in the web's security architecture.
+use C<POST>.
 
 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<check_ok>/C<check_divert> and should be ignored by your application.
 
-By default the hidden parameter is called C<caf_assochash>.
+By default the hidden parameter is called C<caf__assochash>.
 
 After calling C<check_ok> or C<check_divert> the value to put in your
 form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
@@ -373,6 +393,8 @@ All of these are only valid after C<check_divert> or C<check_ok> has
 been called.  (In the case of C<check_ok> it won't normally be sensible
 to call these functions unless C<check_ok> returned true.)
 
+=over
+
 =item C<< $authreq->get_divert() >>
 
 Returns the value previously returned by C<check_divert>.
@@ -413,14 +435,19 @@ C<check_nonpage> will either return successfully, indicating that all
 is well and the request should proceed, or it will die, like
 C<check_mutate>.
 
+=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
 application.
 
-I<$params> is a hashref specifying the parameters and the PATH_INFO.
+I<$params> is a hashref specifying the parameters and the PATH_INFO
+(not including any parameters related to CGI::Auth::Flexible).
 The keys are the parameter names, and the values are array refs with
 the parameter value(s) (as strings, as yet unquoted).  (They are array
 refs because it is possible to pass multiple values for the same
@@ -461,6 +488,14 @@ 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() >>
+
+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's authentication
+arrangements.  (The srcdump request parameters B<are> included.)  The
+PATH_INFO from the request is returned as the parameter C<< '' >>.
+
 =back
 
 =head1 OTHER FUNCTIONS AND METHODS
@@ -482,7 +517,7 @@ parameter.
 
 I<$reqtype> is the request type (the value which will be passed to
 C<check_nonpage> and C<need_add_hidden>.  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
@@ -595,7 +630,7 @@ confidential for the user.)
 C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
 confidential for the user.)
 
-=back.
+=back
 
 =head1 DIVERT SPEC
 
@@ -618,20 +653,25 @@ any tags.
 
 =item C<CookieSecret>
 
-The secret cookie which should be set along with whatever response is
-sent to the client.  The value in the hash is the actual secret value
+The login cookie which should be set along with whatever response is
+sent to the client.  The value in the hash is the actual value
 of the cookie as a string.  C<undef> means no cookie setting header
 should be sent; C<''> means the cookie should be cleared.
 
 =item C<Params>
 
+Provided with diversion kinds which involve
+generating a redirection or indirection,
+perhaps via a login form.
+
 The extra hidden form parameters (and the C<PATH_INFO>) which should
 be set when the subsequent request bounces back from the client, in
 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
@@ -702,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>
@@ -714,6 +776,11 @@ submits our own main page without any parameters.
 (Applications which set C<promise_check_mutate> 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<new_verifier> and C<new_request> each take a list of settings, as
@@ -740,10 +807,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<dir>
 
 The directory CGI::Auth::Generic should use for its data storage.
@@ -752,7 +819,7 @@ path settings are relative values.
 
 Must be an absolute filename.
 
-=item C<assocdb_dbh>
+=item C<db_dbh>
 
 CGI::Auth::Flexible needs a database for recording users' login
 session.  This database needs to be shared across all instances of the
@@ -766,26 +833,26 @@ particular, there is no need for transactional integrity across
 changes made by CAF and your own application.)
 
 By default, CAF uses a sqlite3 database stored on local disk in the
-file named by C<assocdb_path>.  This will be suitable for all
+file named by C<db_path>.  This will be suitable for all
 applications which run on a single host.
 
 This value, if supplied, should be a DBI handle for the database.
 
-=item C<assocdb_dsn>
+=item C<db_dsn>
 
 This is the DSN to pass to C<< DBI->connect >>.  Used only if
-C<assocdb_dbh> is not supplied.
+C<db_dbh> is not supplied.
 
-=item C<assocdb_path>
+=item C<db_path>
 
 Path to the sqlite3 database used for CAF's session storage.  The
-default is currently C<caf-assocs.db> but will change in the future.
+default is C<caf.db>.
 
-Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
+Used only if neither C<db_dbh> or C<db_dsn> are supplied.
 
 If this is a relative path, it is in C<dir>.
 
-=item C<assocdb_table>
+=item C<db_prefix>
 
 Prefix for the SQL tables and indices to use (and to create, if
 necessary).
@@ -873,7 +940,7 @@ Used by the default C<is_logout> hook.
 
 If you want users to be able to explicitly log out, you need to
 provide a logout button, something like
-C<< <input type="submit" name="caf_logout" ...>>
+C<< <input type="submit" name="caf_logout" ... >>
 
 The default is C<['caf_logout']>
 
@@ -906,8 +973,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
@@ -966,8 +1031,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
@@ -1079,10 +1142,17 @@ 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<caf__>.
 
+=back
+
 =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
 
 =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
@@ -1320,7 +1390,7 @@ reported anywhere.
 
 If you use a different database, or just prefer to do things
 differently, you can set up the tables yourself and/or disable or
-modify the default setup statements, via the C<assocdb_setup_stmts>
+modify the default setup statements, via the C<db_setup_stmts>
 setting.
 
 The tables needed are:
@@ -1331,7 +1401,7 @@ xxx make _db_setup_do explicitly overrideable
 
 
 xxx remaining settings
assocdb_password
+ db_password
  username_password_error
  login_ok
  get_cookie_domain
@@ -1345,9 +1415,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-assocs.db
+
 xxx rename caf_assocsecret default cookie name
+
 xxx mention relationship between login_timeout and cookies
-xxx rename assocdb settings to db