X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=216410332ba969741638bbd470be110c907944fd;hp=1308700f58b6a96dd6e08bcc67fbd569eaac99e0;hb=22718a11458ca91fa40bcd11270ed1e3606ea12f;hpb=850b51b3ddfd5c5302cb901ac91e5b9d3cbd81ed

diff --git a/caf.pod b/caf.pod
index 1308700..2164103 100644
--- a/caf.pod
+++ b/caf.pod
@@ -367,7 +367,7 @@ Discards the resources (open files, etc.) in the verifier object.
 
 =back
 
-=head REQUEST-RELATED FUNCTIONS AND METHODS
+=head1 REQUEST-RELATED FUNCTIONS AND METHODS
 
 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
@@ -409,11 +409,11 @@ whenever it is handling anything except an HTML page loads, it must
 call this function.  See L</REQUEST TYPES>, and
 L<GENERATING URLS, FORMS AND AJAX QUERIES>.
 
-C<check_mutate> will either return successfully, indicating that all
+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>.
 
-=head RESPONSE-RELATED FUNCTIONS AND METHODS
+=head1 RESPONSE-RELATED FUNCTIONS AND METHODS
 
 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
 
@@ -461,18 +461,9 @@ 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
-used by XXX.  This is all of the query parameters which are not
-related to CGI::Auth::Flexible.  The PATH_INFO from the request is
-returned as the parameter C<< '' >>.
-
-xxx why use this function
-
 =back
 
-=head OTHER FUNCTIONS AND METHODS
+=head1 OTHER FUNCTIONS AND METHODS
 
 =over
 
@@ -531,6 +522,198 @@ digits.
 
 =back
 
+=head1 REQUEST TYPES
+
+The C<$reqtype> values understood by C<check_nonpage> are strings.
+They are:
+
+=over
+
+=item C<PAGE>
+
+A top-level HTML page load.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<FRAME>
+
+An HTML frame.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<IFRAME>
+
+An HTML iframe.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<SRCDUMP>
+
+Source dump request, whether for the licence or actual source code
+tarball; returned value is not secret.
+
+=item C<STYLESHEET>
+
+CSS stylesheet.  B<MUST NOT> contain any confidential data.  If the
+stylesheet depends on the user, then attackers may be able to
+determine what stylesheet the user is using.  Hopefully this is not a
+problem.
+
+=item C<FAVICON>
+
+"Favicon" - icon for display in the browser's url bar etc.  We aren't
+currently aware of a way that attackers can get a copy of this.
+
+=item C<ROBOTS>
+
+C<robots.txt>.  Should not contain any confidential data (obviously).
+
+=item C<IMAGE>
+
+Inline image, for an C<< <img src=...> >> element.
+
+Unfortunately it is not possible to sensibly show top-level
+confidential images (that is, have the user's browser directly visit a
+url which resolves to an image rather than an HTML page with an inline
+image).  This is because images need to have a per-session hidden form
+parameter to avoid cross-site scripting, which breaks bookmarks etc.
+
+=item C<SCRIPT>
+
+JavaScript for a C<< <script> >> element.  (Possibly confidential for
+the user.)
+
+=item C<AJAX-XML>
+
+C<< XMLHttpRequest >> returning XML data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-JSON>
+
+C<< XMLHttpRequest >> returning JSON data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-OTHER>
+
+C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
+confidential for the user.)
+
+=back.
+
+=head1 DIVERT SPEC
+
+The return value from C<check_divert> indicates how the request should
+be handled.  It is C<undef> if all is well and the user is logged in.
+
+Otherwise the return value is a hash ref with the following keys:
+
+=over
+
+=item C<Kind>
+
+Scalar string indicating the kind of diversion required.
+
+=item C<Message>
+
+Scalar string for display to the user in relation to the diversion.
+Has already been translated.  In HTML but normally does not contain
+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
+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>
+
+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.
+
+It is correct to always include the contents of C<Params> as hidden
+parameters in the urls for all redirections, and as hidden input
+fields in all generated forms.  The specific cases where C<Params> is
+currently relevant are also mentioned in the text for each divert
+kind.
+
+=back
+
+The values of C<Kind> are:
+
+=over
+
+=item C<SRCDUMP->I<item>
+
+We should respond by sending our application source code.  I<item>
+(which will contain only word characters, and no lower case) is the
+specific item to send, normally C<SOURCE> or C<LICENCE>.
+
+=item C<REDIRECT-HTTPS>
+
+We should respond with an HTTP redirect to the HTTPS instance of our
+application.
+
+=item C<REDIRECT-LOGGEDOUT>
+
+We should redirect to a page showing that the user has been logged
+out.  (Ie, to a url with one of the the C<loggedout_param_names> set.)
+
+=item C<SMALLPAGE-LOGGEDOUT>
+
+We should generate a page showing that the user has been logged out.
+There can be a link on the page pointing to the login page so that the
+user can log back in.
+
+=item C<SMALLPAGE-NOCOOKIE>
+
+We should generate a page reporting that the user does not have
+cookies enabled.  It should probably contain a link pointing to the
+login page with additionally all the parameters in C<Params>.  When
+this divert spec is generated, C<Message> will explain the problem
+with cookies so there is no need to do that again in the page body if
+you include the contents of C<Message>.
+
+=item C<LOGIN-STALE>
+
+The user's session was stale (this is described in C<Message>).  We
+should generate a login form.
+
+=item C<LOGIN-BAD>
+
+The user supplied bad login credentials.  The details are in
+C<Message>.  We should generate a login form (with additionally the
+parameters from C<Params> as hidden fields).
+
+=item C<LOGIN-INCOMINGLINK>
+
+We should generate a login form (with the specified parameters); the
+user is entering the site via a cross-site link but is not yet logged
+in.
+
+=item C<LOGIN-FRESH>
+
+We should generate a login form.  The user is not yet logged in.
+
+=item C<REDIRECT-LOGGEDIN>
+
+We should redirect to our actual application, with the specified
+parameters.  (The user has just logged in.)
+
+=item C<MAINPAGEONLY>
+
+We should generate our main page but B<ignoring all form parameters>
+and B<ignoring the path_info>.  Most applications will find this
+difficult to implement.
+
+An alternative is to generate a small page with a form or link which
+submits our own main page without any parameters.
+
+(Applications which set C<promise_check_mutate> do not see this divert
+kind.)
+
 =head1 SETTINGS
 
 C<new_verifier> and C<new_request> each take a list of settings, as
