chiark / gitweb /
docs: more work
[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 simplist usage is to call C<< $request->check_ok() >> which will
137 check the user's authentication.  If the user is not logged in it will
138 generate a login form (or redirection or other appropriate page) and
139 return false; your application should not then processing that request
140 any further.  If the user is logged in it will return true.
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
149 =head2 Sophisticated applications
150
151 If you want to handle the control flow and to generate login forms,
152 redirections, etc., yourself, you can say
153 C<< $divert = $request->check_divert >>.  This returns undef if
154 the user is logged in, or I<divert spec> if some kind of login
155 page or diversion should be generated.  See L</DIVERT SPEC> below for
156 details of how to deal with the return value.
157
158 =head2 MUTATING OPERATIONS AND EXTERNAL LINKS
159
160 =head3 Mutation-ignorant applications
161
162 By default CGI::Auth::Flexible does not permit external links into
163 your site.  All GET requests give a "click to continue" page which
164 submits a form which loads your app's main page.  In this
165 configuration all your application's forms and AJAX requests should
166 use C<POST>.  This restriction arises from complicated deficiencies
167 in the web's security architecture.
168
169 Such applications are also not able to provide user-specific CSS
170 stylesheets, javascript, favicons, etc.
171
172 =head3 Mutation-aware applications
173
174 The alternative is for your application to always make a special check
175 when the incoming request is going to do some kind of action (such as
176 modifying the user's setup, purchasing goods, or whatever) rather than
177 just retrieve and/or display information.  We term such requests
178 "mutating" requests.
179
180 Then non-mutating pages can be linked to from other, untrustworthy,
181 websites.
182
183 To support external links, and C<GET> requests, pass
184 C<< promise_check_mutate => 1 >> in I<settings>, and then call
185 C<< $authreq->check_mutate() >> before taking any actions.  If the
186 incoming request is not suitable then C<< $authreq->check_mutate() >>
187 will call C<die>.
188
189 There have to be no mutating C<GET> requests in your application (but
190 you shouldn't have any of those anyway); if there are, they won't
191 work.  (CGI::Auth::Flexible will spot them and cause them to fail,
192 rather than allow them to be insecure.)
193
194 =head2 GENERATING URLS, FORMS AND AJAX QUERIES
195
196 When you generate a URL, C<POST> form or AJAX request you may need to
197 include a secret hidden form parameter for the benefit of
198 CGI::Auth::Generic.  This form parameter will be checked by
199 C<check_ok>/C<check_divert> and should be ignored by your application.
200
201 By default the hidden parameter is called C<caf_assochash>.
202
203 After calling C<check_ok> or C<check_divert> the value to put in your
204 form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
205 will generate the whole HTML C<< <input...> >> element.
206
207 =head3 Mutation-ignorant applications
208
209 For mutation-ignorant applications (see above), all forms etc. should
210 include the hidden parameter (and as discussed, they must all use
211 POST rather than GET).
212
213 =head3 Mutation-aware applications
214
215 For mutation-aware applications, whether to include the secret
216 parameter depends on the kind of request.  CGI::Auth::Flexible knows
217 when it is necessary.  You should find out by calling
218 C<need_add_hidden>.
219
220 If it is inconvenient to call C<need_add_hidden> at runtime, you can
221 rely instead on the following promises:  All POST requests (which
222 includes all mutating requests) need the parameter.  The return value
223 of need_add_hidden depends only on the $method and $reqtype
224 parameters, so you can query it once and remember the answer.
225 HTML page load GETs do not need the parameter.  It is better to
226 err on the side of including the parameter.
227
228 If you really must, you can call C<need_add_hidden> "on the bench"
229 during development and bake the answer into your application code
230 structure.  However, if you do that and a new vulnerability was
231 discovered which is fixed by changing the answer, updating
232 CGI::Auth::Flexible wouldn't be sufficient to fix it.
233
234 =head3 Mutation-aware applications - non-page requests
235
236 If your mutation-aware application supports non-page resources (AJAX
237 and JSON requests, stylesheets, favicons, etc.) it must inform
238 CGI::Auth::Flexible when it is handling such a request, by calling
239 C<check_nonpage>.
240
241 Normally C<check_nonpage> will simply return (and you can ignore the
242 return value).  However, if there is an attack (or, perhaps, a bug) it
243 will die, stopping the attack.
244
245 (You do not need to call C<check_nonpage> for POST requests, but it is
246 harmless to do so.)
247
248 =head3 Mutation-aware applications - novel kinds of request
249
250 If you want to support a kind of request perhaps not yet known about
251 by CGI::Auth::Flexible, you can provide information about that new
252 request kind using C<update_get_need_add_hidden>.
253
254 =head2 DATA STORAGE
255
256 CGI::Auth::Flexible needs to store various information in plain files;
257 it does this in the directory specified by the C<dir> parameter.
258
259 =head1 SOURCE CODE DOWNLOAD
260
261 By default, CGI::Auth::Flexible provides a facility for users to
262 download the source code for the running version of your web
263 application.
264
265 This facility makes a number of important assumptions which you need
266 to check.  Note that if the provided facility is not sufficient
267 because your application is more sophisticated than it copes with (or
268 if you disable the builtin facility), you may need to implement a
269 functioning alternative to avoid violating the AGPLv3 licence.
270
271 Here are the most important (default) assumptions:
272
273 =over
274
275 =item *
276
277 Your app's source code is available by looking at @INC, $0 and
278 S<$ENV{'SCRIPT_FILENAME'}> (the B<source items>).  See
279 C<srcdump_listitems>.  Where these point to files or directories under
280 revision control, the source item is the whole containing vcs tree.
281
282 =item *
283
284 Specifically, there are no compiled or autogenerated Perl
285 files, Javascript resources, etc., which are not contained in one of
286 the source item directories.  (Files which came with your operating
287 system install don't need to be shipped as they fall under the system
288 library exception.)
289
290 =item *
291
292 You have not installed any modified versions of system
293 libraries (including system-supplied Perl modules) in C</usr> outside
294 C</usr/local>.  See C<srcdump_system_dir>.
295
296 =item *
297
298 For each source item in a dvcs, the entire dvcs history does
299 not contain anything confidential (or libellous).  Also, all files which
300 contain secrets are in the dvcs's I<.ignore> file.  See
301 C<srcdump_vcsscript_git> et al.
302
303 =item *
304
305 For each source item NOT in a dvcs, there are no confidential
306 files with the world-readable bit set (being in a world-inaccessible
307 directory is not sufficient).  See C<srcdump_excludes>.
308
309 =item *
310
311 You have none of your app's source code in C</etc>.
312
313 =item *
314
315 You don't regard pathnames on your server as secret.
316
317 =item *
318
319 You don't intentionally load Perl code by virtue of C<.>
320 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
321
322 =back
323
324 =head1 MAIN FUNCTIONS AND METHODS
325
326 =over
327
328 =item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
329
330 Initialises an instance and returns a verifier object.
331 The arguments are setting pairs like a hash initialiser.
332 See L</SETTINGS> below.
333
334 =item C<< $verifier->new_request($cgi) >>
335
336 Prepares to process a request.  I<$cgi> should normally
337 be the query object from L<CGI(3perl)>.  Most of the default
338 hook methods assume that it is; however if you replace enough of
339 the hook methods then you can pass any value you like and it
340 will be passed to your hooks.
341
342 The return value is the authentication request object (I<$authreq>)
343 which is used to check the incoming request and will contain
344 information about its credentials.
345
346 =item C<< $authreq->check_divert() >>
347
348 Checks whether the user is logged in.  Returns undef if the user is
349 logged in and we should service the request.  Otherwise returns a
350 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
351
352 This method may die if it doesn't like the request, in which case
353 the request needs to be rejected.
354
355 =item C<< $authreq->check_ok() >>
356
357 Checks whether the user is logged in.  Returns true if the user is
358 logged in and we should service the request.
359
360 Otherwise it handles the request itself, generating any appropriate
361 redirect, login form, or continuation page.  It then returns false and
362 the application should not process the request further.
363
364 =item C<< $verifier->disconnect() >>
365
366 Discards the resources (open files, etc.) in the verifier object.
367
368 =back
369
370 =head REQUEST-RELATED FUNCTIONS AND METHODS
371
372 All of these are only valid after C<check_divert> or C<check_ok> has
373 been called.  (In the case of C<check_ok> it won't normally be sensible
374 to call these functions unless C<check_ok> returned true.)
375
376 =item C<< $authreq->get_divert() >>
377
378 Returns the value previously returned by C<check_divert>.
379
380 =item C<< $authreq->get_username() >>
381
382 Returns the name of the logged-in user.  If the user was not logged
383 in (or their session had timed out, or something), returns undef.
384
385 =item C<< $authreq->check_mutate() >>
386
387 Declares to CGI::Auth::Generic that the request being handled will
388 "mutate".  That is, it will modify some server-side state (eg, adding
389 items to shopping baskets, posting messages to blogs, sending emails,
390 or whatever).
391
392 If you have set the setting C<promise_check_mutate> you must call
393 C<check_mutate> whenever appropriate.  If you haven't then it's
394 irrelevant.  See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
395
396 C<check_mutate> will either return successfully, indicating that all
397 is well and the request should proceed, or it will die.  If it dies
398 that means that the request was improper, which can only result from a
399 bug or an attack.  So an "internal server error" is a suitable
400 response.
401
402 =item C<< $authreq->check_nonpage($method, $reqtype) >>
403
404 Declares to CGI::Auth::Generic that the request is not a page request,
405 but rather a request of type I<$reqtype>.
406
407 If your application has set the setting C<promise_check_mutate>,
408 whenever it is handling anything except an HTML page loads, it must
409 call this function.  See L</REQUEST TYPES>, and
410 L<GENERATING URLS, FORMS AND AJAX QUERIES>.
411
412 C<check_mutate> will either return successfully, indicating that all
413 is well and the request should proceed, or it will die, like
414 C<check_mutate>.
415
416 =head RESPONSE-RELATED FUNCTIONS AND METHODS
417
418 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
419
420 Convenience function which returns a url for a GET request to this
421 application.
422
423 I<$params> is a hashref specifying the parameters and the PATH_INFO.
424 The keys are the parameter names, and the values are array refs with
425 the parameter value(s) (as strings, as yet unquoted).  (They are array
426 refs because it is possible to pass multiple values for the same
427 parameter in a single request; normally each arrayref would be a
428 singleton.)
429
430 The request path will be the path to the application.  If a parameter
431 with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
432 value will be appended to the application path.  (It should normally
433 start with C<< / >>, and only one value should be supplied.)
434
435 =item C<< something->need_add_hidden($method, $reqtype) >>
436
437 Enquires whether a request of type I<$reqtype> using HTTP method
438 I<$method> needs the hidden form parameter.  See L</REQUEST TYPES>.
439
440 =item C<< something->secret_hidden_val() >>
441
442 Returns the value of the hidden form parameter.  This should be
443 included in all POST requests to your application (and thus be a
444 hidden form parameter in all forms).
445
446 It should also be in some (maybe all) GET requests.  If your
447 application is mutation-ignorant, it should be in all GET requests.
448 If you are mutation-aware, you need to consult C<need_add_hidden>.
449
450 The name of the hidden parameter is the setting C<assoc_param_name>,
451 C<caf_hassochash> by default.  xxx rename param and setting
452
453 =item C<< something->secret_hidden_html() >>
454
455 Returns the HTML for an C<INPUT> element specifying the hidden form
456 parameter.
457
458 =item C<< something->secret_cookie_val() >>
459
460 Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
461 cookie in the forms generated by C<check_ok>.  You may also set it
462 yourself (and indeed you must do so if you use C<check_divert>).
463
464 =item C<< $authreq->chain_params() >>
465
466 Returns a hash of the "relevant" parameters to this request, in a form
467 used by C<url_with_query_params>.  This is all of the query parameters
468 which are not related to CGI::Auth::Flexible.  The PATH_INFO from the
469 request is returned as the parameter C<< '' >>.
470
471 xxx why use this function
472
473 =back
474
475 =head OTHER FUNCTIONS AND METHODS
476
477 =over
478
479 =item C<< $verifier_or_authreq->hash($data) >>
480
481 Hashes the supplied data using the hash function specified by the
482 C<hash_algorithm> setting, and converts the result to a string of hex
483 digits.
484
485 =item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
486
487 Updates CGI::Auth::Generic's knowledge about the various kinds of
488 request, and whether they need the hidden form parameter.  This
489 function applies only to GET requests - POST requests always use the
490 parameter.
491
492 I<$reqtype> is the request type (the value which will be passed to
493 C<check_nonpage> and C<need_add_hidden>.  If you are supporting a new
494 I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
495 or other users, to assign a unique request type name.
496
497 This method may be called on an authreq or a verifier, in which case
498 it will affect all authreqs using the same verifier.  Or it may be
499 called on the class as a whole, in which case it will affect the
500 global default list for all verifiers.
501
502 If I<$force> is supplied and true, this will override
503 CGI::Auth::Flexible's existing knowledge.  Otherwise this new setting
504 will be ignored if CGI::Auth::Flexible already knows about the request
505 type.  (When called on a verifier or authreq, it will ignore the
506 update in favour of existing knowledge recorded both globally in the
507 class or due to previous requests on the same verifier.)
508
509 See L</REQUEST TYPES>.
510
511 =item C<< CGI::Auth::Flexible::srcdump_dir_cpio($cgi,$verifier,$dumpdir,$dir,$outfn,$how,$script) >>
512
513 Helper function for implementing the C<srcdump_process_item> hook.
514 Generates a tarball using cpio and includes it in the prepared source
515 code distribution.
516
517 The arguments are mostly the same as for that hook.  C<$dir> is the
518 root directory at which to start the archive.  C<$how> is a short text
519 string which will be mentioned in the log.
520
521 C<$script> is a shell script fragment which must output a
522 nul-separated list of filenames (e.g. the output of C<find -print0>).
523 It is textually surrounded by C<( )> and will be executed with C<set -e>
524 in force.  Its cwd will be C<$dir>.
525
526 =item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible-> >>
527
528 Hashes the supplied data using the hash function specified by the
529 C<hash_algorithm> setting, and converts the result to a string of hex
530 digits.
531
532 =back
533
534 =head1 SETTINGS
535
536 C<new_verifier> and C<new_request> each take a list of settings, as
537 a list of pairs C<< key => value >> (like a Perl hash assignment).
538
539 The settings supplied to C<new_verifier> are stored in the verifier
540 and will apply to all authreqs made from it unless overridden in the
541 call to C<new_request>
542
543 When a setting is described as a hook function, it should be a
544 coderef.  The first argument will be the query object from
545 L<CGI(3perl)> (strictly, it will be whatever value was passed to
546 C<new_request>).  The second argument will be the authreq object (the
547 return value from C<new_request>).
548 Ie, C<< sub some_hook ($$...) { my ($cgi,$authreq,@stuff) = @_ ... >>
549
550 In bullet point headings, the hook functions are shown in the form
551 C<< some_hook($cgi,$authreq,@stuff) >> even though this would not be
552 legal syntax.  This should be read to mean that the
553 %implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff)
554 would be a legal call.  (However, the settings hash is not exposed.)
555
556 When a hook's default implementation is mentioned and named, that
557 function won't also be described in the section on the module's
558 functions.
559
560 =over
561
562 =head2 GENERAL SETTINGS
563
564 =item C<dir>
565
566 The directory CGI::Auth::Generic should use for its data storage.
567 This is actually just a default absolute path used when the other
568 path settings are relative values.
569
570 Must be an absolute filename.
571
572 =item C<assocdb_dbh>
573
574 CGI::Auth::Flexible needs a database for recording users' login
575 session.  This database needs to be shared across all instances of the
576 web application, so in a multi-node cluster it needs to be your actual
577 database.
578
579 CGI::Auth::Flexible will create the table and index it needs if they
580 don't already exist, and will manage their contents.  You do not need
581 to integrate them into the rest of your webapp's data storage.  (In
582 particular, there is no need for transactional integrity across
583 changes made by CAF and your own application.)
584
585 By default, CAF uses a sqlite3 database stored on local disk in the
586 file named by C<assocdb_path>.  This will be suitable for all
587 applications which run on a single host.
588
589 This value, if supplied, should be a DBI handle for the database.
590
591 =item C<assocdb_dsn>
592
593 This is the DSN to pass to C<< DBI->connect >>.  Used only if
594 C<assocdb_dbh> is not supplied.
595
596 =item C<assocdb_path>
597
598 Path to the sqlite3 database used for CAF's session storage.  The
599 default is currently C<caf-assocs.db> but will change in the future.
600
601 Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
602
603 If this is a relative path, it is in C<dir>.
604
605 =item C<assocdb_table>
606
607 Prefix for the SQL tables and indices to use (and to create, if
608 necessary).
609
610 See L</DATABASE TABLES>.
611
612 =item C<keys_path>
613
614 Path to the keys file used by CAF.  This arrangement will change in
615 the future.  See L</BUGS>.
616
617 =item C<random_source>
618
619 Special file to read random numbers from.  Should return
620 cryptographically secure (pseudo)-random bytes, unpredictable to
621 adversaries (even ones on the same machine).
622
623 On Linux, there is no device which is properly suitable.  This is a
624 bug in Linux.  You can use C</dev/random> which can block
625 unnecessarily even though the kernel PRNG has been properly seeded and
626 is fine, or C</dev/urandom> which might return values which attackers
627 can predict if the kernel PRNG has not been properly seeded.
628
629 The default is C</dev/urandom>.
630
631 =item C<secretbits>
632
633 Length of the assoc secret.  Defaults to 128.
634
635 =item C<hash_algorithm>
636
637 Must be a string suitable for use with C<new Digest>.
638 Defaults to C<SHA-256>.
639
640 =item C<login_timeout>
641
642 A user will be logged out this many seconds after they first logged
643 in.  Default: 86400 (one day).
644
645 =item C<login_form_timeout>
646
647 A login form becomes invalid this many seconds after it has been sent.
648 Default: 3600 seconds (one hour).
649
650 =item C<key_rollover>
651
652 The key used for generating assoc secrets is rolled over approximately
653 this often (in seconds).  Default: 86400.
654
655 =item C<assoc_param_name>
656
657 Name of the hidden form parameter.  Default: C<caf_assochash>.
658
659 =item C<cookie_name>
660
661 Name of the cookie used for login sessions.  Default:
662 C<caf_assocsecret>.
663
664 =item C<password_param_name>
665
666 Name of the password field in the login form.  Default: C<password>.
667
668 Used by C<login_ok_password> (the default C<login_ok> hook),
669 C<gen_plain_login_form> and the default C<is_login> hook.
670
671 =item C<username_param_names>
672
673 Arrayref of name(s) of username form parameters.
674
675 The first entry is used by C<login_ok_password> (the default
676 C<login_ok> hook) to pass to the C<username_password_error> hook and
677 used as the username if all is well.
678
679 All the entries are used by C<gen_plain_login_fork> (the default
680 C<gen_login_form> hook for C<check_ok>) to generate form entry fields.
681
682 The default is C<['username']>.
683
684 =item C<logout_param_names>
685
686 Arrayref of name(s) of form parameters indicating that the request is
687 a logout request.
688
689 Used by the default C<is_logout> hook.
690
691 If you want users to be able to explicitly log out, you need to
692 provide a logout button, something like
693 C<< <input type="submit" name="caf_logout" ...>>
694
695 The default is C<['caf_logout']>
696
697 =item C<logged_param_names>
698
699 Arrayref of name(s) of form parameters indicating that user has just
700 logged out.  (During the logout process, the actual logout action is a
701 POST request, whose response redirects to the "you have been logged
702 out" page; these form parameters are for this second page.)
703
704 Used by the default C<is_loggedout> hook.
705
706 The first entry is used by C<check_ok> to generate the redirection.
707
708 The default is C<['caf_loggedout']>
709
710 =item C<promise_check_mutate>
711
712 Boolean.  If true, is a declaration by the application that it is
713 mutatin-aware.  See L</MUTATING OPERATIONS AND EXTERNAL LINKS>.
714
715 The default is 0.
716
717 =item C<encrypted_only>
718
719 Boolean.  If true, CAF will insist that all transactions be done over
720 an encrypted http connection.  It will redirect unencrypted requests
721 to the https instance of the applicattion, and will set the encrypted
722 only flag on its cookie.
723
724 The default is 1.
725
726 =back
727
728 =item C<< get_url($cgi,$authreq) >>
729
730 Hook which returns the URL of this web application.  By default, we
731 call C<< $cgi->url() >> for each request, but you can fix this if you
732 prefer.
733
734 =item C<< is_login,is_logout,is_loggedout($cgi,$authreq) >>
735
736 Hook which returns a boolean indicating whether the request was,
737 respectively: a login form submission (ie, username and password); a
738 logout request (submission resulting from the user pressing the
739 "logout" button); "logged out" page (redirection from the logout
740 POST).
741
742 The default is to check whether any of the corresponding request
743 parameters (C<< login_param_names >> etc.) was supplied, using the
744 C<get_param> hook.
745
746 =back
747
748 =head2 SETTINGS (HOOKS) RELATED TO THE CGI REQUEST OBJECT
749
750 =over
751
752 =item C<< get_param($cgi,$authreq,$param) >>
753
754 Returns the value of a single-valued form parameter.
755 The default is to call C<< $cgi->param($param) >>.
756 The semantics are the same as that of C<CGI::param>.
757
758 =item C<< get_params($cgi,$authreq) >>
759
760 Returns a hash of the parameters.  The return value is a hashref whose
761 keys are the parameter names and whose values are arrayrefs, one entry
762 in the arrayref for each value.
763
764 The default is to call C<< $cgi->Vars() >>, expect the
765 results to look like those from C<CGI::Vars>, and massage them into
766 the required form with split.
767
768 =item C<< get_path_info($cgi,$authreq) >>
769
770 Returns the PATH_INFO of the request.  The default is to
771 call C<< $cgi->path_info() >>.
772
773 =item C<< get_cookie($cgi,$authreq) >>
774
775 Returns the value of the CAF cookie sent with the request, or undef if
776 none was supplied.  The default is to call C<<
777 $cgi->cookie($cookie_name) >> (where C<$cookie_name> is from the
778 setting of the same name).  The return value should be the scalar
779 value of the cookie.
780
781 =item C<< get_method($cgi,$authreq) >>
782
783 Returns the HTTP method as a string.  The default is to call
784 C<< $cgi->request_method() >>.
785
786 =back
787
788 =item C<< is_https($cgi,$authreq) >>
789
790 Returns a boolean indicating whether the request was over an encrypted
791 channel.  The default is C<< !!$cgi->https() >>.  See C<encrypted_only>.
792
793 =back
794
795 =head2 SETTINGS RELATED TO HTML GENERATION
796
797 These are only used if you call C<check_ok> or xxx some other functions?.
798
799 Settings whose names are of the form C<gen_...> are hooks which each
800 return an array of strings, normally HTML strings, for use by
801 C<check_ok> (or, in turn, other hooks, or your application).  These
802 are often documented simply by showing the output produced.  In many
803 cases parts of the output are in turn obtained from other hooks.  In
804 some cases the default implementations have been given names for
805 convenient use by your application.  They will be called in array
806 context.
807
808 We'll write C<gettext(something)> even though actually there is a hook
809 to control the translation function used.
810
811 =over
812
813 =item C<handle_divert>($cgi,$authreq,$divert))
814
815 C<check_ok> calls this hook before producing output of its own.  If
816 you want to handle some but not all diversions yourself, you may set
817 this hook.  The hook should either do nothing and return false, or
818 return true if it has handled the request (or arrange for the request
819 to be handled).  If the hook returns true then C<check_ok> simply
820 returns 0.
821
822 =item C<gen_login_form>($cgi,$authreq,$divert))
823
824 Default: a table (used mostly for layout) containing input fields for
825 a login form.  Must be within a C<< <form> >> element, but doesn't
826 generate it.  Has text fields for every entry in
827 C<username_param_names> (in each case associated with a description
828 C<< gettext(ucfirst $parameter_name) >>, a password field (with
829 description C<gettext("Password")>, and a login submit button (with
830 description C<gettext("Login")>.
831
832 Default is available as the module function C<gen_plain_login_form>.
833
834 =item C<gen_login_link>($cgi,$authreq))
835
836 Default:
837
838  <a href="http:...">gettext(Log in again to continue.)</a>
839
840 Default is available as the module function C<gen_plain_login_link>.
841
842 =item C<gen_postmainpage_form>($cgi,$authreq,$params))
843
844 Default: form contents (but not the C<< <form> >> element):
845
846 C<$params> (in the form returned by the C<get_params> hook) as hidden
847 fields, and also:
848
849  <input type="submit" ... value=getext('Continue')>
850
851 Default is available as the module function C<gen_postmainpage_form>.
852
853 =item C<gen_start_html>($cgi,$authreq,$title)
854
855 Default: C<$cgi->start_html($title)>
856
857 =item C<gen_end_html>($cgi,$authreq,$title)
858
859 Default: C<$cgi->end_html($title)>
860
861 =item C<gen_footer_html>($cgi,$authreq)>
862
863 Default:
864
865  <hr><address>
866  Powered by Free / Libre / Open Source Software
867  according to the [gen_licence_link_html].
868  [gen_source_link_html].
869  </address>
870
871 Default is available as the module function C<gen_plain_footer_html>.
872
873 =item C<gen_licence_link_html>($cgi,$authreq)>
874
875 Default: uses C<url_with_query_params> to generate a URL for
876 downloading the licence, and returns:
877   <a href="...">GNU Affero GPL</a>
878
879 Default is available as the module function C<gen_plain_licence_link_html>.
880
881 =item C<gen_source_link_html>($cgi,$authreq)>
882
883 Default: uses C<url_with_query_params> to generate a URL for
884 downloading the source, and returns:
885   <a href="...">Source available</a>
886
887 Default is available as the module function C<gen_plain_source_link_html>.
888
889 =item C<form_entry_size>
890
891 Size of generated text entry fields.  Default is 60.
892
893 =item C<dummy_param_name_prefix>
894
895 Some of CAF's HTML-generating functions need to invent form parameter
896 names.  They will all start with this string.  Default: C<caf__>.
897
898 =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
899
900 =over
901
902 =item C<srcdump_param_name>
903
904 Form parameter name used to indicate that this is a source download
905 request.  If this parameter is supplied, C<check_ok> and
906 C<check_divert> will arrange for the applicaton source code to be
907 delivered as the response (in C<check_ok>'s case by doing it itself
908 and in C<check_divert>'s case by asking your application to do so.
909
910 Default is C<caf_srcdump>.
911
912 =item C<srcdump_path>
913
914 Path to the directory used for storing pre-prepared source downloads.
915 Defaults to C<caf-srcdump>.
916
917 If this is a relative path, it is in C<dir>.
918
919 =item C<srcdump_dump($cgi,$authreq,$srcobj)>
920
921 Dump the source code (C<$srcobj='source'> or licence data
922 (C<$srcobj='licence'>).  The default implementation checks that
923 C<$srcobj> has reasonable syntax and uses the files C<$srcobj.data>
924 and C<$srcobj.ctype> with the C<dump> hook.
925
926 =item C<dump($cgi,$authreq,$contenttype,$datafilehandle)>
927
928 Responds to the request by sending the contents of $datafilehandle
929 (which should just have been opened) and specifying a content type of
930 $contenttype.
931
932 The default implmentation uses the C<print> hook, and also calls
933 C<$cgi->header('-type' => $contenttype>, and is available as the
934 module function C<dump_plain>.
935
936 =item C<srcdump_prepare($cgi,$verifier)>
937
938 Prepares the source code for download when requested.  Invoked by
939 C<new_verifier>, always, immediately before it returns the
940 just-created verifier object.
941
942 The default implementation is the module function
943 C<srcdump_dirscan_prepare>, which prepares a manifest, licence file
944 and source code tarball of tarballs, as follows:
945
946 It processes each entry in the return value from C<srcdump_listitems>.
947 These are the software's include directories and any other directories
948 containing source code.  It handles C<.> specially (see
949 C<srcdump_filter_cwd>).
950
951 For each entry it looks, relative to that, for the licence as a file
952 with a name mentioned in C<srcdump_licence_files>.  The first such
953 file found is considered to be the licence.  It then calls the hook
954 C<srcdump_process_item> for the entry.
955
956 The licence, a manifest file, and all the outputs generated by the
957 calls to C<srcdump_process_item>, are tarred up and compressed as a
958 single source tarball.
959
960 It uses the directory named by C<srcdump_path> as its directory for
961 working and output files.  It uses the filename patterns
962 C<generate.*>, C<licence.*>, C<s.[a-z][a-z][a-z].*>, C<manifest.*>,
963 C<source.*> in that directory.
964
965 =item C<srcdump_process_item>($cgi,$verifier,$dumpdir,$item,\&outfn,\$needlicence,\%dirsdone)>
966
967 Processes a single include directory or software entry, so as to
968 include the source code found there.  Called only by the default
969 implementation of C<srcdump_prepare>.
970
971 C<$dumpdir> is the directory for working and output files.  C<$item>
972 is the real (no symlinks) absolute path to the item.
973
974 C<\$needlicence> is a ref to a scalar: this scalar is undef if we have
975 already found the licence file; otherwise it is the filename to which
976 the licence should be copied.  If the referent is undef on entry,
977 C<srcdump_process_item> needs to see if it finds the licence; if it
978 does it should copy it to the named file and then set the scalar to
979 undef.
980
981 C<\%dirsdone> is a ref to the hash used by C<srcdump_prepare> to avoid
982 including a single directory more than once.  If
983 C<srcdump_process_item> decides to process a directory other than
984 C<$item> it should check this hash with the real absolute path of the
985 other directoy as a key: if the hash entry is true, it has already
986 been done and should be skipped; otherwise the hash entry should be set.
987
988 C<\&outfn> is a coderef which C<srcdump_process_item> should call each
989 time it wants to generate a file which should be included as part of
990 the source code.  It should be called using one of these patterns:
991    $outfn->("message for log");
992    $outfile = $outfn->("message for log", "extension");
993 The former simply logs this message (along with the associated
994 C<$item>, so there is no need to mention that).  The latter logs the
995 message but also generates and returns a filename which should then
996 be created and filled with some appropriate data.  C<"extension">
997 should be a string for the file extension, eg C<"txt">.  The output
998 can be written directly to the named file: there is no need to
999 write to a temporary file and rename.
1000
1001 The default implementation is the module function
1002 C<srcdump_process_item>.
1003
1004 It skips directories for which C<srcdump_system_dir> returns true.
1005
1006 It then searches the item and its parent
1007 directories for a vcs metadata directory (one of the names in
1008 C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
1009 (after checking and updaeing C<%dirsdone>).
1010 Otherwise it calls the C<srcdump_novcs> hook.
1011
1012 =item C<srcdump_novcs($cgi,$verifier,$dumpdir,$item,$outfn)>
1013
1014 Called by the default implementation of C<srcdump_process_item>, with
1015 the same arguments, if it doesn't find vcs metadata.
1016
1017 The default implementation is the module function C<srcdump_novcs>.
1018
1019 If C<$item> is a directory, it uses C<srcdump_dir_cpio> to prepare a
1020 tarball of all the files under C<$item> which have the world read bit
1021 set.  Directories are not included (and their permissions are
1022 disregarded).  The contents of C<srcdump_excludes> are excluded.
1023
1024 If it's a plain file it uses C<srcdump_file> to include the file.
1025
1026 =item C<srcdump_byvcs($cgi,$verifier,$dumpdir,$item,$outfn,$vcs)>
1027
1028 Called by the default implementation of C<srcdump_process_item>, with
1029 the same arguments, if it finds vcs metadata.  The additional argument
1030 C<$vcs> is derived from the entry of C<srcump_vcs_dirs> which was
1031 used: it's the first sequence of word characters, lowercased.
1032
1033 The default implementation is the module function C<srcdump_byvcs>.
1034 It simply calls C<srcdump_dir_cpio> with a script from the setting
1035 C<srcdump_vcsscript>.
1036
1037 =item C<srcdump_vcs_dirs>
1038
1039 Array ref of leaf names of vcs metadata directories.  Used by the
1040 default implementation of C<srcdump_process_item>.  The default value
1041 is C<['.git','.hg','.bzr','.svn']>.
1042
1043 =item C<srcdump_vcs_script>
1044
1045 Hash ref of scripts for generating vcs metadata.  Used by the default
1046 implementation of C<srcdump_byvcs>.  The keys are values of C<$vcs>
1047 (see C<srcdump_byvcs>); the values are scripts as for
1048 C<srcdump_dir_cpio>.
1049
1050 The default has an entry only for C<git>:
1051   git ls-files -z
1052   git ls-files -z --others --exclude-from=.gitignore
1053   find .git -print0
1054
1055 =item C<srcdump_excludes>
1056
1057 Array ref of exclude glob patterns, used by the default implementation
1058 of C<srcdump_novcs>.  The default value is C<['*~','*.bak','*.tmp','#*#']>.
1059
1060 Entries must not contain C<'> or C<\>.
1061
1062 =item C<srcdump_listitems($cgi,$verifier)>
1063
1064 Returns an array of directories which might contain source code of the
1065 web application and which should be therefore be considered for
1066 including in the source code delivery.
1067
1068 Used by the default implementation of C<srcdump_prepare>.
1069
1070 Entries must be directories, plain files, or nonexistent; they may
1071 also be symlinks which resolve to one of those.
1072
1073 If C<.> is included it may be treated specially - see
1074 C<srcdump_filter_cwd>.
1075
1076 The default implementation returns 
1077 C<(@INC, $ENV{'SCRIPT_FILENAME'}, $0)>.
1078
1079 =item C<srcdump_system_dir($cgi,$verifier,$dir)>
1080
1081 Determines whether C<$dir> is a "system directory", in which any
1082 source code used by the application should nevertheless not be
1083 included in the source code dump.
1084
1085 Used by the default implementation of C<srcdump_item>.
1086
1087 The default implementation is as follows: Things in C</etc/> are
1088 system directories.  Things in C</usr/> are too, unless they are in
1089 C</usr/local/> or C</usr/lib/cgi*>.
1090
1091 =item C<srcdump_filter_cwd>
1092
1093 Boolean which controls the handling of C<.> if it appears in the
1094 return value from C<srcdump_listitems>.  Used only by the default
1095 implementation of C<srcdump_prepare>.
1096
1097 If set to false, C<.> is treated normally and no special action is
1098 taken.
1099
1100 However often the current directory may be C</>, or a data directory,
1101 or some other directory containing data which is confidential, or
1102 should not be included in the public source code distribution for
1103 other reasons.  And for historical reasons Perl has C<@INC> containing
1104 C<.> by default (which is arguably dangerous and wrong).
1105
1106 So the default this setting is true, which has the following effects:
1107
1108 C<.> is not searched for source code even if it appears in C<@INC>.
1109 C<.> is removed from C<@INC> and C<%INC> is checked to see if any
1110 modules appear to have already been loaded by virtue of C<.> appearing
1111 in C<@INC> and if they have it is treated as a fatal error.
1112
1113 Only the literal string C<.> is affected.  If the cwd is included by
1114 any other name it is not treated specially regardless of this setting.
1115
1116 =back
1117
1118 =head1 DATABASE TABLES
1119
1120 In a simple application, you do not need to worry about this.  But if
1121 your application runs on multiple frontend hosts with a shared
1122 database, you may need to create for yourself the tables and indices
1123 used by CGI::Auth::Flexible.
1124
1125 xxx document _db_setup_do
1126 xxx make _db_setup_do explicitly overrideable
1127
1128
1129 xxx divert spec
1130 xxx reqtype
1131 xxx settings
1132 xxx html generators
1133 xxx document cookie
1134
1135 xxx bugs wrong default random on Linux
1136 xxx bugs wrong default random on *BSD
1137 xxx bugs keys not shared should be in db
1138 xxx rename caf-assocs.db
1139 xxx rename caf_assocsecret default cookie name
1140 xxx mention relationship between login_timeout and cookies