X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=cgi-auth-flexible.git;a=blobdiff_plain;f=caf.pod;h=ef649825f16e71e4379d0bd6b79918e1d9ee1259;hp=7921b357b33e80f63ff642a5f8fb316d4d2b9cab;hb=7ca0f9784810412473315d817af72e605bcd9d28;hpb=cb2c8c602c3eac270bf973c7908929bb3073b8f7 diff --git a/caf.pod b/caf.pod index 7921b35..ef64982 100644 --- a/caf.pod +++ b/caf.pod @@ -111,7 +111,14 @@ The resulting verifier object can be used to process individual requests, in each case with C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>. -=head2 RESPONSE GENERATION - SIMPLE APPLICATIONS +=head2 CHECKING AND RESPONSE GENERATION + +If the user is logged in, your application is to handle the request. +Otherwise, the user needs to be presented with a login form or error +message, as appropriate. CGI::Auth::Flexible provides two alternative +interfaces for this: + +=head3 Simple applications The simplist usage is to call C<< $request->check_ok() >> which will check the user's authentication. If the user is not logged in it will @@ -126,15 +133,18 @@ After C returns true you should go ahead and process the request; you can use C<< $request->get_username >> to find out which user the request came from. -=head2 RESPONSE GENERATION - SOPHISTICATED APPLICATIONS +=head2 Sophisticated applications If you want to handle the control flow and to generate login forms, redirections, etc., yourself, you can say C<< $divert = $request->check_divert >>. This returns undef if the user is logged in, or I if some kind of login -page or diversion should be generated. +page or diversion should be generated. See L below for +details of how to deal with the return value. -=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-IGNORANT APPLICATIONS +=head2 MUTATING OPERATIONS AND EXTERNAL LINKS + +=head3 Mutation-ignorant applications By default CGI::Auth::Flexible does not permit external links into your site. All GET requests give a "click to continue" page which @@ -146,7 +156,7 @@ in the web's security architecture. Such applications are also not able to provide user-specific CSS stylesheets, javascript, favicons, etc. -=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-AWARE APPLICATIONS +=head3 Mutation-aware applications The alternative is for your application to always make a special check when the incoming request is going to do some kind of action (such as @@ -222,6 +232,12 @@ will die, stopping the attack. (You do not need to call C 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. + =head2 DATA STORAGE CGI::Auth::Flexible needs to store various information in plain files; @@ -268,7 +284,7 @@ C. See C. For each source item in a dvcs, the entire dvcs history does not contain anything confidential (or libellous). Also, all files which -contain secrets are in the dvcs's C<.ignore> file. See +contain secrets are in the dvcs's I<.ignore> file. See C et al. =item * @@ -304,13 +320,13 @@ See L below. =item C<< $verifier->new_request($cgi_query) >> -Prepares to process a request. C<$cgi_query> should normally +Prepares to process a request. I<$cgi_query> 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 will be passed to your hooks. -The return value is the authentication request object (C<$authreq>) +The return value is the authentication request object (I<$authreq>) which is used to check the incoming request and will contain information about its credentials. @@ -337,3 +353,160 @@ the application should not process the request further. Discards the resources (open files, etc.) in the verifier object. =back + +=head REQUEST-RELATED FUNCTIONS AND METHODS + +All of these are only valid after C or C has +been called. (In the case of C it won't normally be sensible +to call these functions unless C returned true.) + +=item C<< $authreq->get_divert() >> + +Returns the value previously returned by C. + +=item C<< $authreq->get_username() >> + +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 you must call +C whenever appropriate. If you haven't then it's +irrelevant. See L. + +C 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, +whenever it is handling anything except an HTML page loads, it must +call this function. See L, and +L. + +C will either return successfully, indicating that all +is well and the request should proceed, or it will die, like +C. + +=head RESPONSE-RELATED FUNCTIONS AND METHODS + +=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >> + +Convenience function which returns a url for a GET request to this +application. + +I<$params> is a hashref specifying the parameters and the PATH_INFO. +The keys are the parameter names, and the values are array refs with +the parameter value(s) (as strings, as yet unquoted). (They are array +refs because it is possible to pass multiple values for the same +parameter in a single request; normally each arrayref would be a +singleton.) + +The request path will be the path to the application. If a parameter +with name C<< '' >> is supplied, it is taken as the PATH_INFO - its +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. + +=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. + +The name of the hidden parameter is the setting C, +C by default. xxx rename param and setting + +=item C<< something->secret_hidden_html() >> + +Returns the HTML for an C 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. You may also set it +yourself (and indeed you must do so if you use C). + +=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 + +=over + +=item C<< $verifier_or_authreq->hash($data) >> + +Hashes the supplied data using the hash function specified by the +C 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 and C. 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. + +=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>> + +Hashes the supplied data using the hash function specified by the +C setting, and converts the result to a string of hex +digits. + +=back + + + +xxx divert spec +xxx reqtype +xxx settings +xxx html generators +xxx document cookie