# -*- 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
=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
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
a 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.
=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
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>
=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
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>.
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
+=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
=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
+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
-=head OTHER FUNCTIONS AND METHODS
+=head1 OTHER FUNCTIONS AND METHODS
=over
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
=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>
+
+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. (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
+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<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>
+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.)
+
+=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
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.
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).
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']>
The default is 1.
-=back
-
=item C<< get_url($cgi,$authreq) >>
Hook which returns the URL of this web application. By default, we
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
=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
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
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>. It searches the item and its parent
+C<srcdump_process_item>.
+
+It skips directories for which C<srcdump_system_dir> returns true.
+
+It then searches the item and its parent
directories for a vcs metadata directory (one of the names in
C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
(after checking and updaeing C<%dirsdone>).
Entries must not contain C<'> or C<\>.
+=item C<srcdump_listitems($cgi,$verifier)>
-xxx conditions on listitems implied by srcdump_dirscan_prepare
-xxx listitems enoent behaviour
-The de
+Returns an array of directories which might contain source code of the
+web application and which should be therefore be considered for
+including in the source code delivery.
-xxx syntax of srcdump_excludes
+Used by the default implementation of C<srcdump_prepare>.
+Entries must be directories, plain files, or nonexistent; they may
+also be symlinks which resolve to one of those.
-=back
+If C<.> is included it may be treated specially - see
+C<srcdump_filter_cwd>.
+
+The default implementation returns
+C<(@INC, $ENV{'SCRIPT_FILENAME'}, $0)>.
+
+=item C<srcdump_system_dir($cgi,$verifier,$dir)>
+
+Determines whether C<$dir> is a "system directory", in which any
+source code used by the application should nevertheless not be
+included in the source code dump.
+
+Used by the default implementation of C<srcdump_item>.
+
+The default implementation is as follows: Things in C</etc/> are
+system directories. Things in C</usr/> are too, unless they are in
+C</usr/local/> or C</usr/lib/cgi*>.
+
+=item C<srcdump_filter_cwd>
+
+Boolean which controls the handling of C<.> if it appears in the
+return value from C<srcdump_listitems>. Used only by the default
+implementation of C<srcdump_prepare>.
+
+If set to false, C<.> is treated normally and no special action is
+taken.
+
+However often the current directory may be C</>, or a data directory,
+or some other directory containing data which is confidential, or
+should not be included in the public source code distribution for
+other reasons. And for historical reasons Perl has C<@INC> containing
+C<.> by default (which is arguably dangerous and wrong).
+
+So the default this setting is true, which has the following effects:
+
+C<.> is not searched for source code even if it appears in C<@INC>.
+C<.> is removed from C<@INC> and C<%INC> is checked to see if any
+modules appear to have already been loaded by virtue of C<.> appearing
+in C<@INC> and if they have it is treated as a fatal error.
+Only the literal string C<.> is affected. If the cwd is included by
+any other name it is not treated specially regardless of this setting.
+
+=back
=head1 DATABASE TABLES
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
~ian / cgi-auth-flexible.git / blobdiff