chiark / gitweb /
docs: more work
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 17 Mar 2013 13:59:59 +0000 (13:59 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 17 Mar 2013 13:59:59 +0000 (13:59 +0000)
caf.pod

diff --git a/caf.pod b/caf.pod
index 2603499..7921b35 100644 (file)
--- a/caf.pod
+++ b/caf.pod
@@ -1,3 +1,5 @@
+# -*- fundamental -*-
+
 =head1 NAME
 
 CGI::Auth::Flexible - web authentication optionally using cookies
@@ -41,6 +43,63 @@ call CGI::Auth::Flexible before answering AJAX requests as well as
 before generating HTML pages, of course, and to call it in every
 entrypoint to your system.
 
+=head2 CHECKLIST
+
+As a minimum you need to do all of the things on this checklist, where
+applicable.  The items marked SECURITY are the ones that you might
+forget: without them your application may appear to work, but will be
+insecure.
+
+=over
+
+=item *
+
+Call C<new_verifier> (once at application startup)
+
+=item *
+
+Call C<new_request> (once per request)
+
+=item *
+
+B<SECURITY>: Call C<check_ok> or C<check_divert> on every request, and
+honour the return value.
+
+=item *
+
+If you're using C<check_ok>, implement either the
+C<username_password_error> or C<login_ok> hook.
+
+=item *
+
+Call C<get_username> when you need to know who's logged in.
+
+=item *
+
+B<SECURITY>: Call C<check_mutate> or C<mutate_ok>, if you specified
+C<promise_check_mutate>.
+
+=item *
+
+B<SECURITY>: Call C<check_nonpage> for every request which is not a page load
+(if your application has any of those).
+
+=item *
+
+When generating URLs and forms (including AJAX requests), include the
+hidden form parameter using C<secret_hidden_val> or
+C<secret_hidden_html> when appropriate (see below).
+
+=item *
+
+B<SECURITY>: If you do not override the source provision facility (see
+L</SOURCE CODE DOWNLOAD>), check that the assumptions it makes aren't
+going to leak security-critical data.
+
+=back
+
+These points will now be covered in more detail.
+
 =head2 INITIALISATION
 
 Your application should, on startup (eg, when it is loaded by
@@ -52,7 +111,7 @@ 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 SIMPLE APPLICATIONS
+=head2 RESPONSE GENERATION - 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
@@ -60,81 +119,108 @@ generate a login form (or redirection or other appropriate page) and
 return false; your application should not then processing that request
 any further.  If the user is logged in it will return true.
 
-After calling C<check_ok> you can use C<< $request->get_username >>
-to find out which user the request came from.
+Various hooks are provided to customise the responses generated by
+C<check_ok>.
+
+After C<check_ok> 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 SOPHISTICATED APPLICATIONS
+=head2 RESPONSE GENERATION - SOPHISTICATED APPLICATIONS
 
-If you want to handle the flow control and to generate login forms,
+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<divert spec> if some kind of login
 page or diversion should be generated.
 
-=head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-IGNORANT APPLICATIONS
 
-When you generate a C<POST> form or AJAX request you need to include a
-special secret hidden form parameter for the benefit of
-CGI::Auth::Generic.  This form parameter will be checked by
-C<check_ok>/C<check_divert> and should be ignored by your application.
+By default CGI::Auth::Flexible does not permit external links into
+your site.  All GET requests give a "click to continue" page which
+submits a form which loads your app's main page.  In this
+configuration all your application's forms and AJAX requests should
+use C<POST>.  This restriction arises from complicated deficiencies
+in the web's security architecture.
 
-By default the hidden parameter is called C<caf_assochash>.  After
-calling C<check_ok> or C<check_divert> the value to put in your form
-can be obtained from C<secret_hidden_val>; C<secret_hidden_html> will
-generate the whole HTML C<< <input...> >> element.
+Such applications are also not able to provide user-specific CSS
+stylesheets, javascript, favicons, etc.
 
-Do not put the secret value in URLs for C<GET> requests.
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-AWARE APPLICATIONS
 
-=head2 NON-PAGE RESOURCES
+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
+modifying the user's setup, purchasing goods, or whatever) rather than
+just retrieve and/or display information.  We term such requests
+"mutating" requests.
+
+Then non-mutating pages can be linked to from other, untrustworthy,
+websites.
+
+To support external links, and C<GET> requests, pass
+C<< promise_check_mutate => 1 >> in I<settings>, and then call
+C<< $authreq->check_mutate() >> before taking any actions.  If the
+incoming request is not suitable then C<< $authreq->check_mutate() >>
+will call C<die>.
 
-Some, but not all, non-page resources (fetched with GET) need to have
-the secret hidden parameter in the query parameters in the form url.
+There have to be no mutating C<GET> requests in your application (but
+you shouldn't have any of those anyway); if there are, they won't
+work.  (CGI::Auth::Flexible will spot them and cause them to fail,
+rather than allow them to be insecure.)
 
-So if your application supports anything except HTML pages you need to
-take special measures.  (Wholly invariant resources which don't depend
-on which user is logged in are an exception.)
+=head2 GENERATING URLS, FORMS AND AJAX QUERIES
 
-When you generate a url to such a resource you must call
-resource_get_needs_secret_hidden to find out whether to include the
-hidden form parameter  xxx fixme
+When you generate a URL, C<POST> form or AJAX request you may need to
+include a secret hidden form parameter for the benefit of
+CGI::Auth::Generic.  This form parameter will be checked by
+C<check_ok>/C<check_divert> and should be ignored by your application.
 
-You can only when logged in
+By default the hidden parameter is called C<caf_assochash>.
 
- call
-C<nonpage_ok> when you are processing one of these.  You need to
-supply a parameter specifying exactly what kind of resource this is:
+After calling C<check_ok> or C<check_divert> the value to put in your
+form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
+will generate the whole HTML C<< <input...> >> element.
 
+=head3 Mutation-ignorant applications
 
+For mutation-ignorant applications (see above), all forms etc. should
+include the hidden parameter (and as discussed, they must all use
+POST rather than GET).
 
-before you
-generate any output 
+=head3 Mutation-aware applications
 
- (other than
+For mutation-aware applications, whether to include the secret
+parameter depends on the kind of request.  CGI::Auth::Flexible knows
+when it is necessary.  You should find out by calling
+C<need_add_hidden>.
 
+If it is inconvenient to call C<need_add_hidden> at runtime, you can
+rely instead on the following promises:  All POST requests (which
+includes all mutating requests) need the parameter.  The return value
+of need_add_hidden depends only on the $method and $reqtype
+parameters, so you can query it once and remember the answer.
+HTML page load GETs do not need the parameter.  It is better to
+err on the side of including the parameter.
 
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
+If you really must, you can call C<need_add_hidden> "on the bench"
+during development and bake the answer into your application code
+structure.  However, if you do that and a new vulnerability was
+discovered which is fixed by changing the answer, updating
+CGI::Auth::Flexible wouldn't be sufficient to fix it.
 
-By default CGI::Auth::Flexible does not permit external links into
-your site.  All GET requests give a "click to continue" page which
-submits a form which loads your app's main page.  In this
-configuration all your application's forms and AJAX requests should
-use C<POST>.  This restriction arises from complicated deficiencies
-in the web's security architecture.  
+=head3 Mutation-aware applications - non-page requests
 
-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
-modifying the user's setup, purchasing goods, or whatever) rather than
-just display HTML pages.  Then non-mutating pages can be linked to
-from other, untrustworthy, websites.
+If your mutation-aware application supports non-page resources (AJAX
+and JSON requests, stylesheets, favicons, etc.) it must inform
+CGI::Auth::Flexible when it is handling such a request, by calling
+C<check_nonpage>.
 
-To support external links, and C<GET> requests, pass
-C<< promise_check_mutate => 1 >> in I<settings>, and then call
-C<< $authreq->check_mutate() >> before taking any actions.  If the
-incoming request is not suitable then C<< $authreq->check_mutate() >>
-will call C<die>.
+Normally C<check_nonpage> will simply return (and you can ignore the
+return value).  However, if there is an attack (or, perhaps, a bug) it
+will die, stopping the attack.
 
-You must make sure that you have no mutating C<GET> requests in your
-application - but you shouldn't have any of those anyway.
+(You do not need to call C<check_nonpage> for POST requests, but it is
+harmless to do so.)
 
 =head2 DATA STORAGE
 
@@ -170,12 +256,12 @@ Specifically, there are no compiled or autogenerated Perl
 files, Javascript resources, etc., which are not contained in one of
 the source item directories.  (Files which came with your operating
 system install don't need to be shipped as they fall under the system
-library exceptio.)
+library exception.)
 
 =item *
 
 You have not installed any modified versions of system
-libraries (including system-supplied) Perl modules in C</usr> outside
+libraries (including system-supplied Perl modules) in C</usr> outside
 C</usr/local>.  See C<srcdump_system_dir>.
 
 =item *
@@ -201,7 +287,7 @@ You don't regard pathnames on your server as secret.
 
 =item *
 
-You don't intentionally load Perl code by virtule of C<.>
+You don't intentionally load Perl code by virtue of C<.>
 being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
 
 =back