chiark / gitweb /
db_setup_stmts: new setting
[cgi-auth-flexible.git] / caf.pod
diff --git a/caf.pod b/caf.pod
index dad4736..8ed5d51 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -367,7 +367,7 @@ Discards the resources (open files, etc.) in the verifier object.
 
 =back
 
-=head REQUEST-RELATED FUNCTIONS AND METHODS
+=head1 REQUEST-RELATED FUNCTIONS AND METHODS
 
 All of these are only valid after C<check_divert> or C<check_ok> has
 been called.  (In the case of C<check_ok> it won't normally be sensible
@@ -409,11 +409,11 @@ whenever it is handling anything except an HTML page loads, it must
 call this function.  See L</REQUEST TYPES>, and
 L<GENERATING URLS, FORMS AND AJAX QUERIES>.
 
-C<check_mutate> will either return successfully, indicating that all
+C<check_nonpage> will either return successfully, indicating that all
 is well and the request should proceed, or it will die, like
 C<check_mutate>.
 
-=head RESPONSE-RELATED FUNCTIONS AND METHODS
+=head1 RESPONSE-RELATED FUNCTIONS AND METHODS
 
 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
 
@@ -461,18 +461,9 @@ Returns the value of the secret cookie.  CGI::Auth::Flexible sets this
 cookie in the forms generated by C<check_ok>.  You may also set it
 yourself (and indeed you must do so if you use C<check_divert>).
 
-=item C<< $authreq->chain_params() >>
-
-Returns a hash of the "relevant" parameters to this request, in a form
-used by XXX.  This is all of the query parameters which are not
-related to CGI::Auth::Flexible.  The PATH_INFO from the request is
-returned as the parameter C<< '' >>.
-
-xxx why use this function
-
 =back
 
-=head OTHER FUNCTIONS AND METHODS
+=head1 OTHER FUNCTIONS AND METHODS
 
 =over
 
@@ -520,8 +511,8 @@ string which will be mentioned in the log.
 
 C<$script> is a shell script fragment which must output a
 nul-separated list of filenames (e.g. the output of C<find -print0>).
-
-xxx blah blah
+It is textually surrounded by C<( )> and will be executed with C<set -e>
+in force.  Its cwd will be C<$dir>.
 
 =item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible-> >>
 
@@ -531,6 +522,198 @@ digits.
 
 =back
 
+=head1 REQUEST TYPES
+
+The C<$reqtype> values understood by C<check_nonpage> are strings.
+They are:
+
+=over
+
+=item C<PAGE>
+
+A top-level HTML page load.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<FRAME>
+
+An HTML frame.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<IFRAME>
+
+An HTML iframe.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<SRCDUMP>
+
+Source dump request, whether for the licence or actual source code
+tarball; returned value is not secret.
+
+=item C<STYLESHEET>
+
+CSS stylesheet.  B<MUST NOT> contain any confidential data.  If the
+stylesheet depends on the user, then attackers may be able to
+determine what stylesheet the user is using.  Hopefully this is not a
+problem.
+
+=item C<FAVICON>
+
+"Favicon" - icon for display in the browser's url bar etc.  We aren't
+currently aware of a way that attackers can get a copy of this.
+
+=item C<ROBOTS>
+
+C<robots.txt>.  Should not contain any confidential data (obviously).
+
+=item C<IMAGE>
+
+Inline image, for an C<< <img src=...> >> element.
+
+Unfortunately it is not possible to sensibly show top-level
+confidential images (that is, have the user's browser directly visit a
+url which resolves to an image rather than an HTML page with an inline
+image).  This is because images need to have a per-session hidden form
+parameter to avoid cross-site scripting, which breaks bookmarks etc.
+
+=item C<SCRIPT>
+
+JavaScript for a C<< <script> >> element.  (Possibly confidential for
+the user.)
+
+=item C<AJAX-XML>
+
+C<< XMLHttpRequest >> returning XML data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-JSON>
+
+C<< XMLHttpRequest >> returning JSON data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-OTHER>
+
+C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
+confidential for the user.)
+
+=back.
+
+=head1 DIVERT SPEC
+
+The return value from C<check_divert> indicates how the request should
+be handled.  It is C<undef> if all is well and the user is logged in.
+
+Otherwise the return value is a hash ref with the following keys:
+
+=over
+
+=item C<Kind>
+
+Scalar string indicating the kind of diversion required.
+
+=item C<Message>
+
+Scalar string for display to the user in relation to the diversion.
+Has already been translated.  In HTML but normally does not contain
+any tags.
+
+=item C<CookieSecret>
+
+The secret cookie which should be set along with whatever response is
+sent to the client.  The value in the hash is the actual secret value
+of the cookie as a string.  C<undef> means no cookie setting header
+should be sent; C<''> means the cookie should be cleared.
+
+=item C<Params>
+
+The extra hidden form parameters (and the C<PATH_INFO>) which should
+be set when the subsequent request bounces back from the client, in
+the form used by C<url_with_query_params>.
+
+The contents of this hashref does not include the CAF-specific
+parameters such as the secret cookie, those which follow from the kind
+of diversion requested, etc.
+
+It is correct to always include the contents of C<Params> as hidden
+parameters in the urls for all redirections, and as hidden input
+fields in all generated forms.  The specific cases where C<Params> is
+currently relevant are also mentioned in the text for each divert
+kind.
+
+=back
+
+The values of C<Kind> are:
+
+=over
+
+=item C<SRCDUMP->I<item>
+
+We should respond by sending our application source code.  I<item>
+(which will contain only word characters, and no lower case) is the
+specific item to send, normally C<SOURCE> or C<LICENCE>.
+
+=item C<REDIRECT-HTTPS>
+
+We should respond with an HTTP redirect to the HTTPS instance of our
+application.
+
+=item C<REDIRECT-LOGGEDOUT>
+
+We should redirect to a page showing that the user has been logged
+out.  (Ie, to a url with one of the the C<loggedout_param_names> set.)
+
+=item C<SMALLPAGE-LOGGEDOUT>
+
+We should generate a page showing that the user has been logged out.
+There can be a link on the page pointing to the login page so that the
+user can log back in.
+
+=item C<SMALLPAGE-NOCOOKIE>
+
+We should generate a page reporting that the user does not have
+cookies enabled.  It should probably contain a link pointing to the
+login page with additionally all the parameters in C<Params>.  When
+this divert spec is generated, C<Message> will explain the problem
+with cookies so there is no need to do that again in the page body if
+you include the contents of C<Message>.
+
+=item C<LOGIN-STALE>
+
+The user's session was stale (this is described in C<Message>).  We
+should generate a login form.
+
+=item C<LOGIN-BAD>
+
+The user supplied bad login credentials.  The details are in
+C<Message>.  We should generate a login form (with additionally the
+parameters from C<Params> as hidden fields).
+
+=item C<LOGIN-INCOMINGLINK>
+
+We should generate a login form (with the specified parameters); the
+user is entering the site via a cross-site link but is not yet logged
+in.
+
+=item C<LOGIN-FRESH>
+
+We should generate a login form.  The user is not yet logged in.
+
+=item C<REDIRECT-LOGGEDIN>
+
+We should redirect to our actual application, with the specified
+parameters.  (The user has just logged in.)
+
+=item C<MAINPAGEONLY>
+
+We should generate our main page but B<ignoring all form parameters>
+and B<ignoring the path_info>.  Most applications will find this
+difficult to implement.
+
+An alternative is to generate a small page with a form or link which
+submits our own main page without any parameters.
+
+(Applications which set C<promise_check_mutate> do not see this divert
+kind.)
+
 =head1 SETTINGS
 
 C<new_verifier> and C<new_request> each take a list of settings, as
