thy-auth - the Thy Authoriser protocol

COMMAND

argument_counter

argument

...

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.

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.

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

Version mismatch

T: VERSION
T: 1
T: 2

A full session, with successful authorisation

T: VERSION
T: 1
T: 1

Changes since Version 1

Probably many.

Gergely Nagy <algernon@bonehunter.rulez.org>

thy(8)