| 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 | When authentication succeeds, *htextauth* removes the HTTP |
| 32 | `Authorization` header from the request before passing the request on |
| 33 | to the child handler, and adds the `X-Ash-Remote-User` header in its |
| 34 | place, containing the name of the authenticated user. |
| 35 | |
| 36 | If the child handler exits, *htextauth* exits as well. |
| 37 | |
| 38 | OPTIONS |
| 39 | ------- |
| 40 | |
| 41 | *-h*:: |
| 42 | |
| 43 | Print a brief help message to standard output and exit. |
| 44 | |
| 45 | *-C*:: |
| 46 | |
| 47 | Do not cache credentials. |
| 48 | |
| 49 | *-s*:: |
| 50 | |
| 51 | Require that all requests are made over HTTPS. |
| 52 | |
| 53 | *-r* 'REALM':: |
| 54 | |
| 55 | Specify 'REALM' as the authentication realm when requesting |
| 56 | credentials from the client. |
| 57 | |
| 58 | AUTHENTICATION |
| 59 | -------------- |
| 60 | |
| 61 | When a previously unseen user needs to be authenticated, *htextauth* |
| 62 | will fork and execute the 'AUTHCMD' program, with any arguments that |
| 63 | follow. *htextauth* will pass two lines of text to the authentication |
| 64 | program's standard input: the given user name on the first line, and |
| 65 | the password on the second. The credentials are checked in advance so |
| 66 | that they do not contain any control characters (below ASCII 32). |
| 67 | |
| 68 | If the authentication program successfully verifies the credentials |
| 69 | and wishes to grant access to the client, it needs to exit |
| 70 | successfully; that is, with exit status 0. Any other exit (including |
| 71 | being killed by a signal) is taken by *htextauth* as a failure. |
| 72 | |
| 73 | The authentication program can specify a reason for any failure by |
| 74 | writing such on standard output. If the program exits unsuccessfully, |
| 75 | *htextauth* will include any such message in the error page sent to |
| 76 | the client. |
| 77 | |
| 78 | Note that *htextauth* will wait for the authentication program to exit |
| 79 | and not process any other requests until then. |
| 80 | |
| 81 | FILES |
| 82 | ----- |
| 83 | The file `etc/extauth/vhtpasswd` in the *ashd* source distribution is |
| 84 | a simple authenticator program (written in Python) that can be used |
| 85 | with *htextauth*, which verifies the given credentials against a |
| 86 | simple database of users with encrypted passwords. It can be used as |
| 87 | is, or as a simple example of how to produce authenticator |
| 88 | programs. The accompanying `mkhtpasswd` program can be used to |
| 89 | maintain the password database. |
| 90 | |
| 91 | AUTHOR |
| 92 | ------ |
| 93 | Fredrik Tolf <fredrik@dolda2000.com> |
| 94 | |
| 95 | SEE ALSO |
| 96 | -------- |
| 97 | *ashd*(7), RFC 2617 |