--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/auth-protocol.txt	Fri Oct 22 16:44:03 2004 +0300
@@ -0,0 +1,184 @@
+Dovecot Authentication Protocol v1.0
+
+
+General
+-------
+
+This is a line based protocol. Each line is a command which ends with an LF
+character. The maximum line length isn't defined, but it's currently
+expected to fit into 8192 bytes. Authentication mechanism specific data
+transfers are the largest single parameters.
+
+Each command is in format:
+
+  <command name> TAB <parameters separated with TAB>
+
+Parameters are split into required and optional parameters. Required
+parameters aren't in any specific format, but optional parameters are
+either booleans without a value, or a name=value pair. If optional parameter
+name is unknown, the parameter should just be ignored.
+
+Typical command looks like (without spaces):
+
+ command TAB param1 TAB param2 TAB optname=value TAB optboolean
+
+There is no way to have TABs or LFs in parameters.
+
+
+Client <-> Server
+-----------------
+
+Client is an untrusted authentication client process. It can serve one or
+more users, so from user's point of view it's usually eg. IMAP or SMTP
+server process.
+
+Server is an authentication server process.
+
+The connection starts by both client and server sending handshakes:
+
+ C: "VERSION" TAB <major> TAB <minor>
+ C: "SERVICE" TAB <service> (optional)
+ C: "CPID" TAB <pid>
+
+ S: "VERSION" TAB <major> TAB <minor>
+ S: "SPID" TAB <pid>
+ S: "CUID" TAB <pid>
+ S: "MECH" TAB <name> [TAB <parameters>] (multiple times)
+ S: "DONE"
+
+Both client and server should check that they support the same major version
+number. If they don't, the other side isn't expected to be talking the same
+protocol and should be disconnected. Minor version can be ignored. This
+document is version number 1.0.
+
+CPID, SPID and specify client and server PIDs. They should be unique
+identifiers for the specific process. UNIX process IDs are good choices.
+
+CUID is a server process-specific unique connection identifier. It's
+different each time a connection is established for the server.
+
+CPID is used by master's REQUEST command.
+
+SPID can be used by authentication client to tell master what server
+process handled the authentication.
+
+CUID is currently useful only for APOP authentication.
+
+SERVICE command can be used to specify default service name for
+authentication requests. If it's not set, each request must specify the
+service separately.
+
+DONE finishes the handshake from server. CPID finishes the handshake from
+client.
+
+
+Authentication Mechanisms
+-------------------------
+
+MECH command announces an available authentication SASL mechanism.
+Mechanisms may have parameters giving some details about them:
+
+ - anonymous   : Anonymous authentication
+ - plaintext   : Transfers plaintext passwords
+ - dictionary  : Subject to passive (dictionary) attack
+ - active      : Subject to active (non-dictionary) attack
+ - forward-secrecy : Provides forward secrecy between sessions
+ - mutual-auth : Provides mutual authentication
+ - private     : Don't advertise this as available SASL mechanism (eg. APOP)
+
+
+Authentication Request
+----------------------
+
+ C: "AUTH" TAB <id> TAB <mechanism> [TAB <parameters>]
+
+ S1: "FAIL" TAB <id> [TAB <parameters>]
+ S2: "CONT" TAB <id> TAB <base64 data>
+ S3: "OK" TAB <id> [TAB <parameters>]
+
+ID is a connection-specific unique request identifier. It must be a 32bit
+number, so typically you'd just increment it by one.
+
+AUTH parameters are:
+
+ - lip=<local ip>    : Local IP  - in standard string format,
+ - rip=<remote ip>   : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1
+ - service=<service> : Service name (eg. POP3, IMAP, SMTP)
+ - resp=<base64>     : Initial response for authentication mechanism
+ - secured           : Remote user has secured transport to auth client
+                       (eg. localhost, SSL, TLS)
+ - ssl-valid-cert    : Remote user has presented a valid SSL certificate.
+
+FAIL parameters may contain "reason=.." parameter which should be sent to
+remote user instead of a standard "Authentication failed" message. For
+example "invalid base64 data" or "temporary internal failure". It should
+NOT be used to give exact reason for authentication failure (ie. "user not
+found" vs. "password mismatch").
+
+CONT command means that the authentication continues, and more data is
+expected from client to finish the authentication. Given base64 data should
+be sent to client.
+
+FAIL and OK may contain multiple unspecified parameters which
+authentication client may handle specially. The only one specified here is
+"user=<userid>" parameter, which should always be sent if userid is known.
+
+
+Server <-> Master
+-----------------
+
+Master is a trusted process which may query results of previous client
+authentication or information about a specific user. Master is optional and
+in SMTP AUTH case it's not needed.
+
+The connection starts by both server and master sending handshakes:
+
+ S: "VERSION" TAB <major> TAB <minor>
+ S: "SPID" TAB <pid>
+
+ M: "VERSION" TAB <major> TAB <minor>
+
+Auth with client <-> server, both should check that the version numbers are
+valid.
+
+SPID can be used to let master identify the server process.
+
+
+Master Requests
+---------------
+
+ M: "REQUEST" TAB <id> TAB <client-pid> TAB <client-id>
+ M: "USER" TAB <id> TAB <userid>
+ M: "DIE"
+
+ S: "NOTFOUND" TAB <id>
+ S: "FAIL" TAB <id> TAB <error message>
+ S: "USER" TAB <id> TAB <userid> [TAB <parameters>]
+
+Master commands can request information about existing authentication
+request, or about a specified user.
+
+ID is a connection-specific unique request identifier. It must be a 32bit
+number, so typically you'd just increment it by one.
+
+DIE makes the server stop accepting new requests, and as soon as the
+existing requests are finished, it kills itself.
+
+NOTFOUND reply means that the request or user wasn't found. Master
+shouldn't even try to send REQUEST commands for nonexisting requests, so if
+it happens it means either a timeout caused by very high load, or client
+lying to master about the request.
+
+FAIL reply means an internal error occured. Usually either a configuration
+mistake or temporary error caused by lost resource (eg. database down).
+
+USER reply is sent if request succeeded. It can return parameters:
+
+ uid=<uid>          : System user ID.
+ gid=<gid>          : System group ID.
+ home=<dir>         : Home directory.
+ chroot=<dir>       : Chroot directory.
+ mail=<data>        : Mail location.
+ system_user=<user> : System user name which can be used to get extra groups.
+                      This will probably be replaced later by giving just
+		      multiple gid fields.