5 CGI::Auth::Flexible - web authentication optionally using cookies
9 my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...);
10 my $authreq = $verifier->new_request($cgi);
13 $authreq->check_ok() or return;
15 # sophisticated applications
16 my $divert_kind = $authreq->check_divert();
17 if ($divert_kind) { ... print diversion page and quit ... }
19 # while handling the request
20 $user = $authreq->get_username();
21 $authreq->check_mutate();
25 CGI::Auth::Flexible is a library which you can use to add a
26 forms/cookie-based login facility to a Perl web application.
28 CGI::Auth::Flexible doesn't interfere with your application's URL path
29 namespace and just needs a few (configurable) form parameter and
30 cookie name(s) for its own use. It tries to avoid making assumptions
31 about the implementation structure of your application.
33 Because CGI::Auth::Flexible is licenced under the AGPLv3, you will
34 probably need to provide a facility to allow users (even ones not
35 logged in) to download the source code for your web app. Conveniently
36 by default CGI::Auth::Flexible provides (for pure Perl webapps) a
37 mechanism for users to get the source.
39 CGI::Auth::Flexible is designed to try to stop you accidentally
40 granting access by misunderstanding the API. (Also it, of course,
41 guards against cross-site scripting.) You do need to make sure to
42 call CGI::Auth::Flexible before answering AJAX requests as well as
43 before generating HTML pages, of course, and to call it in every
44 entrypoint to your system.
48 As a minimum you need to do all of the things on this checklist, where
49 applicable. The items marked SECURITY are the ones that you might
50 forget: without them your application may appear to work, but will be
57 Call C<new_verifier> (once at application startup)
61 Call C<new_request> (once per request)
65 B<SECURITY>: Call C<check_ok> or C<check_divert> on every request, and
66 honour the return value.
70 If you're using C<check_ok>, implement either the
71 C<username_password_error> or C<login_ok> hook and provide it as
72 a setting to C<new_verifier>.
76 Provide the setting C<dir> (or provide absolute paths for all the
77 other relevant settings).
81 Call C<get_username> when you need to know who's logged in.
85 B<SECURITY>: Call C<check_mutate> or C<mutate_ok>, if you specified
86 C<promise_check_mutate>.
90 B<SECURITY>: Call C<check_nonpage> for every request which is not a page load
91 (if your application has any of those).
95 When generating URLs and forms (including AJAX requests), include the
96 hidden form parameter using C<secret_hidden_val> or
97 C<secret_hidden_html> when appropriate (see below).
101 B<SECURITY>: If you do not override the source provision facility (see
102 L</SOURCE CODE DOWNLOAD>), check that the assumptions it makes aren't
103 going to leak security-critical data.
107 Set up HTTPS on your webserver, or set the C<encrypted_only> setting
112 These points will now be covered in more detail.
114 =head2 INITIALISATION
116 Your application should, on startup (eg, when it is loaded by
118 C<< $verifier = CGI::Auth::Flexible->new_verifier(settings...) >>.
119 This call can be expensive and is best amortised.
121 The resulting verifier object can be used to process individual
122 requests, in each case with
123 C<< $authreq = CGI::Auth::Flexible->new_request($cgi) >>.
127 =head2 CHECKING AND RESPONSE GENERATION
129 If the user is logged in, your application is to handle the request.
130 Otherwise, the user needs to be presented with a login form or error
131 message, as appropriate. CGI::Auth::Flexible provides two alternative
134 =head3 Simple applications
136 The simplist usage is to call C<< $request->check_ok() >> which will
137 check the user's authentication. If the user is not logged in it will
138 generate a login form (or redirection or other appropriate page) and
139 return false; your application should not then processing that request
140 any further. If the user is logged in it will return true.
142 Various hooks are provided to customise the responses generated by
145 After C<check_ok> returns true you should go ahead and process the
146 request; you can use C<< $request->get_username >> to find out which
147 user the request came from.
149 =head2 Sophisticated applications
151 If you want to handle the control flow and to generate login forms,
152 redirections, etc., yourself, you can say
153 C<< $divert = $request->check_divert >>. This returns undef if
154 the user is logged in, or I<divert spec> if some kind of login
155 page or diversion should be generated. See L</DIVERT SPEC> below for
156 details of how to deal with the return value.
158 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS
160 =head3 Mutation-ignorant applications
162 By default CGI::Auth::Flexible does not permit external links into
163 your site. All GET requests give a "click to continue" page which
164 submits a form which loads your app's main page. In this
165 configuration all your application's forms and AJAX requests should
166 use C<POST>. This restriction arises from complicated deficiencies
167 in the web's security architecture.
169 Such applications are also not able to provide user-specific CSS
170 stylesheets, javascript, favicons, etc.
172 =head3 Mutation-aware applications
174 The alternative is for your application to always make a special check
175 when the incoming request is going to do some kind of action (such as
176 modifying the user's setup, purchasing goods, or whatever) rather than
177 just retrieve and/or display information. We term such requests
180 Then non-mutating pages can be linked to from other, untrustworthy,
183 To support external links, and C<GET> requests, pass
184 C<< promise_check_mutate => 1 >> in I<settings>, and then call
185 C<< $authreq->check_mutate() >> before taking any actions. If the
186 incoming request is not suitable then C<< $authreq->check_mutate() >>
189 There have to be no mutating C<GET> requests in your application (but
190 you shouldn't have any of those anyway); if there are, they won't
191 work. (CGI::Auth::Flexible will spot them and cause them to fail,
192 rather than allow them to be insecure.)
194 =head2 GENERATING URLS, FORMS AND AJAX QUERIES
196 When you generate a URL, C<POST> form or AJAX request you may need to
197 include a secret hidden form parameter for the benefit of
198 CGI::Auth::Generic. This form parameter will be checked by
199 C<check_ok>/C<check_divert> and should be ignored by your application.
201 By default the hidden parameter is called C<caf_assochash>.
203 After calling C<check_ok> or C<check_divert> the value to put in your
204 form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
205 will generate the whole HTML C<< <input...> >> element.
207 =head3 Mutation-ignorant applications
209 For mutation-ignorant applications (see above), all forms etc. should
210 include the hidden parameter (and as discussed, they must all use
211 POST rather than GET).
213 =head3 Mutation-aware applications
215 For mutation-aware applications, whether to include the secret
216 parameter depends on the kind of request. CGI::Auth::Flexible knows
217 when it is necessary. You should find out by calling
220 If it is inconvenient to call C<need_add_hidden> at runtime, you can
221 rely instead on the following promises: All POST requests (which
222 includes all mutating requests) need the parameter. The return value
223 of need_add_hidden depends only on the $method and $reqtype
224 parameters, so you can query it once and remember the answer.
225 HTML page load GETs do not need the parameter. It is better to
226 err on the side of including the parameter.
228 If you really must, you can call C<need_add_hidden> "on the bench"
229 during development and bake the answer into your application code
230 structure. However, if you do that and a new vulnerability was
231 discovered which is fixed by changing the answer, updating
232 CGI::Auth::Flexible wouldn't be sufficient to fix it.
234 =head3 Mutation-aware applications - non-page requests
236 If your mutation-aware application supports non-page resources (AJAX
237 and JSON requests, stylesheets, favicons, etc.) it must inform
238 CGI::Auth::Flexible when it is handling such a request, by calling
241 Normally C<check_nonpage> will simply return (and you can ignore the
242 return value). However, if there is an attack (or, perhaps, a bug) it
243 will die, stopping the attack.
245 (You do not need to call C<check_nonpage> for POST requests, but it is
248 =head3 Mutation-aware applications - novel kinds of request
250 If you want to support a kind of request perhaps not yet known about
251 by CGI::Auth::Flexible, you can provide information about that new
252 request kind using C<update_get_need_add_hidden>.
256 CGI::Auth::Flexible needs to store various information in plain files;
257 it does this in the directory specified by the C<dir> parameter.
259 =head1 SOURCE CODE DOWNLOAD
261 By default, CGI::Auth::Flexible provides a facility for users to
262 download the source code for the running version of your web
265 This facility makes a number of important assumptions which you need
266 to check. Note that if the provided facility is not sufficient
267 because your application is more sophisticated than it copes with (or
268 if you disable the builtin facility), you may need to implement a
269 functioning alternative to avoid violating the AGPLv3 licence.
271 Here are the most important (default) assumptions:
277 Your app's source code is available by looking at @INC, $0 and
278 S<$ENV{'SCRIPT_FILENAME'}> (the B<source items>). See
279 C<srcdump_listitems>. Where these point to files or directories under
280 revision control, the source item is the whole containing vcs tree.
284 Specifically, there are no compiled or autogenerated Perl
285 files, Javascript resources, etc., which are not contained in one of
286 the source item directories. (Files which came with your operating
287 system install don't need to be shipped as they fall under the system
292 You have not installed any modified versions of system
293 libraries (including system-supplied Perl modules) in C</usr> outside
294 C</usr/local>. See C<srcdump_system_dir>.
298 For each source item in a dvcs, the entire dvcs history does
299 not contain anything confidential (or libellous). Also, all files which
300 contain secrets are in the dvcs's I<.ignore> file. See
301 C<srcdump_vcsscript_git> et al.
305 For each source item NOT in a dvcs, there are no confidential
306 files with the world-readable bit set (being in a world-inaccessible
307 directory is not sufficient). See C<srcdump_excludes>.
311 You have none of your app's source code in C</etc>.
315 You don't regard pathnames on your server as secret.
319 You don't intentionally load Perl code by virtue of C<.>
320 being in C<@INC> by default. (See C<srcdump_filter_cwd>.)
324 =head1 MAIN FUNCTIONS AND METHODS
328 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
330 Initialises an instance and returns a verifier object.
331 The arguments are setting pairs like a hash initialiser.
332 See L</SETTINGS> below.
334 =item C<< $verifier->new_request($cgi) >>
336 Prepares to process a request. I<$cgi> should normally
337 be the query object from L<CGI(3perl)>. Most of the default
338 hook methods assume that it is; however if you replace enough of
339 the hook methods then you can pass any value you like and it
340 will be passed to your hooks.
342 The return value is the authentication request object (I<$authreq>)
343 which is used to check the incoming request and will contain
344 information about its credentials.
346 =item C<< $authreq->check_divert() >>
348 Checks whether the user is logged in. Returns undef if the user is
349 logged in and we should service the request. Otherwise returns a
350 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
352 This method may die if it doesn't like the request, in which case
353 the request needs to be rejected.
355 =item C<< $authreq->check_ok() >>
357 Checks whether the user is logged in. Returns true if the user is
358 logged in and we should service the request.
360 Otherwise it handles the request itself, generating any appropriate
361 redirect, login form, or continuation page. It then returns false and
362 the application should not process the request further.
364 =item C<< $verifier->disconnect() >>
366 Discards the resources (open files, etc.) in the verifier object.
370 =head REQUEST-RELATED FUNCTIONS AND METHODS
372 All of these are only valid after C<check_divert> or C<check_ok> has
373 been called. (In the case of C<check_ok> it won't normally be sensible
374 to call these functions unless C<check_ok> returned true.)
376 =item C<< $authreq->get_divert() >>
378 Returns the value previously returned by C<check_divert>.
380 =item C<< $authreq->get_username() >>
382 Returns the name of the logged-in user. If the user was not logged
383 in (or their session had timed out, or something), returns undef.
385 =item C<< $authreq->check_mutate() >>
387 Declares to CGI::Auth::Generic that the request being handled will
388 "mutate". That is, it will modify some server-side state (eg, adding
389 items to shopping baskets, posting messages to blogs, sending emails,
392 If you have set the setting C<promise_check_mutate> you must call
393 C<check_mutate> whenever appropriate. If you haven't then it's
394 irrelevant. See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
396 C<check_mutate> will either return successfully, indicating that all
397 is well and the request should proceed, or it will die. If it dies
398 that means that the request was improper, which can only result from a
399 bug or an attack. So an "internal server error" is a suitable
402 =item C<< $authreq->check_nonpage($method, $reqtype) >>
404 Declares to CGI::Auth::Generic that the request is not a page request,
405 but rather a request of type I<$reqtype>.
407 If your application has set the setting C<promise_check_mutate>,
408 whenever it is handling anything except an HTML page loads, it must
409 call this function. See L</REQUEST TYPES>, and
410 L<GENERATING URLS, FORMS AND AJAX QUERIES>.
412 C<check_mutate> will either return successfully, indicating that all
413 is well and the request should proceed, or it will die, like
416 =head RESPONSE-RELATED FUNCTIONS AND METHODS
418 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
420 Convenience function which returns a url for a GET request to this
423 I<$params> is a hashref specifying the parameters and the PATH_INFO.
424 The keys are the parameter names, and the values are array refs with
425 the parameter value(s) (as strings, as yet unquoted). (They are array
426 refs because it is possible to pass multiple values for the same
427 parameter in a single request; normally each arrayref would be a
430 The request path will be the path to the application. If a parameter
431 with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
432 value will be appended to the application path. (It should normally
433 start with C<< / >>, and only one value should be supplied.)
435 =item C<< something->need_add_hidden($method, $reqtype) >>
437 Enquires whether a request of type I<$reqtype> using HTTP method
438 I<$method> needs the hidden form parameter. See L</REQUEST TYPES>.
440 =item C<< something->secret_hidden_val() >>
442 Returns the value of the hidden form parameter. This should be
443 included in all POST requests to your application (and thus be a
444 hidden form parameter in all forms).
446 It should also be in some (maybe all) GET requests. If your
447 application is mutation-ignorant, it should be in all GET requests.
448 If you are mutation-aware, you need to consult C<need_add_hidden>.
450 The name of the hidden parameter is the setting C<assoc_param_name>,
451 C<caf_hassochash> by default. xxx rename param and setting
453 =item C<< something->secret_hidden_html() >>
455 Returns the HTML for an C<INPUT> element specifying the hidden form
458 =item C<< something->secret_cookie_val() >>
460 Returns the value of the secret cookie. CGI::Auth::Flexible sets this
461 cookie in the forms generated by C<check_ok>. You may also set it
462 yourself (and indeed you must do so if you use C<check_divert>).
464 =item C<< $authreq->chain_params() >>
466 Returns a hash of the "relevant" parameters to this request, in a form
467 used by XXX. This is all of the query parameters which are not
468 related to CGI::Auth::Flexible. The PATH_INFO from the request is
469 returned as the parameter C<< '' >>.
471 xxx why use this function
475 =head OTHER FUNCTIONS AND METHODS
479 =item C<< $verifier_or_authreq->hash($data) >>
481 Hashes the supplied data using the hash function specified by the
482 C<hash_algorithm> setting, and converts the result to a string of hex
485 =item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
487 Updates CGI::Auth::Generic's knowledge about the various kinds of
488 request, and whether they need the hidden form parameter. This
489 function applies only to GET requests - POST requests always use the
492 I<$reqtype> is the request type (the value which will be passed to
493 C<check_nonpage> and C<need_add_hidden>. If you are supporting a new
494 I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
495 or other users, to assign a unique request type name.
497 This method may be called on an authreq or a verifier, in which case
498 it will affect all authreqs using the same verifier. Or it may be
499 called on the class as a whole, in which case it will affect the
500 global default list for all verifiers.
502 If I<$force> is supplied and true, this will override
503 CGI::Auth::Flexible's existing knowledge. Otherwise this new setting
504 will be ignored if CGI::Auth::Flexible already knows about the request
505 type. (When called on a verifier or authreq, it will ignore the
506 update in favour of existing knowledge recorded both globally in the
507 class or due to previous requests on the same verifier.)
509 See L</REQUEST TYPES>.
511 =item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
513 Hashes the supplied data using the hash function specified by the
514 C<hash_algorithm> setting, and converts the result to a string of hex
521 C<new_verifier> and C<new_request> each take a list of settings, as
522 a list of pairs C<< key => value >> (like a Perl hash assignment).
524 The settings supplied to C<new_verifier> are stored in the verifier
525 and will apply to all authreqs made from it unless overridden in the
526 call to C<new_request>
528 When a setting is described as a hook function, it should be a
529 coderef. The first argument will be the query object from
530 L<CGI(3perl)> (strictly, it will be whatever value was passed to
531 C<new_request>). The second argument will be the authreq object (the
532 return value from C<new_request>).
533 Ie, C<< sub some_hook ($$...) { my ($cgi,$authreq,@stuff) = @_ ... >>
535 In bullet point headings, the hook functions are shown in the form
536 C<< some_hook($cgi,$authreq,@stuff) >> even though this would not be
537 legal syntax. This should be read to mean that the
538 %implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
539 would be a legal call. (However, the settings hash is not exposed.)
543 =head2 GENERAL SETTINGS
547 The directory CGI::Auth::Generic should use for its data storage.
548 This is actually just a default absolute path used when the other
549 path settings are relative values.
551 Must be an absolute filename.
555 CGI::Auth::Flexible needs a database for recording users' login
556 session. This database needs to be shared across all instances of the
557 web application, so in a multi-node cluster it needs to be your actual
560 CGI::Auth::Flexible will create the table and index it needs if they
561 don't already exist, and will manage their contents. You do not need
562 to integrate them into the rest of your webapp's data storage. (In
563 particular, there is no need for transactional integrity across
564 changes made by CAF and your own application.)
566 By default, CAF uses a sqlite3 database stored on local disk in the
567 file named by C<assocdb_path>. This will be suitable for all
568 applications which run on a single host.
570 This value, if supplied, should be a DBI handle for the database.
574 This is the DSN to pass to C<< DBI->connect >>. Used only if
575 C<assocdb_dbh> is not supplied.
577 =item C<assocdb_path>
579 Path to the sqlite3 database used for CAF's session storage. The
580 default is currently C<caf-assocs.db> but will change in the future.
582 Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
584 If this is a relative path, it is in C<dir>.
586 =item C<assocdb_table>
588 Prefix for the SQL tables and indices to use (and to create, if
591 See L</DATABASE TABLES>.
595 Path to the keys file used by CAF. This arrangement will change in
596 the future. See L</BUGS>.
598 =item C<random_source>
600 Special file to read random numbers from. Should return
601 cryptographically secure (pseudo)-random bytes, unpredictable to
602 adversaries (even ones on the same machine).
604 On Linux, there is no device which is properly suitable. This is a
605 bug in Linux. You can use C</dev/random> which can block
606 unnecessarily even though the kernel PRNG has been properly seeded and
607 is fine, or C</dev/urandom> which might return values which attackers
608 can predict if the kernel PRNG has not been properly seeded.
610 The default is C</dev/urandom>.
614 Length of the assoc secret. Defaults to 128.
616 =item C<hash_algorithm>
618 Must be a string suitable for use with C<new Digest>.
619 Defaults to C<SHA-256>.
621 =item C<login_timeout>
623 A user will be logged out this many seconds after they first logged
624 in. Default: 86400 (one day).
626 =item C<login_form_timeout>
628 A login form becomes invalid this many seconds after it has been sent.
629 Default: 3600 seconds (one hour).
631 =item C<key_rollover>
633 The key used for generating assoc secrets is rolled over approximately
634 this often (in seconds). Default: 86400.
636 =item C<assoc_param_name>
638 Name of the hidden form parameter. Default: C<caf_assochash>.
642 Name of the cookie used for login sessions. Default:
645 =item C<password_param_name>
647 Name of the password field in the login form. Default: C<password>.
649 Used by C<login_ok_password> (the default C<login_ok> hook),
650 C<gen_plain_login_form> and the default C<is_login> hook.
652 =item C<username_param_names>
654 Arrayref of name(s) of username form parameters.
656 The first entry is used by C<login_ok_password> (the default
657 C<login_ok> hook) to pass to the C<username_password_error> hook and
658 used as the username if all is well.
660 All the entries are used by C<gen_plain_login_fork> (the default
661 C<gen_login_form> hook for C<check_ok>) to generate form entry fields.
663 The default is C<['username']>.
665 =item C<logout_param_names>
667 Arrayref of name(s) of form parameters indicating that the request is
670 Used by the default C<is_logout> hook.
672 If you want users to be able to explicitly log out, you need to
673 provide a logout button, something like
674 C<< <input type="submit" name="caf_logout" ...>>
676 The default is C<['caf_logout']>
678 =item C<logged_param_names>
680 Arrayref of name(s) of form parameters indicating that user has just
681 logged out. (During the logout process, the actual logout action is a
682 POST request, whose response redirects to the "you have been logged
683 out" page; these form parameters are for this second page.)
685 Used by the default C<is_loggedout> hook.
687 The first entry is used by C<check_ok> to generate the redirection.
689 The default is C<['caf_loggedout']>
691 =item C<promise_check_mutate>
693 Boolean. If true, is a declaration by the application that it is
694 mutatin-aware. See L</MUTATING OPERATIONS AND EXTERNAL LINKS>.
698 =item C<encrypted_only>
700 Boolean. If true, CAF will insist that all transactions be done over
701 an encrypted http connection. It will redirect unencrypted requests
702 to the https instance of the applicattion, and will set the encrypted
703 only flag on its cookie.
709 =item C<< get_url($cgi,$authreq) >>
711 Hook which returns the URL of this web application. By default, we
712 call C<< $cgi->url() >> for each request, but you can fix this if you
715 =item C<< is_login,is_logout,is_loggedout($cgi,$authreq) >>
717 Hook which returns a boolean indicating whether the request was,
718 respectively: a login form submission (ie, username and password); a
719 logout request (submission resulting from the user pressing the
720 "logout" button); "logged out" page (redirection from the logout
723 The default is to check whether any of the corresponding request
724 parameters (C<< login_param_names >> etc.) was supplied, using the
729 =head2 SETTINGS (HOOKS) RELATED TO THE CGI REQUEST OBJECT
733 =item C<< get_param($cgi,$authreq,$param) >>
735 Returns the value of a single-valued form parameter.
736 The default is to call C<< $cgi->param($param) >>.
737 The semantics are the same as that of C<CGI::param>.
739 =item C<< get_params($cgi,$authreq) >>
741 Returns a hash of the parameters. The return value is a hashref whose
742 keys are the parameter names and whose values are arrayrefs, one entry
743 in the arrayref for each value.
745 The default is to call C<< $cgi->Vars() >>, expect the
746 results to look like those from C<CGI::Vars>, and massage them into
747 the required form with split.
749 =item C<< get_path_info($cgi,$authreq) >>
751 Returns the PATH_INFO of the request. The default is to
752 call C<< $cgi->path_info() >>.
754 =item C<< get_cookie($cgi,$authreq) >>
756 Returns the value of the CAF cookie sent with the request, or undef if
757 none was supplied. The default is to call C<<
758 $cgi->cookie($cookie_name) >> (where C<$cookie_name> is from the
759 setting of the same name). The return value should be the scalar
762 =item C<< get_method($cgi,$authreq) >>
764 Returns the HTTP method as a string. The default is to call
765 C<< $cgi->request_method() >>.
769 =item C<< is_https($cgi,$authreq) >>
771 Returns a boolean indicating whether the request was over an encrypted
772 channel. The default is C<< !!$cgi->https() >>. See C<encrypted_only>.
776 =head2 SETTINGS RELATED TO HTML GENERATION
778 These are only used if you call C<check_ok> or xxx some other functions?.
780 Settings whose names are of the form C<gen_...> are hooks which each
781 return an array of strings, normally HTML strings, for use by
782 C<check_ok> (or, in turn, other hooks, or your application). These
783 are often documented simply by showing the output produced. In many
784 cases parts of the output are in turn obtained from other hooks. In
785 some cases the default implementations have been given names for
786 convenient use by your application. They will be called in array
789 We'll write C<gettext(something)> even though actually there is a hook
790 to control the translation function used.
794 =item C<handle_divert>($cgi,$authreq,$divert))
796 C<check_ok> calls this hook before producing output of its own. If
797 you want to handle some but not all diversions yourself, you may set
798 this hook. The hook should either do nothing and return false, or
799 return true if it has handled the request (or arrange for the request
800 to be handled). If the hook returns true then C<check_ok> simply
803 =item C<gen_login_form>($cgi,$authreq,$divert))
805 Default: a table (used mostly for layout) containing input fields for
806 a login form. Must be within a C<< <form> >> element, but doesn't
807 generate it. Has text fields for every entry in
808 C<username_param_names> (in each case associated with a description
809 C<< gettext(ucfirst $parameter_name) >>, a password field (with
810 description C<gettext("Password")>, and a login submit button (with
811 description C<gettext("Login")>.
813 Default is available as the class function C<gen_plain_login_form>.
815 =item C<gen_login_link>($cgi,$authreq))
819 <a href="http:...">gettext(Log in again to continue.)</a>
821 Default is available as the class function C<gen_plain_login_link>.
823 =item C<gen_postmainpage_form>($cgi,$authreq,$params))
825 Default: form contents (but not the C<< <form> >> element):
827 C<$params> (in the form returned by the C<get_params> hook) as hidden
830 <input type="submit" ... value=getext('Continue')>
832 Default is available as the class function C<gen_postmainpage_form>.
834 =item C<gen_start_html>($cgi,$authreq,$title)
836 Default: C<$cgi->start_html($title)>
838 =item C<gen_end_html>($cgi,$authreq,$title)
840 Default: C<$cgi->end_html($title)>
842 =item C<gen_footer_html>($cgi,$authreq)>
847 Powered by Free / Libre / Open Source Software
848 according to the [gen_licence_link_html].
849 [gen_source_link_html].
852 Default is available as the class function C<gen_plain_footer_html>.
854 =item C<gen_licence_link_html>($cgi,$authreq)>
856 Default: uses C<url_with_query_params> to generate a URL for
857 downloading the licence, and returns:
858 <a href="...">GNU Affero GPL</a>
860 Default is available as the class function C<gen_plain_licence_link_html>.
862 =item C<gen_source_link_html>($cgi,$authreq)>
864 Default: uses C<url_with_query_params> to generate a URL for
865 downloading the source, and returns:
866 <a href="...">Source available</a>
868 Default is available as the class function C<gen_plain_source_link_html>.
870 =item C<form_entry_size>
872 Size of generated text entry fields. Default is 60.
874 =item C<dummy_param_name_prefix>
876 Some of CAF's HTML-generating functions need to invent form parameter
877 names. They will all start with this string. Default: C<caf__>.
879 =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
883 =item C<srcdump_param_name>
885 Form parameter name used to indicate that this is a source download
886 request. If this parameter is supplied, C<check_ok> and
887 C<check_divert> will arrange for the applicaton source code to be
888 delivered as the response (in C<check_ok>'s case by doing it itself
889 and in C<check_divert>'s case by asking your application to do so.
891 Default is C<caf_srcdump>.
893 =item C<srcdump_path>
895 Path to the directory used for storing pre-prepared source downloads.
896 Defaults to C<caf-srcdump>.
898 If this is a relative path, it is in C<dir>.
902 =head2 SETTINGS FOR HTML GENERATION
910 =head1 DATABASE TABLES
912 In a simple application, you do not need to worry about this. But if
913 your application runs on multiple frontend hosts with a shared
914 database, you may need to create for yourself the tables and indices
915 used by CGI::Auth::Flexible.
917 xxx document _db_setup_do
918 xxx make _db_setup_do explicitly overrideable
927 xxx bugs wrong default random on Linux
928 xxx bugs wrong default random on *BSD
929 xxx bugs keys not shared should be in db
930 xxx rename caf-assocs.db
931 xxx rename caf_assocsecret default cookie name
932 xxx mention relationship between login_timeout and cookies