chiark / gitweb /
Testing: Rename srcdump-loginback.at (from srcdump.at)
[cgi-auth-flexible.git] / caf.pod
1 # -*- fundamental -*-
2
3 # This is part of CGI::Auth::Flexible, a perl CGI authentication module.
4 #
5 # This program is free software: you can redistribute it and/or modify
6 # it under the terms of the GNU Affero General Public License as published by
7 # the Free Software Foundation, either version 3 of the License, or
8 # (at your option) any later version, with the "CAF Login Exception"
9 # as published by Ian Jackson (version 1, or at your option any 
10 # later version) as an Additional Permission.
11 #
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15 # GNU Affero General Public License for more details.
16
17
18 =head1 NAME
19
20 CGI::Auth::Flexible - web authentication optionally using cookies
21
22 =head1 SYNOPSYS
23
24  my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...);
25  my $authreq = $verifier->new_request($cgi);
26
27  # simple applications
28  $authreq->check_ok() or return;
29
30  # sophisticated applications
31  my $divert_kind = $authreq->check_divert();
32  if ($divert_kind) { ... print diversion page and quit ... }
33
34  # while handling the request
35  $user = $authreq->get_username();
36  $authreq->check_mutate();
37
38 =head1 DESCRIPTION
39
40 CGI::Auth::Flexible is a library which you can use to add a
41 forms/cookie-based login facility to a Perl web application.
42
43 CGI::Auth::Flexible doesn't interfere with your application's URL path
44 namespace and just needs a few (configurable) form parameter and
45 cookie name(s) for its own use.  It tries to avoid making assumptions
46 about the implementation structure of your application.
47
48 Because CGI::Auth::Flexible is licenced under the AGPLv3, you will
49 probably need to provide a facility to allow users (even ones not
50 logged in) to download the source code for your web app.  Conveniently
51 by default CGI::Auth::Flexible provides (for pure Perl webapps) a
52 mechanism for users to get the source.
53
54 CGI::Auth::Flexible is designed to try to stop you accidentally
55 granting access by misunderstanding the API.  (Also it, of course,
56 guards against cross-site scripting.)  You do need to make sure to
57 call CGI::Auth::Flexible before answering AJAX requests as well as
58 before generating HTML pages, of course, and to call it in every
59 entrypoint to your system.
60
61 =head2 CHECKLIST
62
63 As a minimum you need to do all of the things on this checklist, where
64 applicable.  The items marked SECURITY are the ones that you might
65 forget: without them your application may appear to work, but will be
66 insecure.
67
68 =over
69
70 =item *
71
72 Call C<new_verifier> (once at application startup)
73
74 =item *
75
76 Call C<new_request> (once per request)
77
78 =item *
79
80 B<SECURITY>: Call C<check_ok> or C<check_divert> on every request, and
81 honour the return value.
82
83 =item *
84
85 If you're using C<check_ok>, implement either the
86 C<username_password_error> or C<login_ok> hook and provide it as
87 a setting to C<new_verifier>.
88
89 =item *
90
91 Provide the setting C<dir> (or provide absolute paths for all the
92 other relevant settings).
93
94 =item *
95
96 Call C<get_username> when you need to know who's logged in.
97
98 =item *
99
100 B<SECURITY>: Call C<check_mutate> or C<mutate_ok>, if you specified
101 C<promise_check_mutate>.
102
103 =item *
104
105 B<SECURITY>: Call C<check_nonpage> for every request which is not a page load
106 (if your application has any of those).
107
108 =item *
109
110 When generating URLs and forms (including AJAX requests), include the
111 hidden form parameter using C<secret_hidden_val> or
112 C<secret_hidden_html> when appropriate (see below).
113
114 =item *
115
116 B<SECURITY>: If you do not override the source provision facility (see
117 L</SOURCE CODE DOWNLOAD>), check that the assumptions it makes aren't
118 going to leak security-critical data.
119
120 =item *
121
122 Set up HTTPS on your webserver, or set the C<encrypted_only> setting
123 to a false value.
124
125 =back
126
127 These points will now be covered in more detail.
128
129 =head2 INITIALISATION
130
131 Your application should, on startup (eg, when it is loaded by
132 mod_perl) do
133 C<< $verifier = CGI::Auth::Flexible->new_verifier(settings...) >>.
134 This call can be expensive and is best amortised.
135
136 The resulting verifier object can be used to process individual
137 requests, in each case with
138 C<< $authreq = CGI::Auth::Flexible->new_request($cgi) >>.
139
140 See L</SETTINGS>.
141
142 =head2 CHECKING AND RESPONSE GENERATION
143
144 If the user is logged in, your application is to handle the request.
145 Otherwise, the user needs to be presented with a login form or error
146 message, as appropriate.  CGI::Auth::Flexible provides two alternative
147 interfaces for this:
148
149 =head3 Simple applications
150
151 The simplest usage is to call C<< $request->check_ok() >> which will
152 check the user's authentication.  If the user is not logged in it will
153 generate a login form (or redirection or other appropriate page) and
154 return false; your application should not then process that request
155 any further.  If the user is logged in it will return true.
156
157 Various hooks are provided to customise the responses generated by
158 C<check_ok>.
159
160 After C<check_ok> returns true you should go ahead and process the
161 request; you can use C<< $request->get_username >> to find out which
162 user the request came from.
163 You may also need to call C<check_mutate> and/or C<check_nonpage>
164 - see below.
165
166 =head3 Sophisticated applications
167
168 If you want to handle the control flow and to generate login forms,
169 redirections, etc., yourself, you can say
170 C<< $divert = $request->check_divert >>.  This returns undef if
171 the user is logged in, or a I<divert spec> if some kind of login
172 page or diversion should be generated.  See L</DIVERT SPEC> below for
173 details of how to deal with the return value.
174
175 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS
176
177 =head3 Mutation-ignorant applications
178
179 By default CGI::Auth::Flexible does not permit external deep links
180 into your site.
181 All GET requests give a "click to continue" page which
182 submits a form which loads your app's main page.  In this
183 configuration all your application's forms and AJAX requests should
184 use C<POST>.
185
186 Such applications are also not able to provide user-specific CSS
187 stylesheets, javascript, favicons, etc.
188
189 This restriction arises from complicated deficiencies
190 in the web's security architecture.
191
192 =head3 Mutation-aware applications
193
194 The alternative is for your application to always make a special check
195 when the incoming request is going to do some kind of action (such as
196 modifying the user's setup, purchasing goods, or whatever) rather than
197 just retrieve and/or display information.  We term such requests
198 "mutating" requests.
199
200 Then non-mutating pages can be linked to from other, untrustworthy,
201 websites.
202
203 To support external links, and C<GET> requests, pass
204 C<< promise_check_mutate => 1 >> in I<settings>, and then call
205 C<< $authreq->check_mutate() >> before taking any actions.  If the
206 incoming request is not suitable then C<< $authreq->check_mutate() >>
207 will call C<die>.
208
209 There have to be no mutating C<GET> requests in your application (but
210 you shouldn't have any of those anyway); if there are, they won't
211 work.  (CGI::Auth::Flexible will spot them and cause them to fail,
212 rather than allow them to be insecure.)
213
214 =head2 GENERATING URLS, FORMS AND AJAX QUERIES
215
216 When you generate a URL, C<POST> form or AJAX request you may need to
217 include a secret hidden form parameter for the benefit of
218 CGI::Auth::Generic.  This form parameter will be checked by
219 C<check_ok>/C<check_divert> and should be ignored by your application.
220
221 By default the hidden parameter is called C<caf__assochash>.
222
223 After calling C<check_ok> or C<check_divert> the value to put in your
224 form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
225 will generate the whole HTML C<< <input...> >> element.
226
227 =head3 Mutation-ignorant applications
228
229 For mutation-ignorant applications (see above), all forms etc. should
230 include the hidden parameter (and as discussed, they must all use
231 POST rather than GET).
232
233 =head3 Mutation-aware applications
234
235 For mutation-aware applications, whether to include the secret
236 parameter depends on the kind of request.  CGI::Auth::Flexible knows
237 when it is necessary.  You should find out by calling
238 C<need_add_hidden>.
239
240 If it is inconvenient to call C<need_add_hidden> at runtime, you can
241 rely instead on the following promises:  All POST requests (which
242 includes all mutating requests) need the parameter.  The return value
243 of need_add_hidden depends only on the $method and $reqtype
244 parameters, so you can query it once and remember the answer.
245 HTML page load GETs do not need the parameter.  It is better to
246 err on the side of including the parameter.
247
248 If you really must, you can call C<need_add_hidden> "on the bench"
249 during development and bake the answer into your application code
250 structure.  However, if you do that and a new vulnerability was
251 discovered which is fixed by changing the answer, updating
252 CGI::Auth::Flexible wouldn't be sufficient to fix it.
253
254 =head3 Mutation-aware applications - non-page requests
255
256 If your mutation-aware application supports non-page resources (AJAX
257 and JSON requests, stylesheets, favicons, etc.) it must inform
258 CGI::Auth::Flexible when it is handling such a request, by calling
259 C<check_nonpage>.
260
261 Normally C<check_nonpage> will simply return (and you can ignore the
262 return value).  However, if there is an attack (or, perhaps, a bug) it
263 will die, stopping the attack.
264
265 (You do not need to call C<check_nonpage> for POST requests, but it is
266 harmless to do so.)
267
268 =head3 Mutation-aware applications - novel kinds of request
269
270 If you want to support a kind of request perhaps not yet known about
271 by CGI::Auth::Flexible, you can provide information about that new
272 request kind using C<update_get_need_add_hidden>.
273
274 =head2 DATA STORAGE
275
276 CGI::Auth::Flexible needs to store various information in plain files;
277 it does this in the directory specified by the C<dir> parameter.
278
279 =head1 SOURCE CODE DOWNLOAD
280
281 By default, CGI::Auth::Flexible provides a facility for users to
282 download the source code for the running version of your web
283 application.
284
285 This facility makes a number of important assumptions which you need
286 to check.  Note that if the provided facility is not sufficient
287 because your application is more sophisticated than it copes with (or
288 if you disable the builtin facility), you may need to implement a
289 functioning alternative to avoid violating the AGPLv3 licence.
290
291 Here are the most important (default) assumptions:
292
293 =over
294
295 =item *
296
297 Your app's source code is available by looking at @INC, $0 and
298 S<$ENV{'SCRIPT_FILENAME'}> (the B<source items>).  See
299 C<srcdump_listitems>.  Where these point to files or directories under
300 revision control, the source item is the whole containing vcs tree.
301
302 =item *
303
304 Specifically, there are no compiled or autogenerated Perl
305 files, Javascript resources, etc., which are not contained in one of
306 the source item directories.  (Files which came with your operating
307 system install don't need to be shipped as they fall under the system
308 library exception.)
309
310 =item *
311
312 You have not installed any modified versions of system
313 libraries (including system-supplied Perl modules) in C</usr> outside
314 C</usr/local>.  See C<srcdump_system_dir>.
315
316 =item *
317
318 For each source item in a dvcs, the entire dvcs history does
319 not contain anything confidential (or libellous).  Also, all files which
320 contain secrets are in the dvcs's I<.ignore> file.  See
321 C<srcdump_vcsscript_git> et al.
322
323 =item *
324
325 For each source item NOT in a dvcs, there are no confidential
326 files with the world-readable bit set (being in a world-inaccessible
327 directory is not sufficient).  See C<srcdump_excludes>.
328
329 =item *
330
331 You have none of your app's source code in C</etc>.
332
333 =item *
334
335 You don't regard pathnames on your server as secret.
336
337 =item *
338
339 You don't intentionally load Perl code by virtue of C<.>
340 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
341
342 =back
343
344 =head1 MAIN FUNCTIONS AND METHODS
345
346 =over
347
348 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
349
350 Initialises an instance and returns a verifier object.
351 The arguments are setting pairs like a hash initialiser.
352 See L</SETTINGS> below.
353
354 =item C<< $verifier->new_request($cgi) >>
355
356 Prepares to process a request.  I<$cgi> should normally
357 be the query object from L<CGI(3perl)>.  Most of the default
358 hook methods assume that it is; however if you replace enough of
359 the hook methods then you can pass any value you like and it
360 will be passed to your hooks.
361
362 The return value is the authentication request object (I<$authreq>)
363 which is used to check the incoming request and will contain
364 information about its credentials.
365
366 =item C<< $authreq->check_divert() >>
367
368 Checks whether the user is logged in.  Returns undef if the user is
369 logged in and we should service the request.  Otherwise returns a
370 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
371
372 This method may die if it doesn't like the request, in which case
373 the request needs to be rejected.
374
375 =item C<< $authreq->check_ok() >>
376
377 Checks whether the user is logged in.  Returns true if the user is
378 logged in and we should service the request.
379
380 Otherwise it handles the request itself, generating any appropriate
381 redirect, login form, or continuation page.  It then returns false and
382 the application should not process the request further.
383
384 =item C<< $verifier->disconnect() >>
385
386 Discards the resources (open files, etc.) in the verifier object.
387
388 =back
389
390 =head1 REQUEST-RELATED FUNCTIONS AND METHODS
391
392 All of these are only valid after C<check_divert> or C<check_ok> has
393 been called.  (In the case of C<check_ok> it won't normally be sensible
394 to call these functions unless C<check_ok> returned true.)
395
396 =over
397
398 =item C<< $authreq->get_divert() >>
399
400 Returns the value previously returned by C<check_divert>.
401
402 =item C<< $authreq->get_username() >>
403
404 Returns the name of the logged-in user.  If the user was not logged
405 in (or their session had timed out, or something), returns undef.
406
407 =item C<< $authreq->check_mutate() >>
408
409 Declares to CGI::Auth::Generic that the request being handled will
410 "mutate".  That is, it will modify some server-side state (eg, adding
411 items to shopping baskets, posting messages to blogs, sending emails,
412 or whatever).
413
414 If you have set the setting C<promise_check_mutate> you must call
415 C<check_mutate> whenever appropriate.  If you haven't then it's
416 irrelevant.  See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
417
418 C<check_mutate> will either return successfully, indicating that all
419 is well and the request should proceed, or it will die.  If it dies
420 that means that the request was improper, which can only result from a
421 bug or an attack.  So an "internal server error" is a suitable
422 response.
423
424 =item C<< $authreq->check_nonpage($method, $reqtype) >>
425
426 Declares to CGI::Auth::Generic that the request is not a page request,
427 but rather a request of type I<$reqtype>.
428
429 If your application has set the setting C<promise_check_mutate>,
430 whenever it is handling anything except an HTML page loads, it must
431 call this function.  See L</REQUEST TYPES>, and
432 L<GENERATING URLS, FORMS AND AJAX QUERIES>.
433
434 C<check_nonpage> will either return successfully, indicating that all
435 is well and the request should proceed, or it will die, like
436 C<check_mutate>.
437
438 =back
439
440 =head1 RESPONSE-RELATED FUNCTIONS AND METHODS
441
442 =over
443
444 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
445
446 Convenience function which returns a url for a GET request to this
447 application.
448
449 I<$params> is a hashref specifying the parameters and the PATH_INFO
450 (not including any parameters related to CGI::Auth::Flexible).
451 The keys are the parameter names, and the values are array refs with
452 the parameter value(s) (as strings, as yet unquoted).  (They are array
453 refs because it is possible to pass multiple values for the same
454 parameter in a single request; normally each arrayref would be a
455 singleton.)
456
457 The request path will be the path to the application.  If a parameter
458 with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
459 value will be appended to the application path.  (It should normally
460 start with C<< / >>, and only one value should be supplied.)
461
462 =item C<< something->need_add_hidden($method, $reqtype) >>
463
464 Enquires whether a request of type I<$reqtype> using HTTP method
465 I<$method> needs the hidden form parameter.  See L</REQUEST TYPES>.
466
467 =item C<< something->secret_hidden_val() >>
468
469 Returns the value of the hidden form parameter.  This should be
470 included in all POST requests to your application (and thus be a
471 hidden form parameter in all forms).
472
473 It should also be in some (maybe all) GET requests.  If your
474 application is mutation-ignorant, it should be in all GET requests.
475 If you are mutation-aware, you need to consult C<need_add_hidden>.
476
477 The name of the hidden parameter is the setting C<assoc_param_name>,
478 C<caf_hassochash> by default.  xxx rename param and setting
479
480 =item C<< something->secret_hidden_html() >>
481
482 Returns the HTML for an C<INPUT> element specifying the hidden form
483 parameter.
484
485 =item C<< something->secret_cookie_val() >>
486
487 Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
488 cookie in the forms generated by C<check_ok>.  You may also set it
489 yourself (and indeed you must do so if you use C<check_divert>).
490
491 =item C<< $authreq->chain_params() >>
492
493 Returns a hash of the "relevant" parameters to this request, in a form
494 suitable for C<url_with_query_params>.  This is all of the query
495 parameters which are not related to CGI::Auth::Flexible's authentication
496 arrangements.  (The srcdump request parameters B<are> included.)  The
497 PATH_INFO from the request is returned as the parameter C<< '' >>.
498
499 =back
500
501 =head1 OTHER FUNCTIONS AND METHODS
502
503 =over
504
505 =item C<< $verifier_or_authreq->hash($data) >>
506
507 Hashes the supplied data using the hash function specified by the
508 C<hash_algorithm> setting, and converts the result to a string of hex
509 digits.
510
511 =item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
512
513 Updates CGI::Auth::Generic's knowledge about the various kinds of
514 request, and whether they need the hidden form parameter.  This
515 function applies only to GET requests - POST requests always use the
516 parameter.
517
518 I<$reqtype> is the request type (the value which will be passed to
519 C<check_nonpage> and C<need_add_hidden>.  If you are supporting a new
520 I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstream,
521 or other users, to assign a unique request type name.
522
523 This method may be called on an authreq or a verifier, in which case
524 it will affect all authreqs using the same verifier.  Or it may be
525 called on the class as a whole, in which case it will affect the
526 global default list for all verifiers.
527
528 If I<$force> is supplied and true, this will override
529 CGI::Auth::Flexible's existing knowledge.  Otherwise this new setting
530 will be ignored if CGI::Auth::Flexible already knows about the request
531 type.  (When called on a verifier or authreq, it will ignore the
532 update in favour of existing knowledge recorded both globally in the
533 class or due to previous requests on the same verifier.)
534
535 See L</REQUEST TYPES>.
536
537 =item C<< CGI::Auth::Flexible::srcdump_dir_cpio($cgi,$verifier,$dumpdir,$dir,$outfn,$how,$script) >>
538
539 Helper function for implementing the C<srcdump_process_item> hook.
540 Generates a tarball using cpio and includes it in the prepared source
541 code distribution.
542
543 The arguments are mostly the same as for that hook.  C<$dir> is the
544 root directory at which to start the archive.  C<$how> is a short text
545 string which will be mentioned in the log.
546
547 C<$script> is a shell script fragment which must output a
548 nul-separated list of filenames (e.g. the output of C<find -print0>).
549 It is textually surrounded by C<( )> and will be executed with C<set -e>
550 in force.  Its cwd will be C<$dir>.
551
552 =item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible-> >>
553
554 Hashes the supplied data using the hash function specified by the
555 C<hash_algorithm> setting, and converts the result to a string of hex
556 digits.
557
558 =back
559
560 =head1 REQUEST TYPES
561
562 The C<$reqtype> values understood by C<check_nonpage> are strings.
563 They are:
564
565 =over
566
567 =item C<PAGE>
568
569 A top-level HTML page load.  May contain confidential information for
570 the benefit of the logged-in user.
571
572 =item C<FRAME>
573
574 An HTML frame.  May contain confidential information for
575 the benefit of the logged-in user.
576
577 =item C<IFRAME>
578
579 An HTML iframe.  May contain confidential information for
580 the benefit of the logged-in user.
581
582 =item C<SRCDUMP>
583
584 Source dump request, whether for the licence or actual source code
585 tarball; returned value is not secret.
586
587 =item C<STYLESHEET>
588
589 CSS stylesheet.  B<MUST NOT> contain any confidential data.  If the
590 stylesheet depends on the user, then attackers may be able to
591 determine what stylesheet the user is using.  Hopefully this is not a
592 problem.
593
594 =item C<FAVICON>
595
596 "Favicon" - icon for display in the browser's url bar etc.  We aren't
597 currently aware of a way that attackers can get a copy of this.
598
599 =item C<ROBOTS>
600
601 C<robots.txt>.  Should not contain any confidential data (obviously).
602
603 =item C<IMAGE>
604
605 Inline image, for an C<< <img src=...> >> element.
606
607 Unfortunately it is not possible to sensibly show top-level
608 confidential images (that is, have the user's browser directly visit a
609 url which resolves to an image rather than an HTML page with an inline
610 image).  This is because images need to have a per-session hidden form
611 parameter to avoid cross-site scripting, which breaks bookmarks etc.
612
613 =item C<SCRIPT>
614
615 JavaScript for a C<< <script> >> element.  (Possibly confidential for
616 the user.)
617
618 =item C<AJAX-XML>
619
620 C<< XMLHttpRequest >> returning XML data.  (Possibly
621 confidential for the user.)
622
623 =item C<AJAX-JSON>
624
625 C<< XMLHttpRequest >> returning JSON data.  (Possibly
626 confidential for the user.)
627
628 =item C<AJAX-OTHER>
629
630 C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
631 confidential for the user.)
632
633 =back
634
635 =head1 DIVERT SPEC
636
637 The return value from C<check_divert> indicates how the request should
638 be handled.  It is C<undef> if all is well and the user is logged in.
639
640 Otherwise the return value is a hash ref with the following keys:
641
642 =over
643
644 =item C<Kind>
645
646 Scalar string indicating the kind of diversion required.
647
648 =item C<Message>
649
650 Scalar string for display to the user in relation to the diversion.
651 Has already been translated.  In HTML but normally does not contain
652 any tags.
653
654 =item C<CookieSecret>
655
656 The login cookie which should be set along with whatever response is
657 sent to the client.  The value in the hash is the actual value
658 of the cookie as a string.  C<undef> means no cookie setting header
659 should be sent; C<''> means the cookie should be cleared.
660
661 =item C<Params>
662
663 Provided with diversion kinds which involve
664 generating a redirection or indirection,
665 perhaps via a login form.
666
667 The extra hidden form parameters (and the C<PATH_INFO>) which should
668 be set when the subsequent request bounces back from the client, in
669 the form used by C<url_with_query_params>.
670
671 The contents of this hashref does not include the CAF-specific
672 parameters such as the secret cookie, those which follow from the kind
673 of diversion requested, etc.  (But they may include the
674 srcdump_param_name, so that srcdump_needlogin can work properly.)
675
676 It is correct to always include the contents of C<Params> as hidden
677 parameters in the urls for all redirections, and as hidden input
678 fields in all generated forms.  The specific cases where C<Params> is
679 currently relevant are also mentioned in the text for each divert
680 kind.
681
682 =back
683
684 The values of C<Kind> are:
685
686 =over
687
688 =item C<SRCDUMP->I<item>
689
690 We should respond by sending our application source code.  I<item>
691 (which will contain only word characters, and no lower case) is the
692 specific item to send, normally C<SOURCE> or C<LICENCE>.
693
694 =item C<REDIRECT-HTTPS>
695
696 We should respond with an HTTP redirect to the HTTPS instance of our
697 application.
698
699 =item C<REDIRECT-LOGGEDOUT>
700
701 We should redirect to a page showing that the user has been logged
702 out.  (Ie, to a url with one of the the C<loggedout_param_names> set.)
703
704 =item C<SMALLPAGE-LOGGEDOUT>
705
706 We should generate a page showing that the user has been logged out.
707 There can be a link on the page pointing to the login page so that the
708 user can log back in.
709
710 =item C<SMALLPAGE-NOCOOKIE>
711
712 We should generate a page reporting that the user does not have
713 cookies enabled.  It should probably contain a link pointing to the
714 login page with additionally all the parameters in C<Params>.  When
715 this divert spec is generated, C<Message> will explain the problem
716 with cookies so there is no need to do that again in the page body if
717 you include the contents of C<Message>.
718
719 =item C<LOGIN-STALE>
720
721 The user's session was stale (this is described in C<Message>).  We
722 should generate a login form.
723
724 =item C<LOGIN-BAD>
725
726 The user supplied bad login credentials.  The details are in
727 C<Message>.  We should generate a login form (with additionally the
728 parameters from C<Params> as hidden fields).
729
730 =item C<LOGIN-INCOMINGLINK>
731
732 We should generate a login form (with the specified parameters); the
733 user is entering the site via a cross-site link but is not yet logged
734 in.
735
736 =item C<LOGIN-FRESH>
737
738 We should generate a login form.  The user is not yet logged in.
739
740 =item C<REDIRECT-LOGGEDIN>
741
742 We should redirect to our actual application, with the specified
743 parameters.  (The user has just logged in.)
744
745 =item C<STALE>
746
747 The user is logged in but the incoming form submission looks like it
748 was from a stale login session.  Alternatively, it may have been
749 generated by an attacker's cross-site-scripting attack.
750
751 Naive applications should generate a small page with a form or link to
752 our own main page without any parameters.
753
754 A sophisticated application could infer from the submitted form
755 parameters what the user was allegedly trying to do.  We could then
756 generate a fresh page showing what the intended action was, with a
757 fresh form which (if the user confirm) would resubmit that action.
758 B<Great care> must be taken to avoid relying on the sanity and
759 coherence of the incoming form parameters.  We B<MUST NOT> simply
760 reproduce the incoming parameters in the new form.  It is essential
761 that the visual appearance of the generated form correctly shows to
762 the user what the action is that will be taken if the form is
763 submitted.  If that action is dangerous, the form should not look like
764 the kind of confirmation pages which the user is likely to simply
765 click through without thinking.
766
767 =item C<MAINPAGEONLY>
768
769 We should generate our main page but B<ignoring all form parameters>
770 and B<ignoring the path_info>.  Most applications will find this
771 difficult to implement.
772
773 An alternative is to generate a small page with a form or link which
774 submits our own main page without any parameters.
775
776 (Applications which set C<promise_check_mutate> do not see this divert
777 kind.)
778
779 =back
780
781 Applications should die if they are presented with a divert kind that
782 they don't recognise.
783
784 =head1 SETTINGS
785
786 C<new_verifier> and C<new_request> each take a list of settings, as
787 a list of pairs C<< key => value >> (like a Perl hash assignment).
788
789 The settings supplied to C<new_verifier> are stored in the verifier
790 and will apply to all authreqs made from it unless overridden in the
791 call to C<new_request>
792
793 When a setting is described as a hook function, it should be a
794 coderef.  The first argument will be the query object from
795 L<CGI(3perl)> (strictly, it will be whatever value was passed to
796 C<new_request>).  The second argument will be the authreq object (the
797 return value from C<new_request>).
798 Ie, C<< sub some_hook ($$...) { my ($cgi,$authreq,@stuff) = @_ ... >>
799
800 In bullet point headings, the hook functions are shown in the form
801 C<< some_hook($cgi,$authreq,@stuff) >> even though this would not be
802 legal syntax.  This should be read to mean that the
803 %implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
804 would be a legal call.  (However, the settings hash is not exposed.)
805
806 When a hook's default implementation is mentioned and named, that
807 function won't also be described in the section on the module's
808 functions.
809
810 =head2 GENERAL SETTINGS
811
812 =over
813
814 =item C<dir>
815
816 The directory CGI::Auth::Generic should use for its data storage.
817 This is actually just a default absolute path used when the other
818 path settings are relative values.
819
820 Must be an absolute filename.
821
822 =item C<db_dbh>
823
824 CGI::Auth::Flexible needs a database for recording users' login
825 session.  This database needs to be shared across all instances of the
826 web application, so in a multi-node cluster it needs to be your actual
827 database.
828
829 CGI::Auth::Flexible will create the table and index it needs if they
830 don't already exist, and will manage their contents.  You do not need
831 to integrate them into the rest of your webapp's data storage.  (In
832 particular, there is no need for transactional integrity across
833 changes made by CAF and your own application.)
834
835 By default, CAF uses a sqlite3 database stored on local disk in the
836 file named by C<db_path>.  This will be suitable for all
837 applications which run on a single host.
838
839 This value, if supplied, should be a DBI handle for the database.
840
841 =item C<db_dsn>
842
843 This is the DSN to pass to C<< DBI->connect >>.  Used only if
844 C<db_dbh> is not supplied.
845
846 =item C<db_path>
847
848 Path to the sqlite3 database used for CAF's session storage.  The
849 default is C<caf.db>.
850
851 Used only if neither C<db_dbh> or C<db_dsn> are supplied.
852
853 If this is a relative path, it is in C<dir>.
854
855 =item C<db_prefix>
856
857 Prefix for the SQL tables and indices to use (and to create, if
858 necessary).
859
860 See L</DATABASE TABLES>.
861
862 =item C<keys_path>
863
864 Path to the keys file used by CAF.  This arrangement will change in
865 the future.  See L</BUGS>.
866
867 =item C<random_source>
868
869 Special file to read random numbers from.  Should return
870 cryptographically secure (pseudo)-random bytes, unpredictable to
871 adversaries (even ones on the same machine).
872
873 On Linux, there is no device which is properly suitable.  This is a
874 bug in Linux.  You can use C</dev/random> which can block
875 unnecessarily even though the kernel PRNG has been properly seeded and
876 is fine, or C</dev/urandom> which might return values which attackers
877 can predict if the kernel PRNG has not been properly seeded.
878
879 The default is C</dev/urandom>.
880
881 =item C<secretbits>
882
883 Length of the assoc secret.  Defaults to 128.
884
885 =item C<hash_algorithm>
886
887 Must be a string suitable for use with C<new Digest>.
888 Defaults to C<SHA-256>.
889
890 =item C<login_timeout>
891
892 A user will be logged out this many seconds after they first logged
893 in.  Default: 86400 (one day).
894
895 =item C<login_form_timeout>
896
897 A login form becomes invalid this many seconds after it has been sent.
898 Default: 3600 seconds (one hour).
899
900 =item C<key_rollover>
901
902 The key used for generating assoc secrets is rolled over approximately
903 this often (in seconds).  Default: 86400.
904
905 =item C<assoc_param_name>
906
907 Name of the hidden form parameter.  Default: C<caf_assochash>.
908
909 =item C<cookie_name>
910
911 Name of the cookie used for login sessions.  Default:
912 C<caf_assocsecret>.
913
914 =item C<password_param_name>
915
916 Name of the password field in the login form.  Default: C<password>.
917
918 Used by C<login_ok_password> (the default C<login_ok> hook),
919 C<gen_plain_login_form> and the default C<is_login> hook.
920
921 =item C<username_param_names>
922
923 Arrayref of name(s) of username form parameters.
924
925 The first entry is used by C<login_ok_password> (the default
926 C<login_ok> hook) to pass to the C<username_password_error> hook and
927 used as the username if all is well.
928
929 All the entries are used by C<gen_plain_login_fork> (the default
930 C<gen_login_form> hook for C<check_ok>) to generate form entry fields.
931
932 The default is C<['username']>.
933
934 =item C<logout_param_names>
935
936 Arrayref of name(s) of form parameters indicating that the request is
937 a logout request.
938
939 Used by the default C<is_logout> hook.
940
941 If you want users to be able to explicitly log out, you need to
942 provide a logout button, something like
943 C<< <input type="submit" name="caf_logout" ... >>
944
945 The default is C<['caf_logout']>
946
947 =item C<logged_param_names>
948
949 Arrayref of name(s) of form parameters indicating that user has just
950 logged out.  (During the logout process, the actual logout action is a
951 POST request, whose response redirects to the "you have been logged
952 out" page; these form parameters are for this second page.)
953
954 Used by the default C<is_loggedout> hook.
955
956 The first entry is used by C<check_ok> to generate the redirection.
957
958 The default is C<['caf_loggedout']>
959
960 =item C<promise_check_mutate>
961
962 Boolean.  If true, is a declaration by the application that it is
963 mutatin-aware.  See L</MUTATING OPERATIONS AND EXTERNAL LINKS>.
964
965 The default is 0.
966
967 =item C<encrypted_only>
968
969 Boolean.  If true, CAF will insist that all transactions be done over
970 an encrypted http connection.  It will redirect unencrypted requests
971 to the https instance of the applicattion, and will set the encrypted
972 only flag on its cookie.
973
974 The default is 1.
975
976 =item C<< get_url($cgi,$authreq) >>
977
978 Hook which returns the URL of this web application.  By default, we
979 call C<< $cgi->url() >> for each request, but you can fix this if you
980 prefer.
981
982 =item C<< is_login,is_logout,is_loggedout($cgi,$authreq) >>
983
984 Hook which returns a boolean indicating whether the request was,
985 respectively: a login form submission (ie, username and password); a
986 logout request (submission resulting from the user pressing the
987 "logout" button); "logged out" page (redirection from the logout
988 POST).
989
990 The default is to check whether any of the corresponding request
991 parameters (C<< login_param_names >> etc.) was supplied, using the
992 C<get_param> hook.
993
994 =back
995
996 =head2 SETTINGS (HOOKS) RELATED TO THE CGI REQUEST OBJECT
997
998 =over
999
1000 =item C<< get_param($cgi,$authreq,$param) >>
1001
1002 Returns the value of a single-valued form parameter.
1003 The default is to call C<< $cgi->param($param) >>.
1004 The semantics are the same as that of C<CGI::param>.
1005
1006 =item C<< get_params($cgi,$authreq) >>
1007
1008 Returns a hash of the parameters.  The return value is a hashref whose
1009 keys are the parameter names and whose values are arrayrefs, one entry
1010 in the arrayref for each value.
1011
1012 The default is to call C<< $cgi->Vars() >>, expect the
1013 results to look like those from C<CGI::Vars>, and massage them into
1014 the required form with split.
1015
1016 =item C<< get_path_info($cgi,$authreq) >>
1017
1018 Returns the PATH_INFO of the request.  The default is to
1019 call C<< $cgi->path_info() >>.
1020
1021 =item C<< get_cookie($cgi,$authreq) >>
1022
1023 Returns the value of the CAF cookie sent with the request, or undef if
1024 none was supplied.  The default is to call C<<
1025 $cgi->cookie($cookie_name) >> (where C<$cookie_name> is from the
1026 setting of the same name).  The return value should be the scalar
1027 value of the cookie.
1028
1029 =item C<< get_method($cgi,$authreq) >>
1030
1031 Returns the HTTP method as a string.  The default is to call
1032 C<< $cgi->request_method() >>.
1033
1034 =item C<< is_https($cgi,$authreq) >>
1035
1036 Returns a boolean indicating whether the request was over an encrypted
1037 channel.  The default is C<< !!$cgi->https() >>.  See C<encrypted_only>.
1038
1039 =back
1040
1041 =head2 SETTINGS RELATED TO HTML GENERATION
1042
1043 These are only used if you call C<check_ok> (or other functions
1044 mentioned in this section).
1045
1046 Settings whose names are of the form C<gen_...> are hooks which each
1047 return an array of strings, normally HTML strings, for use by
1048 C<check_ok> (or, in turn, other hooks, or your application).  These
1049 are often documented simply by showing the output produced.  In many
1050 cases parts of the output are in turn obtained from other hooks.  In
1051 some cases the default implementations have been given names for
1052 convenient use by your application.  They will be called in array
1053 context.
1054
1055 We'll write C<gettext(something)> even though actually there is a hook
1056 to control the translation function used.
1057
1058 =over
1059
1060 =item C<handle_divert>($cgi,$authreq,$divert))
1061
1062 C<check_ok> calls this hook before producing output of its own.  If
1063 you want to handle some but not all diversions yourself, you may set
1064 this hook.  The hook should either do nothing and return false, or
1065 return true if it has handled the request (or arrange for the request
1066 to be handled).  If the hook returns true then C<check_ok> simply
1067 returns 0.
1068
1069 =item C<gen_login_form>($cgi,$authreq,$divert))
1070
1071 Default: a table (used mostly for layout) containing input fields for
1072 a login form.  Must be within a C<< <form> >> element, but doesn't
1073 generate it.  Has text fields for every entry in
1074 C<username_param_names> (in each case associated with a description
1075 C<< gettext(ucfirst $parameter_name) >>, a password field (with
1076 description C<gettext("Password")>, and a login submit button (with
1077 description C<gettext("Login")>.
1078
1079 Default is available as the module function C<gen_plain_login_form>.
1080
1081 =item C<gen_login_link>($cgi,$authreq))
1082
1083 Default:
1084
1085  <a href="http:...">gettext(Log in again to continue.)</a>
1086
1087 Default is available as the module function C<gen_plain_login_link>.
1088
1089 =item C<gen_postmainpage_form>($cgi,$authreq,$params))
1090
1091 Default: form contents (but not the C<< <form> >> element):
1092
1093 C<$params> (in the form returned by the C<get_params> hook) as hidden
1094 fields, and also:
1095
1096  <input type="submit" ... value=getext('Continue')>
1097
1098 Default is available as the module function C<gen_postmainpage_form>.
1099
1100 =item C<gen_start_html>($cgi,$authreq,$title)
1101
1102 Default: C<$cgi->start_html($title)>
1103
1104 =item C<gen_end_html>($cgi,$authreq,$title)
1105
1106 Default: C<$cgi->end_html($title)>
1107
1108 =item C<gen_footer_html>($cgi,$authreq)>
1109
1110 Default:
1111
1112  <hr><address>
1113  Powered by Free / Libre / Open Source Software
1114  according to the [gen_licence_link_html].
1115  [gen_source_link_html].
1116  </address>
1117
1118 Default is available as the module function C<gen_plain_footer_html>.
1119
1120 =item C<gen_licence_link_html>($cgi,$authreq)>
1121
1122 Default: uses C<url_with_query_params> to generate a URL for
1123 downloading the licence, and returns:
1124   <a href="...">GNU Affero GPL</a>
1125
1126 Default is available as the module function C<gen_plain_licence_link_html>.
1127
1128 =item C<gen_source_link_html>($cgi,$authreq)>
1129
1130 Default: uses C<url_with_query_params> to generate a URL for
1131 downloading the source, and returns:
1132   <a href="...">Source available</a>
1133
1134 Default is available as the module function C<gen_plain_source_link_html>.
1135
1136 =item C<form_entry_size>
1137
1138 Size of generated text entry fields.  Default is 60.
1139
1140 =item C<dummy_param_name_prefix>
1141
1142 Some of CAF's HTML-generating functions need to invent form parameter
1143 names.  They will all start with this string.  Default: C<caf__>.
1144
1145 =back
1146
1147 =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
1148
1149 =over
1150
1151 =item C<srcdump_needlogin>
1152
1153 Boolean: do users need to log in to be able to download the source
1154 code for the whole application ?  Default: 0.
1155
1156 =item C<srcdump_param_name>
1157
1158 Form parameter name used to indicate that this is a source download
1159 request.  If this parameter is supplied, C<check_ok> and
1160 C<check_divert> will arrange for the applicaton source code to be
1161 delivered as the response (in C<check_ok>'s case by doing it itself
1162 and in C<check_divert>'s case by asking your application to do so.
1163
1164 Default is C<caf_srcdump>.
1165
1166 =item C<srcdump_path>
1167
1168 Path to the directory used for storing pre-prepared source downloads.
1169 Defaults to C<caf-srcdump>.
1170
1171 If this is a relative path, it is in C<dir>.
1172
1173 =item C<srcdump_dump($cgi,$authreq,$srcobj)>
1174
1175 Dump the source code (C<$srcobj='source'> or licence data
1176 (C<$srcobj='licence'>).  The default implementation checks that
1177 C<$srcobj> has reasonable syntax and uses the files C<$srcobj.data>
1178 and C<$srcobj.ctype> with the C<dump> hook.
1179
1180 =item C<dump($cgi,$authreq,$contenttype,$datafilehandle)>
1181
1182 Responds to the request by sending the contents of $datafilehandle
1183 (which should just have been opened) and specifying a content type of
1184 $contenttype.
1185
1186 The default implmentation uses the C<print> hook, and also calls
1187 C<$cgi->header('-type' => $contenttype>, and is available as the
1188 module function C<dump_plain>.
1189
1190 =item C<srcdump_prepare($cgi,$verifier)>
1191
1192 Prepares the source code for download when requested.  Invoked by
1193 C<new_verifier>, always, immediately before it returns the
1194 just-created verifier object.
1195
1196 The default implementation is the module function
1197 C<srcdump_dirscan_prepare>, which prepares a manifest, licence file
1198 and source code tarball of tarballs, as follows:
1199
1200 It processes each entry in the return value from C<srcdump_listitems>.
1201 These are the software's include directories and any other directories
1202 containing source code.  It handles C<.> specially (see
1203 C<srcdump_filter_cwd>).
1204
1205 For each entry it looks, relative to that, for the licence as a file
1206 with a name mentioned in C<srcdump_licence_files>.  The first such
1207 file found is considered to be the licence.  It then calls the hook
1208 C<srcdump_process_item> for the entry.
1209
1210 The licence, a manifest file, and all the outputs generated by the
1211 calls to C<srcdump_process_item>, are tarred up and compressed as a
1212 single source tarball.
1213
1214 It uses the directory named by C<srcdump_path> as its directory for
1215 working and output files.  It uses the filename patterns
1216 C<generate.*>, C<licence.*>, C<s.[a-z][a-z][a-z].*>, C<manifest.*>,
1217 C<source.*> in that directory.
1218
1219 =item C<srcdump_process_item>($cgi,$verifier,$dumpdir,$item,\&outfn,\$needlicence,\%dirsdone)>
1220
1221 Processes a single include directory or software entry, so as to
1222 include the source code found there.  Called only by the default
1223 implementation of C<srcdump_prepare>.
1224
1225 C<$dumpdir> is the directory for working and output files.  C<$item>
1226 is the real (no symlinks) absolute path to the item.
1227
1228 C<\$needlicence> is a ref to a scalar: this scalar is undef if we have
1229 already found the licence file; otherwise it is the filename to which
1230 the licence should be copied.  If the referent is undef on entry,
1231 C<srcdump_process_item> needs to see if it finds the licence; if it
1232 does it should copy it to the named file and then set the scalar to
1233 undef.
1234
1235 C<\%dirsdone> is a ref to the hash used by C<srcdump_prepare> to avoid
1236 including a single directory more than once.  If
1237 C<srcdump_process_item> decides to process a directory other than
1238 C<$item> it should check this hash with the real absolute path of the
1239 other directoy as a key: if the hash entry is true, it has already
1240 been done and should be skipped; otherwise the hash entry should be set.
1241
1242 C<\&outfn> is a coderef which C<srcdump_process_item> should call each
1243 time it wants to generate a file which should be included as part of
1244 the source code.  It should be called using one of these patterns:
1245    $outfn->("message for manifest");
1246    $outfile = $outfn->("message for manifest", "extension");
1247 The former simply prints the message into the manifest in the form
1248   none: message for manifest
1249 The latter generates and returns a filename which should then
1250 be created and filled with some appropriate data.  C<"extension">
1251 should be a string for the file extension, eg C<"txt">.  The output
1252 can be written directly to the named file: there is no need to
1253 write to a temporary file and rename.  C<$outfn> writes the filename
1254 and the message to the manifest, in the form
1255   filename leaf: message
1256 In neither case is the actual name of C<$dir> on the system
1257 disclosed per se although of course some of the contents of some of
1258 the files in the source code dump may mention it.
1259
1260 The default implementation is the module function
1261 C<srcdump_process_item>.
1262
1263 It skips directories for which C<srcdump_system_dir> returns true.
1264
1265 It then searches the item and its parent
1266 directories for a vcs metadata directory (one of the names in
1267 C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
1268 (after checking and updaeing C<%dirsdone>).
1269 Otherwise it calls the C<srcdump_novcs> hook.
1270
1271 =item C<srcdump_novcs($cgi,$verifier,$dumpdir,$item,$outfn)>
1272
1273 Called by the default implementation of C<srcdump_process_item>, with
1274 the same arguments, if it doesn't find vcs metadata.
1275
1276 The default implementation is the module function C<srcdump_novcs>.
1277
1278 If C<$item> is a directory, it uses C<srcdump_dir_cpio> to prepare a
1279 tarball of all the files under C<$item> which have the world read bit
1280 set.  Directories are not included (and their permissions are
1281 disregarded).  The contents of C<srcdump_excludes> are excluded.
1282
1283 If it's a plain file it uses C<srcdump_file> to include the file.
1284
1285 =item C<srcdump_byvcs($cgi,$verifier,$dumpdir,$item,$outfn,$vcs)>
1286
1287 Called by the default implementation of C<srcdump_process_item>, with
1288 the same arguments, if it finds vcs metadata.  The additional argument
1289 C<$vcs> is derived from the entry of C<srcump_vcs_dirs> which was
1290 used: it's the first sequence of word characters, lowercased.
1291
1292 The default implementation is the module function C<srcdump_byvcs>.
1293 It simply calls C<srcdump_dir_cpio> with a script from the setting
1294 C<srcdump_vcsscript>.
1295
1296 =item C<srcdump_vcs_dirs>
1297
1298 Array ref of leaf names of vcs metadata directories.  Used by the
1299 default implementation of C<srcdump_process_item>.  The default value
1300 is C<['.git','.hg','.bzr','.svn']>.
1301
1302 =item C<srcdump_vcs_script>
1303
1304 Hash ref of scripts for generating vcs metadata.  Used by the default
1305 implementation of C<srcdump_byvcs>.  The keys are values of C<$vcs>
1306 (see C<srcdump_byvcs>); the values are scripts as for
1307 C<srcdump_dir_cpio>.
1308
1309 The default has an entry only for C<git>:
1310   git ls-files -z
1311   git ls-files -z --others --exclude-from=.gitignore
1312   find .git -print0
1313
1314 =item C<srcdump_excludes>
1315
1316 Array ref of exclude glob patterns, used by the default implementation
1317 of C<srcdump_novcs>.  The default value is C<['*~','*.bak','*.tmp','#*#']>.
1318
1319 Entries must not contain C<'> or C<\>.
1320
1321 =item C<srcdump_listitems($cgi,$verifier)>
1322
1323 Returns an array of directories which might contain source code of the
1324 web application and which should be therefore be considered for
1325 including in the source code delivery.
1326
1327 Used by the default implementation of C<srcdump_prepare>.
1328
1329 Entries must be directories, plain files, or nonexistent; they may
1330 also be symlinks which resolve to one of those.
1331
1332 If C<.> is included it may be treated specially - see
1333 C<srcdump_filter_cwd>.
1334
1335 The default implementation returns 
1336 C<(@INC, $ENV{'SCRIPT_FILENAME'}, $0)>.
1337
1338 =item C<srcdump_system_dir($cgi,$verifier,$dir)>
1339
1340 Determines whether C<$dir> is a "system directory", in which any
1341 source code used by the application should nevertheless not be
1342 included in the source code dump.
1343
1344 Used by the default implementation of C<srcdump_item>.
1345
1346 The default implementation is as follows: Things in C</etc/> are
1347 system directories.  Things in C</usr/> are too, unless they are in
1348 C</usr/local/> or C</usr/lib/cgi*>.
1349
1350 =item C<srcdump_filter_cwd>
1351
1352 Boolean which controls the handling of C<.> if it appears in the
1353 return value from C<srcdump_listitems>.  Used only by the default
1354 implementation of C<srcdump_prepare>.
1355
1356 If set to false, C<.> is treated normally and no special action is
1357 taken.
1358
1359 However often the current directory may be C</>, or a data directory,
1360 or some other directory containing data which is confidential, or
1361 should not be included in the public source code distribution for
1362 other reasons.  And for historical reasons Perl has C<@INC> containing
1363 C<.> by default (which is arguably dangerous and wrong).
1364
1365 So the default this setting is true, which has the following effects:
1366
1367 C<.> is not searched for source code even if it appears in C<@INC>.
1368 C<.> is removed from C<@INC> and C<%INC> is checked to see if any
1369 modules appear to have already been loaded by virtue of C<.> appearing
1370 in C<@INC> and if they have it is treated as a fatal error.
1371
1372 Only the literal string C<.> is affected.  If the cwd is included by
1373 any other name it is not treated specially regardless of this setting.
1374
1375 =back
1376
1377 =head1 DATABASE TABLES
1378
1379 In a simple application, you do not need to worry about this.  But if
1380 your application runs on multiple frontend hosts with a shared
1381 database, you may need to create for yourself the tables and indices
1382 used by CGI::Auth::Flexible.
1383
1384 By default, every time CAF starts up, it attempts to execute certain
1385 fixed database statements to create the tables and indices it needs.
1386 These are run with C<$dbh->{PrintError}> set to 0.  The effect with
1387 sqlite (the default database) is that the tables and indices are
1388 created iff they do not already exist, and that no spurious errors are
1389 reported anywhere.
1390
1391 If you use a different database, or just prefer to do things
1392 differently, you can set up the tables yourself and/or disable or
1393 modify the default setup statements, via the C<db_setup_stmts>
1394 setting.
1395
1396 The tables needed are:
1397
1398
1399 xxx document _db_setup_do
1400 xxx make _db_setup_do explicitly overrideable
1401
1402
1403 xxx remaining settings
1404  db_password
1405  username_password_error
1406  login_ok
1407  get_cookie_domain
1408  gettext
1409  print
1410  debug
1411
1412 xxx document cookie usage
1413 xxx document construct_cookie fn
1414
1415 xxx document @default_db_setup_statements
1416
1417 xxx bugs wrong default random on Linux
1418
1419 xxx bugs wrong default random on *BSD
1420
1421 xxx bugs keys not shared should be in db
1422
1423 xxx rename caf_assocsecret default cookie name
1424
1425 xxx mention relationship between login_timeout and cookies