From: Timo Sirainen Date: Fri, 18 Nov 2011 20:14:02 +0000 (+0200) Subject: doc: Removed auth-protocol.txt. A more up to date version is in wiki docs. X-Git-Tag: 2.1.rc1~52 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9055976274624da853fb66fee4e6561cb9155a49;p=thirdparty%2Fdovecot%2Fcore.git doc: Removed auth-protocol.txt. A more up to date version is in wiki docs. --- diff --git a/doc/auth-protocol.txt b/doc/auth-protocol.txt deleted file mode 100644 index c7a0f1c761..0000000000 --- a/doc/auth-protocol.txt +++ /dev/null @@ -1,197 +0,0 @@ -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.