Provided by: thy_0.9.4-1_i386 bug

NAME

       thy-auth - the Thy Authoriser protocol

SYNOPSIS

       COMMAND
       argument_counter
       argument
       ...

DESCRIPTION

       This manual page documents version 2 of the Thy Authorisation Protocol.
       It is expected that the protocol will not change in the future, and the
       current specification is safe to use.

       The  protocol  is  really  simple: Thy sends a command, then a newline,
       then the number of arguments, another newline, then all the  arguments,
       separated by newlines. Responses look similar.

       The   standard   is   that  1  responses  indicate  positiveness  (user
       authorised, authentication needed, protocol  version  supported,  etc),
       while  0  indicates  a  negative  response.  A zero response may not be
       followed by other responses to the same command.

       Unknown commands must be answered by a single zero response.

COMMANDS

       All commands take at least  one  argument:  the  number  of  arguments.
       Whether  this is passed down to the handler function, is implementation
       dependant.

       VERSION
              This command takes exactly one argument - the version number  of
              the  Authoriser  protocol  the  other end wants to speak. If the
              Authoriser supports the protocol, it  must  respond  with  1,  0
              otherwise.

       QUIT   This  command  does  not  take any arguments. When received, the
              Authoriser must shut itself down.

       AUTH   This command takes five arguments: the username,  the  password,
              the  realm, a filename and an authfile. The filename is the full
              path to the requested (and protected) file,  while  authfile  is
              the  full  path to the file Thy should authorise against (.realm
              or .htaccess for example).

              The handler can use any of these  to  authorise  the  user,  and
              respond with a 1 if he may pass, with a 0 otherwise.

       CHECK  This  command  takes  only  one  argument:  the  filename of the
              so-called realm file. Then,  it  verifies  if  authorisation  is
              needed,  and when not, responds with 0. If yes, responds with 1,
              followed by the length of the realm, then the realm itself.

              Please note that when authorisation  is  not  needed,  only  one
              response should be sent, not three.

EXAMPLE

       In  the  example sessions below, T indicates lines sent by Thy, A flags
       responses.

   Version mismatch
              T: VERSION
              T: 1
              T: 2

              A: 0

   A full session, with successful authorisation
              T: VERSION
              T: 1
              T: 1

              A: 1

              T: CHECK
              T: 1
              T: /var/www/admin/.realm

              A: 1
              A: 3
              A: foo

              T: AUTH
              T: 4
              T: test
              T: easy_password
              T: foo
              T: /var/www/admin/index.html

              A: 1

              T: QUIT

CHANGES

   Changes since Version 1
       The only change from protocol version one  is  that  the  AUTH  command
       takes a fifth argument: authfile.

BUGS

       Probably many.

AUTHOR

       Gergely Nagy <algernon@bonehunter.rulez.org>

SEE ALSO

       thy(8)