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.