# HG changeset patch # User Timo Sirainen # Date 1098452643 -10800 # Node ID 74517c34a68766d5dccae2b84361d488e161c70f # Parent 0b1bef51f2075d04af0a24f381e132d2011eaad9 Dovecot authentication protocol v1.0 diff -r 0b1bef51f207 -r 74517c34a687 doc/Makefile.am --- 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 \ diff -r 0b1bef51f207 -r 74517c34a687 doc/auth-protocol.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: + + 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 TAB + C: "SERVICE" TAB (optional) + C: "CPID" TAB + + S: "VERSION" TAB TAB + S: "SPID" TAB + S: "CUID" TAB + S: "MECH" TAB [TAB ] (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 TAB  [TAB ] + + S1: "FAIL" TAB [TAB ] + S2: "CONT" TAB TAB + S3: "OK" TAB [TAB ] + +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 - in standard string format, + - rip= : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1 + - service= : Service name (eg. POP3, IMAP, SMTP) + - resp= : 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=" 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 TAB + S: "SPID" TAB + + M: "VERSION" TAB TAB + +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 TAB TAB + M: "USER" TAB TAB + M: "DIE" + + S: "NOTFOUND" TAB + S: "FAIL" TAB TAB + S: "USER" TAB TAB [TAB ] + +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= : System user ID. + gid= : System group ID. + home= : Home directory. + chroot= : Chroot directory. + mail= : Mail location. + system_user= : System user name which can be used to get extra groups. + This will probably be replaced later by giving just + multiple gid fields.