@@ -596,13 +779,13 @@ C<assocdb_dbh> is not supplied.
 =item C<assocdb_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.
 
 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).
@@ -794,7 +977,8 @@ channel.  The default is C<< !!$cgi->https() >>.  See C<encrypted_only>.
 
 =head2 SETTINGS RELATED TO HTML GENERATION
 
-These are only used if you call C<check_ok> or xxx some other functions?.
+These are only used if you call C<check_ok> (or other functions
+mentioned in this section).
 
 Settings whose names are of the form C<gen_...> are hooks which each
 return an array of strings, normally HTML strings, for use by
@@ -988,15 +1172,20 @@ been done and should be skipped; otherwise the hash entry should be set.
 C<\&outfn> is a coderef which C<srcdump_process_item> should call each
 time it wants to generate a file which should be included as part of
 the source code.  It should be called using one of these patterns:
-   $outfn->("message for log");
-   $outfile = $outfn->("message for log", "extension");
-The former simply logs this message (along with the associated
-C<$item>, so there is no need to mention that).  The latter logs the
-message but also generates and returns a filename which should then
+   $outfn->("message for manifest");
+   $outfile = $outfn->("message for manifest", "extension");
+The former simply prints the message into the manifest in the form
+  none: message for manifest
+The latter generates and returns a filename which should then
 be created and filled with some appropriate data.  C<"extension">
 should be a string for the file extension, eg C<"txt">.  The output
 can be written directly to the named file: there is no need to
-write to a temporary file and rename.
+write to a temporary file and rename.  C<$outfn> writes the filename
+and the message to the manifest, in the form
+  filename leaf: message
+In neither case is the actual name of C<$dir> on the system
+disclosed per se although of course some of the contents of some of
+the files in the source code dump may mention it.
 
 The default implementation is the module function
 C<srcdump_process_item>.
@@ -1122,19 +1311,42 @@ your application runs on multiple frontend hosts with a shared
 database, you may need to create for yourself the tables and indices
 used by CGI::Auth::Flexible.
 
+By default, every time CAF starts up, it attempts to execute certain
+fixed database statements to create the tables and indices it needs.
+These are run with C<$dbh->{PrintError}> set to 0.  The effect with
+sqlite (the default database) is that the tables and indices are
+created iff they do not already exist, and that no spurious errors are
+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>
+setting.
+
+The tables needed are:
+
+
 xxx document _db_setup_do
 xxx make _db_setup_do explicitly overrideable
 
 
-xxx divert spec
-xxx reqtype
-xxx settings
-xxx html generators
-xxx document cookie
+xxx remaining settings
+ assocdb_password
+ username_password_error
+ login_ok
+ get_cookie_domain
+ gettext
+ print
+ debug
+
+xxx document cookie usage
+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