mod-auth-udp

Protocol between apache-module and udpauthserver

1. Overview

While the browser and the http-server use TCP-connections for communication, the communication between the http-server and the udpauthserver works by sending UDP-packets. The http-server builds one packet(request), sends it to the udpauthserver and the udpauthserver in return sends one packet(reply) back.

2. Requests (http-server to udpauthserver)

The request that is send is assembled from a number of C-Strings which are putted one after the other, with '\0' Characters as separators! The first string is an index to the following parts and tells the udpauthserver how many parts there are and what they contain. As of version 1.0 the following is possible:

Indexchar

Content

U

Username

P

Password

G

Groupname

So a valid request could be:

  1. U\0joe-user\0

  2. UP\0jumpingjackflasch\0b-flat\0

  3. UGG\0frodo\0hobbit\0ent\0

( Note that the \0 is only one char, the ASCII NUL.)

The first request asks the udpauthserver to look up the encrypted password for the user »joe-user« and send it back to the http-server.

The second request asks the udpauthserver to check wether or not the password of the user »jumpingjackflash« matches »b-flat« and report this back to the http-server.

The third request asks the udpauthserver to check wether the user »frodo« belongs to at least one of the groups »hobbit« or »ent« and report this back to the http-server.

3. Replies (udpauthserver to http-server)

Replies are made up by one C-style string (no embedded \0's). The first char gives the overall result, the rest gives additional Information.

Possible replies are:

Startchar

Message

In reply to Request

Explanation

Http-status

O

k

2, 3

The username and password or groups match

200

D

errormesseage

1, 2, 3

The username was not found or the password or group does not match, and thus access must be denied

401

P

Password

The username was found and the encrypted password is send back to the http-server

200 or 401

E

Errormesseage

1, 2, 3

Something went wrong within the udpauthserver. Further processing is unlikely to work.

500



4. Timeouts

After sending the request the module waits 1 second for an answer. If this timeout expires the request ist resent and the module waits 2 more seconds. It this second timeout expires the request is sent a third time and the module waits 3 more seconds. If there is no answer after sending the request three times and a cumulated timeout of 6 seconds, a internal server-error is reported to the browser.

5. Messagelength

The module and the udpauthserver both read only the first 1023 bytes of the udp-packet and silently discard the rest. To avoid any buffer overflow usernames, passwords and groups are truncated to at most 100 bytes before creating the request. The only way to get a buffer-overflow within the module would be a configuration with a great number of long group names.

6. Future extensions

The protocol was designed to be extensible. Additional Information could be added easily to the requests.

7. Some Why?s

Why udp ? It has very little overhead and thus is fast.

Why fixed maximum messagelength ? It avoids network congestion and thus keeps the server running.

Why \0 as separator ? Apache is written in C and this one character can never be a part of a valid C-string. With any other character some kind of escaping would be necessary.