Dovecot Authentication Protocol v1.1 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: "CPID" TAB S: "VERSION" TAB TAB S: "SPID" TAB S: "CUID" TAB S: "COOKIE" 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.1. 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. COOKIE returns connection-specific 128 bit cookie in hex. It must be given to REQUEST command. (Protocol v1.1+ / Dovecot v2.0+) 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 service= [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. Service is the service requesting authentication, eg. POP3, IMAP, SMTP. AUTH parameters are: - lip= : Local IP - in standard string format, - rip= : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1 - lport= : Local port number - rport= : Remote port number - secured : Remote user has secured transport to auth client (eg. localhost, SSL, TLS) - valid-client-cert : Remote user has presented a valid SSL certificate. - resp= : Initial response for authentication mechanism. NOTE: This must be the last parameter. Everything after it is ignored. This is to avoid accidental security holes if user-given data is directly put to base64 string without filtering out tabs. FAIL parameters may contain: - reason= : should be sent to remote user instead of the standard "Authentication failed" messages. For example "invalid base64 data". It must NOT be used to give exact reason for authentication failure (i.e. "user not found" vs. "password mismatch"). - temp : This is a temporary internal failure, e.g. connection was lost to SQL database. - authz : Authentication succeeded, but authorization failed (master user's password was ok, but destnation user was not ok). Added in Dovecot v1.2. 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 the 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 TAB M: "USER" TAB TAB TAB service= [TAB ] 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. USER command's service and parameters are the same as with AUTH client request. ID is a connection-specific unique request identifier. It must be a 32bit number, so typically you'd just increment it by one. NOTFOUND reply means that the user wasn't found. FAIL reply means an internal error occurred. Usually either a configuration mistake or temporary error caused by lost resource (eg. database down). Also unknown request IDs are reported as FAILs. Currently the only specified parameter is "reason", which is used when user is wanted to be put into "temporarily disabled" state and the reason string will be shown to user on login or to LMTP RCPT TO reply. 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.