=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
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]) >>
=back
-=head OTHER FUNCTIONS AND METHODS
+=head1 OTHER FUNCTIONS AND METHODS
=over
=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 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>
+
+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
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
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).
=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
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>.
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<db_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
+ db_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