=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;
=item *
If you're using C<check_ok>, implement either the
-C<username_password_error> or C<login_ok> hook.
+C<username_password_error> or C<login_ok> hook and provide it as
+a setting to C<new_verifier>.
+
+=item *
+
+Provide the setting C<dir> (or provide absolute paths for all the
+other relevant settings).
=item *
L</SOURCE CODE DOWNLOAD>), 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<encrypted_only> setting
+to a false value.
+
=back
These points will now be covered in more detail.
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</SETTINGS>.
=head2 CHECKING AND RESPONSE GENERATION
The arguments are setting pairs like a hash initialiser.
See L</SETTINGS> 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<CGI(3perl)>. 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
=back
+=head1 SETTINGS
+
+C<new_verifier> and C<new_request> each take a list of settings, as
+a list of pairs C<< key => value >> (like a Perl hash assignment).
+
+The settings supplied to C<new_verifier> are stored in the verifier
+and will apply to all authreqs made from it unless overridden in the
+call to C<new_request>
+
+When a setting is described as a hook function, it should be a
+coderef. The first argument will be the query object from
+L<CGI(3perl)> (strictly, it will be whatever value was passed to
+C<new_request>). The second argument will be the authreq object (the
+return value from C<new_request>).
+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
+
+=item C<dir>
+
+The directory CGI::Auth::Generic should use for its data storage.
+This is actually just a default absolute path used when the other
+path settings are relative values.
+
+Must be an absolute filename.
+
+=item C<assocdb_dbh>
+
+CGI::Auth::Flexible needs a database for recording users' login
+session. This database needs to be shared across all instances of the
+web application, so in a multi-node cluster it needs to be your actual
+database.
+
+CGI::Auth::Flexible will create the table and index it needs if they
+don't already exist, and will manage their contents. You do not need
+to integrate them into the rest of your webapp's data storage. (In
+particular, there is no need for transactional integrity across
+changes made by CAF and your own application.)
+
+By default, CAF uses a sqlite3 database stored on local disk in the
+file named by C<assocdb_path>. This will be suitable for all
+applications which run on a single host.
+
+This value, if supplied, should be a DBI handle for the database.
+
+=item C<assocdb_dsn>
+
+This is the DSN to pass to C<< DBI->connect >>. Used only if
+C<assocdb_dbh> is not supplied.
+
+=item C<assocdb_path>
+
+Path to the sqlite3 database used for CAF's session storage. The
+default is currently C<caf-assocs.db> but will change in the future.
+
+Used only if neither C<assocdb_dbh> or C<assocdb_dsn> are supplied.
+
+If this is a relative path, it is in C<dir>.
+
+=item C<assocdb_table>
+
+Prefix for the SQL tables and indices to use (and to create, if
+necessary).
+
+See L</DATABASE TABLES>.
+
+=item C<keys_path>
+
+Path to the keys file used by CAF. This arrangement will change in
+the future. See L</BUGS>.
+
+=item C<random_source>
+
+Special file to read random numbers from. Should return
+cryptographically secure (pseudo)-random bytes, unpredictable to
+adversaries (even ones on the same machine).
+
+On Linux, there is no device which is properly suitable. This is a
+bug in Linux. You can use C</dev/random> which can block
+unnecessarily even though the kernel PRNG has been properly seeded and
+is fine, or C</dev/urandom> which might return values which attackers
+can predict if the kernel PRNG has not been properly seeded.
+
+The default is C</dev/urandom>.
+
+=item C<secretbits>
+
+Length of the assoc secret. Defaults to 128.
+
+=item C<hash_algorithm>
+
+Must be a string suitable for use with C<new Digest>.
+Defaults to C<SHA-256>.
+
+=item C<login_timeout>
+
+A user will be logged out this many seconds after they first logged
+in. Default: 86400 (one day).
+
+=item C<login_form_timeout>
+
+A login form becomes invalid this many seconds after it has been sent.
+Default: 3600 seconds (one hour).
+
+=item C<key_rollover>
+
+The key used for generating assoc secrets is rolled over approximately
+this often (in seconds). Default: 86400.
+
+=item C<assoc_param_name>
+
+Name of the hidden form parameter. Default: C<caf_assochash>.
+
+=item C<cookie_name>
+
+Name of the cookie used for login sessions. Default:
+C<caf_assocsecret>.
+
+=item C<password_param_name>
+
+Name of the password field in the login form. Default: C<password>.
+
+Used by C<login_ok_password> (the default C<login_ok> hook),
+C<gen_plain_login_form> and the default C<is_login> hook.
+
+=item C<username_param_names>
+
+Arrayref of name(s) of username form parameters.
+
+The first entry is used by C<login_ok_password> (the default
+C<login_ok> hook) to pass to the C<username_password_error> hook and
+used as the username if all is well.
+
+All the entries are used by C<gen_plain_login_fork> (the default
+C<gen_login_form> hook for C<check_ok>) to generate form entry fields.
+
+The default is C<['username']>.
+
+=item C<logout_param_names>
+
+Arrayref of name(s) of form parameters indicating that the request is
+a logout request.
+
+Used by the default C<is_logout> hook.
+
+If you want users to be able to explicitly log out, you need to
+provide a logout button, something like
+C<< <input type="submit" name="caf_logout" ...>>
+
+The default is C<['caf_logout']>
+
+=item C<logged_param_names>
+
+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<is_loggedout> hook.
+
+The first entry is used by C<check_ok> to generate the redirection.
+
+The default is C<['caf_loggedout']>
+
+=item C<promise_check_mutate>
+
+Boolean. If true, is a declaration by the application that it is
+mutatin-aware. See L</MUTATING OPERATIONS AND EXTERNAL LINKS>.
+
+The default is 0.
+
+=item C<encrypted_only>
+
+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<get_param> 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<CGI::param>.
+
+=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<CGI::Vars>, 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<encrypted_only>.
+
+=back
+
+=head2 SETTINGS RELATED TO HTML GENERATION
+
+These are only used if you call C<check_ok> or xxx some other functions?.
+
+Settings whose names are of the form C<gen_...> are hooks which each
+return an array of strings, normally HTML strings, for use by
+C<check_ok> (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<gettext(something)> even though actually there is a hook
+to control the translation function used.
+
+=over
+
+=item C<handle_divert>($cgi,$authreq,$divert))
+
+C<check_ok> 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<check_ok> simply
+returns 0.
+
+=item C<gen_login_form>($cgi,$authreq,$divert))
+
+Default: a table (used mostly for layout) containing input fields for
+a login form. Must be within a C<< <form> >> element, but doesn't
+generate it. Has text fields for every entry in
+C<username_param_names> (in each case associated with a description
+C<< gettext(ucfirst $parameter_name) >>, a password field (with
+description C<gettext("Password")>, and a login submit button (with
+description C<gettext("Login")>.
+
+Default is available as the class function C<gen_plain_login_form>.
+
+=item C<gen_login_link>($cgi,$authreq))
+
+Default:
+
+ <a href="http:...">gettext(Log in again to continue.)</a>
+
+Default is available as the class function C<gen_plain_login_link>.
+
+=item C<gen_postmainpage_form>($cgi,$authreq,$params))
+
+Default: form contents (but not the C<< <form> >> element):
+
+C<$params> (in the form returned by the C<get_params> hook) as hidden
+fields, and also:
+
+ <input type="submit" ... value=getext('Continue')>
+
+Default is available as the class function C<gen_postmainpage_form>.
+
+=item C<gen_start_html>($cgi,$authreq,$title)
+
+Default: C<$cgi->start_html($title)>
+
+=item C<gen_end_html>($cgi,$authreq,$title)
+
+Default: C<$cgi->end_html($title)>
+
+=item C<gen_footer_html>($cgi,$authreq)>
+
+Default:
+
+ <hr><address>
+ Powered by Free / Libre / Open Source Software
+ according to the [gen_licence_link_html].
+ [gen_source_link_html].
+ </address>
+
+Default is available as the class function C<gen_plain_footer_html>.
+
+=item C<gen_licence_link_html>($cgi,$authreq)>
+
+Default: uses C<url_with_query_params> to generate a URL for
+downloading the licence, and returns:
+ <a href="...">GNU Affero GPL</a>
+
+Default is available as the class function C<gen_plain_licence_link_html>.
+
+=item C<gen_source_link_html>($cgi,$authreq)>
+
+Default: uses C<url_with_query_params> to generate a URL for
+downloading the source, and returns:
+ <a href="...">Source available</a>
+
+Default is available as the class function C<gen_plain_source_link_html>.
+
+=item C<form_entry_size>
+
+Size of generated text entry fields. Default is 60.
+
+=item C<dummy_param_name_prefix>
+
+Some of CAF's HTML-generating functions need to invent form parameter
+names. They will all start with this string. Default: C<caf__>.
+
+=head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
+
+=over
+
+=item C<srcdump_param_name>
+
+Form parameter name used to indicate that this is a source download
+request. If this parameter is supplied, C<check_ok> and
+C<check_divert> will arrange for the applicaton source code to be
+delivered as the response (in C<check_ok>'s case by doing it itself
+and in C<check_divert>'s case by asking your application to do so.
+
+Default is C<caf_srcdump>.
+
+=item C<srcdump_path>
+
+Path to the directory used for storing pre-prepared source downloads.
+Defaults to C<caf-srcdump>.
+
+If this is a relative path, it is in C<dir>.
+
+=back
+
+
+=head1 DATABASE TABLES
+
+In a simple application, you do not need to worry about this. But if
+your application runs on multiple frontend hosts with a shared
+database, you may need to create for yourself the tables and indices
+used by CGI::Auth::Flexible.
+
+xxx document _db_setup_do
+xxx make _db_setup_do explicitly overrideable
xxx divert spec
xxx settings
xxx html generators
xxx document cookie
+
+xxx bugs wrong default random on Linux
+xxx bugs wrong default random on *BSD
+xxx bugs keys not shared should be in db
+xxx rename caf-assocs.db
+xxx rename caf_assocsecret default cookie name
+xxx mention relationship between login_timeout and cookies
~ian / cgi-auth-flexible.git / blobdiff