From 466a236a669f5cc8e382d29435b01ff4ae642aec Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 21 Mar 2013 17:10:14 +0000 Subject: [PATCH] docs: more work --- caf.pod | 254 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 231 insertions(+), 23 deletions(-) diff --git a/caf.pod b/caf.pod index aa9566b..2f57270 100644 --- a/caf.pod +++ b/caf.pod @@ -7,7 +7,7 @@ CGI::Auth::Flexible - web authentication optionally using cookies =head1 SYNOPSYS my $verifier = CGI::Auth::Flexible->new_verifier(setting => value,...); - my $authreq = $verifier->new_request($cgi_query_object); + my $authreq = $verifier->new_request($cgi); # simple applications $authreq->check_ok() or return; @@ -102,6 +102,11 @@ B: If you do not override the source provision facility (see L), check that the assumptions it makes aren't going to leak security-critical data. +=item * + +Set up HTTPS on your webserver, or set the C setting +to a false value. + =back These points will now be covered in more detail. @@ -115,7 +120,7 @@ This call can be expensive and is best amortised. The resulting verifier object can be used to process individual requests, in each case with -C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>. +C<< $authreq = CGI::Auth::Flexible->new_request($cgi) >>. See L. @@ -326,9 +331,9 @@ Initialises an instance and returns a verifier object. The arguments are setting pairs like a hash initialiser. See L below. -=item C<< $verifier->new_request($cgi_query) >> +=item C<< $verifier->new_request($cgi) >> -Prepares to process a request. I<$cgi_query> should normally +Prepares to process a request. I<$cgi> should normally be the query object from L. Most of the default hook methods assume that it is; however if you replace enough of the hook methods then you can pass any value you like and it @@ -520,6 +525,19 @@ The settings supplied to C are stored in the verifier and will apply to all authreqs made from it unless overridden in the call to C +When a setting is described as a hook function, it should be a +coderef. The first argument will be the query object from +L (strictly, it will be whatever value was passed to +C). The second argument will be the authreq object (the +return value from C). +Ie, C<< sub some_hook ($$...) { my ($cgi,$authreq,@stuff) = @_ ... >> + +In bullet point headings, the hook functions are shown in the form +C<< some_hook($cgi,$authreq,@stuff) >> even though this would not be +legal syntax. This should be read to mean that the +%implicit_settings_hash{'some_hook'}($cgi,$authreq,@stuff) +would be a legal call. (However, the settings hash is not exposed.) + =over =head2 GENERAL SETTINGS @@ -619,11 +637,6 @@ this often (in seconds). Default: 86400. Name of the hidden form parameter. Default: C. -=item C - -Some of CAF's HTML-generating functions need to invent form parameter -names. They will all start with this string. Default: C. - =item C Name of the cookie used for login sessions. Default: @@ -636,16 +649,6 @@ Name of the password field in the login form. Default: C. Used by C (the default C hook), C and the default C hook. -=item C - -Form parameter name used to indicate that this is a source download -request. If this parameter is supplied, C and -C will arrange for the applicaton source code to be -delivered as the response (in C's case by doing it itself -and in C's case by asking your application to do so. - -Default is C. - =item C Arrayref of name(s) of username form parameters. @@ -672,12 +675,221 @@ C<< > The default is C<['caf_logout']> +=item C + +Arrayref of name(s) of form parameters indicating that user has just +logged out. (During the logout process, the actual logout action is a +POST request, whose response redirects to the "you have been logged +out" page; these form parameters are for this second page.) + +Used by the default C hook. + +The first entry is used by C to generate the redirection. + +The default is C<['caf_loggedout']> + +=item C + +Boolean. If true, is a declaration by the application that it is +mutatin-aware. See L. + +The default is 0. + +=item C + +Boolean. If true, CAF will insist that all transactions be done over +an encrypted http connection. It will redirect unencrypted requests +to the https instance of the applicattion, and will set the encrypted +only flag on its cookie. + +The default is 1. + +=back + +=item C<< get_url($cgi,$authreq) >> + +Hook which returns the URL of this web application. By default, we +call C<< $cgi->url() >> for each request, but you can fix this if you +prefer. + +=item C<< is_login,is_logout,is_loggedout($cgi,$authreq) >> + +Hook which returns a boolean indicating whether the request was, +respectively: a login form submission (ie, username and password); a +logout request (submission resulting from the user pressing the +"logout" button); "logged out" page (redirection from the logout +POST). + +The default is to check whether any of the corresponding request +parameters (C<< login_param_names >> etc.) was supplied, using the +C hook. + +=back + +=head2 SETTINGS (HOOKS) RELATED TO THE CGI REQUEST OBJECT + +=over + +=item C<< get_param($cgi,$authreq,$param) >> + +Returns the value of a single-valued form parameter. +The default is to call C<< $cgi->param($param) >>. +The semantics are the same as that of C. + +=item C<< get_params($cgi,$authreq) >> + +Returns a hash of the parameters. The return value is a hashref whose +keys are the parameter names and whose values are arrayrefs, one entry +in the arrayref for each value. + +The default is to call C<< $cgi->Vars() >>, expect the +results to look like those from C, and massage them into +the required form with split. + +=item C<< get_path_info($cgi,$authreq) >> + +Returns the PATH_INFO of the request. The default is to +call C<< $cgi->path_info() >>. + +=item C<< get_cookie($cgi,$authreq) >> + +Returns the value of the CAF cookie sent with the request, or undef if +none was supplied. The default is to call C<< +$cgi->cookie($cookie_name) >> (where C<$cookie_name> is from the +setting of the same name). The return value should be the scalar +value of the cookie. + +=item C<< get_method($cgi,$authreq) >> + +Returns the HTTP method as a string. The default is to call +C<< $cgi->request_method() >>. + =back +=item C<< is_https($cgi,$authreq) >> + +Returns a boolean indicating whether the request was over an encrypted +channel. The default is C<< !!$cgi->https() >>. See C. + +=back + +=head2 SETTINGS RELATED TO HTML GENERATION + +These are only used if you call C or xxx some other functions?. + +Settings whose names are of the form C are hooks which each +return an array of strings, normally HTML strings, for use by +C (or, in turn, other hooks, or your application). These +are often documented simply by showing the output produced. In many +cases parts of the output are in turn obtained from other hooks. In +some cases the default implementations have been given names for +convenient use by your application. They will be called in array +context. + +We'll write C even though actually there is a hook +to control the translation function used. + +=over + +=item C($cgi,$authreq,$divert)) + +C calls this hook before producing output of its own. If +you want to handle some but not all diversions yourself, you may set +this hook. The hook should either do nothing and return false, or +return true if it has handled the request (or arrange for the request +to be handled). If the hook returns true then C simply +returns 0. + +=item C($cgi,$authreq,$divert)) + +Default: a table (used mostly for layout) containing input fields for +a login form. Must be within a C<<
>> element, but doesn't +generate it. Has text fields for every entry in +C (in each case associated with a description +C<< gettext(ucfirst $parameter_name) >>, a password field (with +description C, and a login submit button (with +description C. + +Default is available as the class function C. + +=item C($cgi,$authreq)) + +Default: + + gettext(Log in again to continue.) + +Default is available as the class function C. + +=item C($cgi,$authreq,$params)) + +Default: form contents (but not the C<< >> element): + +C<$params> (in the form returned by the C hook) as hidden +fields, and also: + + + +Default is available as the class function C. + +=item C($cgi,$authreq,$title) + +Default: C<$cgi->start_html($title)> + +=item C($cgi,$authreq,$title) + +Default: C<$cgi->end_html($title)> + +=item C($cgi,$authreq)> + +Default: + +
+ Powered by Free / Libre / Open Source Software + according to the [gen_licence_link_html]. + [gen_source_link_html]. +
+ +Default is available as the class function C. + +=item C($cgi,$authreq)> + +Default: uses C to generate a URL for +downloading the licence, and returns: + GNU Affero GPL + +Default is available as the class function C. + +=item C($cgi,$authreq)> + +Default: uses C to generate a URL for +downloading the source, and returns: + Source available + +Default is available as the class function C. + +=item C + +Size of generated text entry fields. Default is 60. + +=item C + +Some of CAF's HTML-generating functions need to invent form parameter +names. They will all start with this string. Default: C. + =head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY =over +=item C + +Form parameter name used to indicate that this is a source download +request. If this parameter is supplied, C and +C will arrange for the applicaton source code to be +delivered as the response (in C's case by doing it itself +and in C's case by asking your application to do so. + +Default is C. + =item C Path to the directory used for storing pre-prepared source downloads. @@ -691,10 +903,6 @@ If this is a relative path, it is in C. =over -=item C - -xxx - =back -- 2.30.2