@@ -794,7 +977,8 @@ channel.  The default is C<< !!$cgi->https() >>.  See C<encrypted_only>.
 
 =head2 SETTINGS RELATED TO HTML GENERATION
 
-These are only used if you call C<check_ok> or xxx some other functions?.
+These are only used if you call C<check_ok> (or other functions
+mentioned in this section).
 
 Settings whose names are of the form C<gen_...> are hooks which each
 return an array of strings, normally HTML strings, for use by
@@ -988,18 +1172,27 @@ been done and should be skipped; otherwise the hash entry should be set.
 C<\&outfn> is a coderef which C<srcdump_process_item> should call each
 time it wants to generate a file which should be included as part of
 the source code.  It should be called using one of these patterns:
-   $outfn->("message for log");
-   $outfile = $outfn->("message for log", "extension");
-The former simply logs this message (along with the associated
-C<$item>, so there is no need to mention that).  The latter logs the
-message but also generates and returns a filename which should then
+   $outfn->("message for manifest");
+   $outfile = $outfn->("message for manifest", "extension");
+The former simply prints the message into the manifest in the form
+  none: message for manifest
+The latter generates and returns a filename which should then
 be created and filled with some appropriate data.  C<"extension">
 should be a string for the file extension, eg C<"txt">.  The output
 can be written directly to the named file: there is no need to
-write to a temporary file and rename.
+write to a temporary file and rename.  C<$outfn> writes the filename
+and the message to the manifest, in the form
+  filename leaf: message
+In neither case is the actual name of C<$dir> on the system
+disclosed per se although of course some of the contents of some of
+the files in the source code dump may mention it.
 
 The default implementation is the module function
