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