+# -*- fundamental -*-
+
=head1 NAME
CGI::Auth::Flexible - web authentication optionally using cookies
=head1 SYNOPSYS
my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...);
- my $authreq = $verifier->new_request($cgi_query_object);
+ my $authreq = $verifier->new_request($cgi);
# simple applications
$authreq->check_ok() or return;
before generating HTML pages, of course, and to call it in every
entrypoint to your system.
+=head2 CHECKLIST
+
+As a minimum you need to do all of the things on this checklist, where
+applicable. The items marked SECURITY are the ones that you might
+forget: without them your application may appear to work, but will be
+insecure.
+
+=over
+
+=item *
+
+Call C<new_verifier> (once at application startup)
+
+=item *
+
+Call C<new_request> (once per request)
+
+=item *
+
+B<SECURITY>: Call C<check_ok> or C<check_divert> on every request, and
+honour the return value.
+
+=item *
+
+If you're using C<check_ok>, implement either the
+C<username_password_error> or C<login_ok> hook and provide it as
+a setting to C<new_verifier>.
+
+=item *
+
+Provide the setting C<dir> (or provide absolute paths for all the
+other relevant settings).
+
+=item *
+
+Call C<get_username> when you need to know who's logged in.
+
+=item *
+
+B<SECURITY>: Call C<check_mutate> or C<mutate_ok>, if you specified
+C<promise_check_mutate>.
+
+=item *
+
+B<SECURITY>: Call C<check_nonpage> for every request which is not a page load
+(if your application has any of those).
+
+=item *
+
+When generating URLs and forms (including AJAX requests), include the
+hidden form parameter using C<secret_hidden_val> or
+C<secret_hidden_html> when appropriate (see below).
+
+=item *
+
+B<SECURITY>: If you do not override the source provision facility (see
+L</SOURCE CODE DOWNLOAD>), check that the assumptions it makes aren't
+going to leak security-critical data.
+
+=item *
+
+Set up HTTPS on your webserver, or set the C<encrypted_only> setting
+to a false value.
+
+=back
+
+These points will now be covered in more detail.
+
=head2 INITIALISATION
Your application should, on startup (eg, when it is loaded by
The resulting verifier object can be used to process individual
requests, in each case with
-C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
+C<< $authreq = CGI::Auth::Flexible->new_request($cgi) >>.
+
+See L</SETTINGS>.
+
+=head2 CHECKING AND RESPONSE GENERATION
+
+If the user is logged in, your application is to handle the request.
+Otherwise, the user needs to be presented with a login form or error
+message, as appropriate. CGI::Auth::Flexible provides two alternative
+interfaces for this:
-=head2 SIMPLE APPLICATIONS
+=head3 Simple applications
The simplist usage is to call C<< $request->check_ok() >> which will
check the user's authentication. If the user is not logged in it will
return false; your application should not then processing that request
any further. If the user is logged in it will return true.
-After calling C<check_ok> you can use C<< $request->get_username >>
-to find out which user the request came from.
+Various hooks are provided to customise the responses generated by
+C<check_ok>.
-=head2 SOPHISTICATED APPLICATIONS
+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.
-If you want to handle the flow control and to generate login forms,
+=head2 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
-page or diversion should be generated.
-
-=head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
-
-When you generate a C<POST> form or AJAX request you need to include a
-special 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>. 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> will
-generate the whole HTML C<< <input...> >> element.
+page or diversion should be generated. See L</DIVERT SPEC> below for
+details of how to deal with the return value.
-Do not put the secret value in URLs for C<GET> requests.
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
+=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
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.
+in the web's security architecture.
+
+Such applications are also not able to provide user-specific CSS
+stylesheets, javascript, favicons, etc.
+
+=head3 Mutation-aware applications
The alternative is for your application to always make a special check
when the incoming request is going to do some kind of action (such as
modifying the user's setup, purchasing goods, or whatever) rather than
-just display HTML pages. Then non-mutating pages can be linked to
-from other, untrustworthy, websites.
+just retrieve and/or display information. We term such requests
+"mutating" requests.
+
+Then non-mutating pages can be linked to from other, untrustworthy,
+websites.
To support external links, and C<GET> requests, pass
C<< promise_check_mutate => 1 >> in I<settings>, and then call
incoming request is not suitable then C<< $authreq->check_mutate() >>
will call C<die>.
-You must make sure that you have no mutating C<GET> requests in your
-application - but you shouldn't have any of those anyway.
+There have to be no mutating C<GET> requests in your application (but
+you shouldn't have any of those anyway); if there are, they won't
+work. (CGI::Auth::Flexible will spot them and cause them to fail,
+rather than allow them to be insecure.)
+
+=head2 GENERATING URLS, FORMS AND AJAX QUERIES
+
+When you generate a URL, C<POST> form or AJAX request you may need to
+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>.
+
+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>
+will generate the whole HTML C<< <input...> >> element.
+
+=head3 Mutation-ignorant applications
+
+For mutation-ignorant applications (see above), all forms etc. should
+include the hidden parameter (and as discussed, they must all use
+POST rather than GET).
+
+=head3 Mutation-aware applications
+
+For mutation-aware applications, whether to include the secret
+parameter depends on the kind of request. CGI::Auth::Flexible knows
+when it is necessary. You should find out by calling
+C<need_add_hidden>.
+
+If it is inconvenient to call C<need_add_hidden> at runtime, you can
+rely instead on the following promises: All POST requests (which
+includes all mutating requests) need the parameter. The return value
+of need_add_hidden depends only on the $method and $reqtype
+parameters, so you can query it once and remember the answer.
+HTML page load GETs do not need the parameter. It is better to
+err on the side of including the parameter.
+
+If you really must, you can call C<need_add_hidden> "on the bench"
+during development and bake the answer into your application code
+structure. However, if you do that and a new vulnerability was
+discovered which is fixed by changing the answer, updating
+CGI::Auth::Flexible wouldn't be sufficient to fix it.
+
+=head3 Mutation-aware applications - non-page requests
+
+If your mutation-aware application supports non-page resources (AJAX
+and JSON requests, stylesheets, favicons, etc.) it must inform
+CGI::Auth::Flexible when it is handling such a request, by calling
+C<check_nonpage>.
+
+Normally C<check_nonpage> will simply return (and you can ignore the
+return value). However, if there is an attack (or, perhaps, a bug) it
+will die, stopping the attack.
+
+(You do not need to call C<check_nonpage> for POST requests, but it is
+harmless to do so.)
+
+=head3 Mutation-aware applications - novel kinds of request
+
+If you want to support a kind of request perhaps not yet known about
+by CGI::Auth::Flexible, you can provide information about that new
+request kind using C<update_get_need_add_hidden>.
=head2 DATA STORAGE
files, Javascript resources, etc., which are not contained in one of
the source item directories. (Files which came with your operating
system install don't need to be shipped as they fall under the system
-library exceptio.)
+library exception.)
=item *
You have not installed any modified versions of system
-libraries (including system-supplied) Perl modules in C</usr> outside
+libraries (including system-supplied Perl modules) in C</usr> outside
C</usr/local>. See C<srcdump_system_dir>.
=item *
For each source item in a dvcs, the entire dvcs history does
not contain anything confidential (or libellous). Also, all files which
-contain secrets are in the dvcs's C<.ignore> file. See
+contain secrets are in the dvcs's I<.ignore> file. See
C<srcdump_vcsscript_git> et al.
=item *
=item *
-You don't intentionally load Perl code by virtule of C<.>
+You don't intentionally load Perl code by virtue of C<.>
being in C<@INC> by default. (See C<srcdump_filter_cwd>.)
=back
The arguments are setting pairs like a hash initialiser.
See L</SETTINGS> below.
-=item C<< $verifier->new_request($cgi_query) >>
+=item C<< $verifier->new_request($cgi) >>
-Prepares to process a request. C<$cgi_query> should normally
+Prepares to process a request. I<$cgi> should normally
be the query object from L<CGI(3perl)>. Most of the default
hook methods assume that it is; however if you replace enough of
the hook methods then you can pass any value you like and it
will be passed to your hooks.
-The return value is the authentication request object (C<$authreq>)
+The return value is the authentication request object (I<$authreq>)
which is used to check the incoming request and will contain
information about its credentials.
Discards the resources (open files, etc.) in the verifier object.
=back
+
+=head 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.)
+
+=item C<< $authreq->get_divert() >>
+
+Returns the value previously returned by C<check_divert>.
+
+=item C<< $authreq->get_username() >>
+
+Returns the name of the logged-in user. If the user was not logged
+in (or their session had timed out, or something), returns undef.
+
+=item C<< $authreq->check_mutate() >>
+
+Declares to CGI::Auth::Generic that the request being handled will
+"mutate". That is, it will modify some server-side state (eg, adding
+items to shopping baskets, posting messages to blogs, sending emails,
+or whatever).
+
+If you have set the setting C<promise_check_mutate> you must call
+C<check_mutate> whenever appropriate. If you haven't then it's
+irrelevant. See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
+
+C<check_mutate> will either return successfully, indicating that all
+is well and the request should proceed, or it will die. If it dies
+that means that the request was improper, which can only result from a
+bug or an attack. So an "internal server error" is a suitable
+response.
+
+=item C<< $authreq->check_nonpage($method, $reqtype) >>
+
+Declares to CGI::Auth::Generic that the request is not a page request,
+but rather a request of type I<$reqtype>.
+
+If your application has set the setting C<promise_check_mutate>,
+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
+is well and the request should proceed, or it will die, like
+C<check_mutate>.
+
+=head RESPONSE-RELATED FUNCTIONS AND METHODS
+
+=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.
+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
+parameter in a single request; normally each arrayref would be a
+singleton.)
+
+The request path will be the path to the application. If a parameter
+with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
+value will be appended to the application path. (It should normally
+start with C<< / >>, and only one value should be supplied.)
+
+=item C<< something->need_add_hidden($method, $reqtype) >>
+
+Enquires whether a request of type I<$reqtype> using HTTP method
+I<$method> needs the hidden form parameter. See L</REQUEST TYPES>.
+
+=item C<< something->secret_hidden_val() >>
+
+Returns the value of the hidden form parameter. This should be
+included in all POST requests to your application (and thus be a
+hidden form parameter in all forms).
+
+It should also be in some (maybe all) GET requests. If your
+application is mutation-ignorant, it should be in all GET requests.
+If you are mutation-aware, you need to consult C<need_add_hidden>.
+
+The name of the hidden parameter is the setting C<assoc_param_name>,
+C<caf_hassochash> by default. xxx rename param and setting
+
+=item C<< something->secret_hidden_html() >>
+
+Returns the HTML for an C<INPUT> element specifying the hidden form
+parameter.
+
+=item C<< something->secret_cookie_val() >>
+
+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
+
+=over
+
+=item C<< $verifier_or_authreq->hash($data) >>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
+=item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
+
+Updates CGI::Auth::Generic's knowledge about the various kinds of
+request, and whether they need the hidden form parameter. This
+function applies only to GET requests - POST requests always use the
+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,
+or other users, to assign a unique request type name.
+
+This method may be called on an authreq or a verifier, in which case
+it will affect all authreqs using the same verifier. Or it may be
+called on the class as a whole, in which case it will affect the
+global default list for all verifiers.
+
+If I<$force> is supplied and true, this will override
+CGI::Auth::Flexible's existing knowledge. Otherwise this new setting
+will be ignored if CGI::Auth::Flexible already knows about the request
+type. (When called on a verifier or authreq, it will ignore the
+update in favour of existing knowledge recorded both globally in the
+class or due to previous requests on the same verifier.)
+
+See L</REQUEST TYPES>.
+
+=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
+=back
+
+=head1 SETTINGS
+
+C<new_verifier> and C<new_request> each take a list of settings, as
+a list of pairs C<< key => value >> (like a Perl hash assignment).
+
+The settings supplied to C<new_verifier> are stored in the verifier
+and will apply to all authreqs made from it unless overridden in the
+call to C<new_request>
+
+When a setting is described as a hook function, it should be a
+coderef. The first argument will be the query object from
+L<CGI(3perl)> (strictly, it will be whatever value was passed to
+C<new_request>). The second argument will be the authreq object (the
+return value from C<new_request>).
+Ie, C<< sub some_hook ($$...) { my ($cgi,$authreq,@stuff) = @_ ... >>
+
+In bullet point headings, the hook functions are shown in the form
+C<< some_hook($cgi,$authreq,@stuff) >> even though this would not be
+legal syntax. This should be read to mean that the
+%implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
+would be a legal call. (However, the settings hash is not exposed.)
+
+=over
+
+=head2 GENERAL SETTINGS
+
+=item C<dir>
+
+The directory CGI::Auth::Generic should use for its data storage.
+This is actually just a default absolute path used when the other
+path settings are relative values.
+
+Must be an absolute filename.
+
+=item C<assocdb_dbh>
+
+CGI::Auth::Flexible needs a database for recording users' login
+session. This database needs to be shared across all instances of the
+web application, so in a multi-node cluster it needs to be your actual
+database.
+
+CGI::Auth::Flexible will create the table and index it needs if they
+don't already exist, and will manage their contents. You do not need
+to integrate them into the rest of your webapp's data storage. (In
+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
+applications which run on a single host.
+
+This value, if supplied, should be a DBI handle for the database.
+
+=item C<assocdb_dsn>
+
+This is the DSN to pass to C<< DBI->connect >>. Used only if
+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.
+
+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>
+
+Prefix for the SQL tables and indices to use (and to create, if
+necessary).
+
+See L</DATABASE TABLES>.
+
+=item C<keys_path>
+
+Path to the keys file used by CAF. This arrangement will change in
+the future. See L</BUGS>.
+
+=item C<random_source>
+
+Special file to read random numbers from. Should return
+cryptographically secure (pseudo)-random bytes, unpredictable to
+adversaries (even ones on the same machine).
+
+On Linux, there is no device which is properly suitable. This is a
+bug in Linux. You can use C</dev/random> which can block
+unnecessarily even though the kernel PRNG has been properly seeded and
+is fine, or C</dev/urandom> which might return values which attackers
+can predict if the kernel PRNG has not been properly seeded.
+
+The default is C</dev/urandom>.
+
+=item C<secretbits>
+
+Length of the assoc secret. Defaults to 128.
+
+=item C<hash_algorithm>
+
+Must be a string suitable for use with C<new Digest>.
+Defaults to C<SHA-256>.
+
+=item C<login_timeout>
+
+A user will be logged out this many seconds after they first logged
+in. Default: 86400 (one day).
+
+=item C<login_form_timeout>
+
+A login form becomes invalid this many seconds after it has been sent.
+Default: 3600 seconds (one hour).
+
+=item C<key_rollover>
+
+The key used for generating assoc secrets is rolled over approximately
+this often (in seconds). Default: 86400.
+
+=item C<assoc_param_name>
+
+Name of the hidden form parameter. Default: C<caf_assochash>.
+
+=item C<cookie_name>
+
+Name of the cookie used for login sessions. Default:
+C<caf_assocsecret>.
+
+=item C<password_param_name>
+
+Name of the password field in the login form. Default: C<password>.
+
+Used by C<login_ok_password> (the default C<login_ok> hook),
+C<gen_plain_login_form> and the default C<is_login> hook.
+
+=item C<username_param_names>
+
+Arrayref of name(s) of username form parameters.
+
+The first entry is used by C<login_ok_password> (the default
+C<login_ok> hook) to pass to the C<username_password_error> hook and
+used as the username if all is well.
+
+All the entries are used by C<gen_plain_login_fork> (the default
+C<gen_login_form> hook for C<check_ok>) to generate form entry fields.
+
+The default is C<['username']>.
+
+=item C<logout_param_names>
+
+Arrayref of name(s) of form parameters indicating that the request is
+a logout request.
+
+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" ...>>
+
+The default is C<['caf_logout']>
+
+=item C<logged_param_names>
+
+Arrayref of name(s) of form parameters indicating that user has just
+logged out. (During the logout process, the actual logout action is a
+POST request, whose response redirects to the "you have been logged
+out" page; these form parameters are for this second page.)
+
+Used by the default C<is_loggedout> hook.
+
+The first entry is used by C<check_ok> to generate the redirection.
+
+The default is C<['caf_loggedout']>
+
+=item C<promise_check_mutate>
+
+Boolean. If true, is a declaration by the application that it is
+mutatin-aware. See L</MUTATING OPERATIONS AND EXTERNAL LINKS>.
+
+The default is 0.
+
+=item C<encrypted_only>
+
+Boolean. If true, CAF will insist that all transactions be done over
+an encrypted http connection. It will redirect unencrypted requests
+to the https instance of the applicattion, and will set the encrypted
+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
+call C<< $cgi->url() >> for each request, but you can fix this if you
+prefer.
+
+=item C<< is_login,is_logout,is_loggedout($cgi,$authreq) >>
+
+Hook which returns a boolean indicating whether the request was,
+respectively: a login form submission (ie, username and password); a
+logout request (submission resulting from the user pressing the
+"logout" button); "logged out" page (redirection from the logout
+POST).
+
+The default is to check whether any of the corresponding request
+parameters (C<< login_param_names >> etc.) was supplied, using the
+C<get_param> hook.
+
+=back
+
+=head2 SETTINGS (HOOKS) RELATED TO THE CGI REQUEST OBJECT
+
+=over
+
+=item C<< get_param($cgi,$authreq,$param) >>
+
+Returns the value of a single-valued form parameter.
+The default is to call C<< $cgi->param($param) >>.
+The semantics are the same as that of C<CGI::param>.
+
+=item C<< get_params($cgi,$authreq) >>
+
+Returns a hash of the parameters. The return value is a hashref whose
+keys are the parameter names and whose values are arrayrefs, one entry
+in the arrayref for each value.
+
+The default is to call C<< $cgi->Vars() >>, expect the
+results to look like those from C<CGI::Vars>, and massage them into
+the required form with split.
+
+=item C<< get_path_info($cgi,$authreq) >>
+
+Returns the PATH_INFO of the request. The default is to
+call C<< $cgi->path_info() >>.
+
+=item C<< get_cookie($cgi,$authreq) >>
+
+Returns the value of the CAF cookie sent with the request, or undef if
+none was supplied. The default is to call C<<
+$cgi->cookie($cookie_name) >> (where C<$cookie_name> is from the
+setting of the same name). The return value should be the scalar
+value of the cookie.
+
+=item C<< get_method($cgi,$authreq) >>
+
+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
+channel. The default is C<< !!$cgi->https() >>. See C<encrypted_only>.
+
+=back
+
+=head2 SETTINGS RELATED TO HTML GENERATION
+
+These are only used if you call C<check_ok> or xxx some other functions?.
+
+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<check_ok> (or, in turn, other hooks, or your application). These
+are often documented simply by showing the output produced. In many
+cases parts of the output are in turn obtained from other hooks. In
+some cases the default implementations have been given names for
+convenient use by your application. They will be called in array
+context.
+
+We'll write C<gettext(something)> even though actually there is a hook
+to control the translation function used.
+
+=over
+
+=item C<handle_divert>($cgi,$authreq,$divert))
+
+C<check_ok> calls this hook before producing output of its own. If
+you want to handle some but not all diversions yourself, you may set
+this hook. The hook should either do nothing and return false, or
+return true if it has handled the request (or arrange for the request
+to be handled). If the hook returns true then C<check_ok> simply
+returns 0.
+
+=item C<gen_login_form>($cgi,$authreq,$divert))
+
+Default: a table (used mostly for layout) containing input fields for
+a login form. Must be within a C<< <form> >> element, but doesn't
+generate it. Has text fields for every entry in
+C<username_param_names> (in each case associated with a description
+C<< gettext(ucfirst $parameter_name) >>, a password field (with
+description C<gettext("Password")>, and a login submit button (with
+description C<gettext("Login")>.
+
+Default is available as the class function C<gen_plain_login_form>.
+
+=item C<gen_login_link>($cgi,$authreq))
+
+Default:
+
+ <a href="http:...">gettext(Log in again to continue.)</a>
+
+Default is available as the class function C<gen_plain_login_link>.
+
+=item C<gen_postmainpage_form>($cgi,$authreq,$params))
+
+Default: form contents (but not the C<< <form> >> element):
+
+C<$params> (in the form returned by the C<get_params> hook) as hidden
+fields, and also:
+
+ <input type="submit" ... value=getext('Continue')>
+
+Default is available as the class function C<gen_postmainpage_form>.
+
+=item C<gen_start_html>($cgi,$authreq,$title)
+
+Default: C<$cgi->start_html($title)>
+
+=item C<gen_end_html>($cgi,$authreq,$title)
+
+Default: C<$cgi->end_html($title)>
+
+=item C<gen_footer_html>($cgi,$authreq)>
+
+Default:
+
+ <hr><address>
+ Powered by Free / Libre / Open Source Software
+ according to the [gen_licence_link_html].
+ [gen_source_link_html].
+ </address>
+
+Default is available as the class function C<gen_plain_footer_html>.
+
+=item C<gen_licence_link_html>($cgi,$authreq)>
+
+Default: uses C<url_with_query_params> to generate a URL for
+downloading the licence, and returns:
+ <a href="...">GNU Affero GPL</a>
+
+Default is available as the class function C<gen_plain_licence_link_html>.
+
+=item C<gen_source_link_html>($cgi,$authreq)>
+
+Default: uses C<url_with_query_params> to generate a URL for
+downloading the source, and returns:
+ <a href="...">Source available</a>
+
+Default is available as the class function C<gen_plain_source_link_html>.
+
+=item C<form_entry_size>
+
+Size of generated text entry fields. Default is 60.
+
+=item C<dummy_param_name_prefix>
+
+Some of CAF's HTML-generating functions need to invent form parameter
+names. They will all start with this string. Default: C<caf__>.
+
+=head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
+
+=over
+
+=item C<srcdump_param_name>
+
+Form parameter name used to indicate that this is a source download
+request. If this parameter is supplied, C<check_ok> and
+C<check_divert> will arrange for the applicaton source code to be
+delivered as the response (in C<check_ok>'s case by doing it itself
+and in C<check_divert>'s case by asking your application to do so.
+
+Default is C<caf_srcdump>.
+
+=item C<srcdump_path>
+
+Path to the directory used for storing pre-prepared source downloads.
+Defaults to C<caf-srcdump>.
+
+If this is a relative path, it is in C<dir>.
+
+=back
+
+
+=head1 DATABASE TABLES
+
+In a simple application, you do not need to worry about this. But if
+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.
+
+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 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