doc/htextauth.doc

   1 htextauth(1)
   2 ============
   3
   4 NAME
   5 ----
   6 htextauth - HTTP Basic authenticator for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *htextauth* [*-hCs*] [*-r* 'REALM'] 'AUTHCMD' ['ARGS'...] `--` 'CHILD' ['ARGS'...]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *htextauth* handler starts a single child handler which it passes
  16 all requests it receives, assuming they pass an authentication
  17 test. *htextauth* will request HTTP Basic credentials from the client,
  18 and pass such credentials to an external program in order to verify
  19 them. The authentication program will be called every time a new user
  20 needs to be authenticated. See the AUTHENTICATION section, below, for
  21 the calling convention used for the authentication program.
  22
  23 *htextauth* is a persistent handler, as defined in *ashd*(7), and the
  24 specified child handler must also be a persistent handler.
  25
  26 By default, *htextauth* will cache successfully verified credentials,
  27 so that the authentication program does not have to be called for each
  28 and every request. Cached credentials are cleared from the cache when
  29 they have not been used for over 30 minutes.
  30
  31 If the child handler exits, *htextauth* exits as well.
  32
  33 OPTIONS
  34 -------
  35
  36 *-h*::
  37
  38         Print a brief help message to standard output and exit.
  39
  40 *-C*::
  41
  42         Do not cache credentials.
  43
  44 *-s*::
  45
  46         Require that all requests are made over HTTPS.
  47
  48 *-r* 'REALM'::
  49
  50         Specify 'REALM' as the authentication realm when requesting
  51         credentials from the client.
  52
  53 AUTHENTICATION
  54 --------------
  55
  56 When a previously unseen user needs to be authenticated, *htextauth*
  57 will fork and execute the 'AUTHCMD' program, with any arguments that
  58 follow. *htextauth* will pass two lines of text to the authentication
  59 program's standard input: the given user name on the first line, and
  60 the password on the second. The credentials are checked in advance so
  61 that they do not contain any control characters (below ASCII 32).
  62
  63 If the authentication program successfully verifies the credentials
  64 and wishes to grant access to the client, it needs to exit
  65 successfully; that is, with exit status 0. Any other exit (including
  66 being killed by a signal) is taken by *htextauth* as a failure.
  67
  68 The authentication program can specify a reason for any failure by
  69 writing such on standard output. If the program exits unsuccessfully,
  70 *htextauth* will include any such message in the error page sent to
  71 the client.
  72
  73 Note that *htextauth* will wait for the authentication program to exit
  74 and not process any other requests until then.
  75
  76 AUTHOR
  77 ------
  78 Fredrik Tolf <fredrik@dolda2000.com>
  79
  80 SEE ALSO
  81 --------
  82 *ashd*(7), RFC 2617