-C<srcdump_process_item>.  It searches the item and its parent
+C<srcdump_process_item>.
+
+It skips directories for which C<srcdump_system_dir> returns true.
+
+It then searches the item and its parent
 directories for a vcs metadata directory (one of the names in
 C<srcdump_vcs_dirs>); if found, it calls the C<srcdump_byvcs> hook
 (after checking and updaeing C<%dirsdone>).
@@ -1027,21 +1220,89 @@ C<$vcs> is derived from the entry of C<srcump_vcs_dirs> which was
 used: it's the first sequence of word characters, lowercased.
 
 The default implementation is the module function C<srcdump_byvcs>.
-It simply calls C<srcdump_dir_cpio> with the script from the setting
-C<srcdump_vcsscript_$vcs>.
+It simply calls C<srcdump_dir_cpio> with a script from the setting
+C<srcdump_vcsscript>.
 
+=item C<srcdump_vcs_dirs>
 
- which is defined
+Array ref of leaf names of vcs metadata directories.  Used by the
+default implementation of C<srcdump_process_item>.  The default value
+is C<['.git','.hg','.bzr','.svn']>.
 
-xxx conditions on listitems implied by srcdump_dirscan_prepare
-xxx listitems enoent behaviour
-The de
+=item C<srcdump_vcs_script>
 
-xxx syntax of srcdump_excludes
+Hash ref of scripts for generating vcs metadata.  Used by the default
+implementation of C<srcdump_byvcs>.  The keys are values of C<$vcs>
+(see C<srcdump_byvcs>); the values are scripts as for
+C<srcdump_dir_cpio>.
 
+The default has an entry only for C<git>:
+  git ls-files -z
+  git ls-files -z --others --exclude-from=.gitignore
+  find .git -print0
 
-=back
+=item C<srcdump_excludes>
+
+Array ref of exclude glob patterns, used by the default implementation
+of C<srcdump_novcs>.  The default value is C<['*~','*.bak','*.tmp','#*#']>.
+
+Entries must not contain C<'> or C<\>.
+
+=item C<srcdump_listitems($cgi,$verifier)>
+
+Returns an array of directories which might contain source code of the
+web application and which should be therefore be considered for
+including in the source code delivery.
+
+Used by the default implementation of C<srcdump_prepare>.
+
+Entries must be directories, plain files, or nonexistent; they may
+also be symlinks which resolve to one of those.
+
+If C<.> is included it may be treated specially - see
+C<srcdump_filter_cwd>.
+
+The default implementation returns 
+C<(@INC, $ENV{'SCRIPT_FILENAME'}, $0)>.
+
+=item C<srcdump_system_dir($cgi,$verifier,$dir)>
 
+Determines whether C<$dir> is a "system directory", in which any
+source code used by the application should nevertheless not be
+included in the source code dump.
+
+Used by the default implementation of C<srcdump_item>.
+
+The default implementation is as follows: Things in C</etc/> are
+system directories.  Things in C</usr/> are too, unless they are in
+C</usr/local/> or C</usr/lib/cgi*>.
+
+=item C<srcdump_filter_cwd>
+
+Boolean which controls the handling of C<.> if it appears in the
+return value from C<srcdump_listitems>.  Used only by the default
+implementation of C<srcdump_prepare>.
+
+If set to false, C<.> is treated normally and no special action is
+taken.
+
+However often the current directory may be C</>, or a data directory,
+or some other directory containing data which is confidential, or
+should not be included in the public source code distribution for
+other reasons.  And for historical reasons Perl has C<@INC> containing
+C<.> by default (which is arguably dangerous and wrong).
+
+So the default this setting is true, which has the following effects:
+
+C<.> is not searched for source code even if it appears in C<@INC>.
+C<.> is removed from C<@INC> and C<%INC> is checked to see if any
+modules appear to have already been loaded by virtue of C<.> appearing
+in C<@INC> and if they have it is treated as a fatal error.
+
+Only the literal string C<.> is affected.  If the cwd is included by
+any other name it is not treated specially regardless of this setting.
+
+=back
 
 =head1 DATABASE TABLES
 
@@ -1054,11 +1315,17 @@ xxx document _db_setup_do
 xxx make _db_setup_do explicitly overrideable
 
 
-xxx divert spec
-xxx reqtype
-xxx settings
-xxx html generators
-xxx document cookie
+xxx remaining settings
+ assocdb_password
+ username_password_error
+ login_ok
+ get_cookie_domain
+ gettext
+ print
+ debug
+
+xxx document cookie usage
+xxx document construct_cookie fn
 
 xxx bugs wrong default random on Linux
 xxx bugs wrong default random on *BSD