=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 *
requests, in each case with
C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
+See L</SETTINGS>.
+
=head2 CHECKING AND RESPONSE GENERATION
If the user is logged in, your application is to handle the request.
redirections, etc., yourself, you can say
C<< $divert = $request->check_divert >>. This returns undef if
the user is logged in, or I<divert spec> if some kind of login
-page or diversion should be generated.
-
-xxx see below
+page or diversion should be generated. See L</DIVERT SPEC> below for
+details of how to deal with the return value.
=head2 MUTATING OPERATIONS AND EXTERNAL LINKS
(You do not need to call C<check_nonpage> for POST requests, but it is
harmless to do so.)
+=head3 Mutation-aware applications - novel kinds of request
+
+If you want to support a kind of request perhaps not yet known about
+by CGI::Auth::Flexible, you can provide information about that new
+request kind using C<update_get_need_add_hidden>.
+
=head2 DATA STORAGE
CGI::Auth::Flexible needs to store various information in plain files;
=back
-=head REQUEST-HANDLING FUNCTIONS AND METHODS
+=head 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
Returns the name of the logged-in user. If the user was not logged
in (or their session had timed out, or something), returns undef.
+=item C<< $authreq->check_mutate() >>
+
+Declares to CGI::Auth::Generic that the request being handled will
+"mutate". That is, it will modify some server-side state (eg, adding
+items to shopping baskets, posting messages to blogs, sending emails,
+or whatever).
+
+If you have set the setting C<promise_check_mutate> you must call
+C<check_mutate> whenever appropriate. If you haven't then it's
+irrelevant. See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
+
+C<check_mutate> will either return successfully, indicating that all
+is well and the request should proceed, or it will die. If it dies
+that means that the request was improper, which can only result from a
+bug or an attack. So an "internal server error" is a suitable
+response.
+
+=item C<< $authreq->check_nonpage($method, $reqtype) >>
+
+Declares to CGI::Auth::Generic that the request is not a page request,
+but rather a request of type I<$reqtype>.
+
+If your application has set the setting C<promise_check_mutate>,
+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
+is well and the request should proceed, or it will die, like
+C<check_mutate>.
+
=head RESPONSE-RELATED FUNCTIONS AND METHODS
=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
value will be appended to the application path. (It should normally
start with C<< / >>, and only one value should be supplied.)
+=item C<< something->need_add_hidden($method, $reqtype) >>
+
+Enquires whether a request of type I<$reqtype> using HTTP method
+I<$method> needs the hidden form parameter. See L</REQUEST TYPES>.
+
+=item C<< something->secret_hidden_val() >>
+
+Returns the value of the hidden form parameter. This should be
+included in all POST requests to your application (and thus be a
+hidden form parameter in all forms).
+
+It should also be in some (maybe all) GET requests. If your
+application is mutation-ignorant, it should be in all GET requests.
+If you are mutation-aware, you need to consult C<need_add_hidden>.
+
+The name of the hidden parameter is the setting C<assoc_param_name>,
+C<caf_hassochash> by default. xxx rename param and setting
+
+=item C<< something->secret_hidden_html() >>
+
+Returns the HTML for an C<INPUT> element specifying the hidden form
+parameter.
+
+=item C<< something->secret_cookie_val() >>
+
+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
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
+
+=over
+
+=item C<< $verifier_or_authreq->hash($data) >>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
+=item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
+
+Updates CGI::Auth::Generic's knowledge about the various kinds of
+request, and whether they need the hidden form parameter. This
+function applies only to GET requests - POST requests always use the
+parameter.
+
+I<$reqtype> is the request type (the value which will be passed to
+C<check_nonpage> and C<need_add_hidden>. If you are supporting a new
+I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
+or other users, to assign a unique request type name.
+
+This method may be called on an authreq or a verifier, in which case
+it will affect all authreqs using the same verifier. Or it may be
+called on the class as a whole, in which case it will affect the
+global default list for all verifiers.
+
+If I<$force> is supplied and true, this will override
+CGI::Auth::Flexible's existing knowledge. Otherwise this new setting
+will be ignored if CGI::Auth::Flexible already knows about the request
+type. (When called on a verifier or authreq, it will ignore the
+update in favour of existing knowledge recorded both globally in the
+class or due to previous requests on the same verifier.)
+
+See L</REQUEST TYPES>.
+
+=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
=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>
+
+=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<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__>.
+
+=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<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<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']>
+
+=back
+
+=head2 SETTINGS FOR SOURCE CODE DOWNLOAD FACILITY
+
+=over
+
+=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
+
+=head2 SETTINGS FOR HTML GENERATION
+
+=over
+
+=item C<form_entry_size>
+
+xxx
+
+=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 reqtype
+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