---
name: "thy-auth"
section: "7"
platform: "linux"
package: "thy"
version: "0.9.4-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/thy-auth"
---

# thy-auth(7)

the Thy Authoriser protocol

## 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)](/thy/8.md)