Mercurial > dovecot > original-hg > dovecot-1.2
changeset 2810:74517c34a687 HEAD
Dovecot authentication protocol v1.0
author | Timo Sirainen <tss@iki.fi> |
---|---|
date | Fri, 22 Oct 2004 16:44:03 +0300 |
parents | 0b1bef51f207 |
children | 253fae0aa95f |
files | doc/Makefile.am doc/auth-protocol.txt |
diffstat | 2 files changed, 185 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/Makefile.am Fri Oct 22 16:42:55 2004 +0300 +++ b/doc/Makefile.am Fri Oct 22 16:44:03 2004 +0300 @@ -2,6 +2,7 @@ doc_DATA = \ auth.txt \ + auth-protocol.txt \ configuration.txt \ design.txt \ index.txt \
--- /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.