authentication_handler implementaion

Authentication handler allows to delegate http authentication to external
program. It introduces one new configuration variable: authentication_handler.
Note that this commit does not affect uzbl behaviour unless this variable is
set.  Also updated README documentation, default config and added example
authentication script.

1 files changed, 32 insertions, 0 deletions

diff --git a/README b/README
index 217e6bf..99daef1 100644
--- a/README
+++ b/README
@@ -204,6 +204,7 @@ Besides the builtin variables you can also define your own ones and use them in
   - `cookie_handler`
   - `new_window`: handler to execute to invoke new uzbl window (TODO better name)
   - `scheme_handler`: handler to execute for each URI navigated to - the navigation request will be ignored if handler prints "USED\n"
+  - `authentication_handler`: command that handles http authentication
   - `fifo_dir`: location to store fifo's
   - `socket_dir`: location to store sockets
   - `print_events`: show events on stdout
@@ -395,6 +396,12 @@ The script specific arguments are this:
 
     $8 URI of the page to be navigated to
 
+* authentication handler:
+
+    $8 authentication zone unique identifier
+    $9 domain part of URL that requests authentication
+    $10 authentication realm
+    $11 FALSE if this is the first attempt to authenticate, TRUE otherwise
 
 Custom, userdefined scripts (`spawn foo bar`) get first the arguments as specified in the config and then the above 7 are added at the end.
 
@@ -411,6 +418,31 @@ Currently, the `Uzbl` object provides only one function:
        * `Uzbl.run("spawn insert_bookmark.sh")`
        * `uri = Uzbl.run("print @uri")` (see variable expansion below)
 
+### AUTHENTICATION ###
+
+If authentication_handler variable is not set, http authentication is handled internally by WebKit. If you want to use custom script for http authentication, set authentication_handler. For example:
+
+  set authentication_handler = sync_spawn /patch/to/your/script
+
+Script will be executed on each authentication request. It will receive four auth-related parameters:
+    
+    $8 authentication zone unique identifier (may be used as hash key in passwords database)
+    $9 domain part of URL that requests authentication
+    $10 authentication realm
+    $11 FALSE if this is the first attempt to authenticate, TRUE otherwise
+
+Script is expected to print exactly two lines of text on stdout (that means its output must contain exactly two '\n' bytes). The first line contains username, the second one - password.
+If authentication fail, script will be executed again (with $11 = TRUE). Non-interactive scripts should handle this case and do not try to authenticate again to avoid loops.
+If number of '\n' characters in scripts output does not equal 2, authentication will fail. That means 401 error will be displayed and uzbl won't try to authenticate anymore.
+
+The simplest example of authentication handler script is:
+
+#!/bin/sh
+[ "$11" == "TRUE ] && exit
+echo alice
+echo wonderland
+
+This script tries to authenticate as user alice with password wonderland once and never retries authentication. See examples for more sofisticated, interactive authentication handler.
 
 ### EVENTS ###