dovecot-2.1: doc: Removed auth-protocol.txt. A more up to date v...
dovecot at dovecot.org
dovecot at dovecot.org
Fri Nov 18 22:14:24 EET 2011
details: http://hg.dovecot.org/dovecot-2.1/rev/46b07e8dca14
changeset: 13729:46b07e8dca14
user: Timo Sirainen <tss at iki.fi>
date: Fri Nov 18 22:14:02 2011 +0200
description:
doc: Removed auth-protocol.txt. A more up to date version is in wiki docs.
diffstat:
doc/auth-protocol.txt | 191 --------------------------------------------------
1 files changed, 0 insertions(+), 191 deletions(-)
diffs (201 lines):
diff -r 9a6aa717bc46 -r 46b07e8dca14 doc/auth-protocol.txt
--- a/doc/auth-protocol.txt Fri Nov 18 22:07:16 2011 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -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:
-
- <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: "CPID" TAB <pid>
-
- S: "VERSION" TAB <major> TAB <minor>
- S: "SPID" TAB <pid>
- S: "CUID" TAB <pid>
- S: "COOKIE" TAB <cookie>
- 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.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 <id> TAB <mechanism> TAB service=<service> [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.
-
-Service is the service requesting authentication, eg. POP3, IMAP, SMTP.
-
-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
- - lport=<port> : Local port number
- - rport=<port> : 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=<base64> : 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=<str> : <str> 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=<userid>" 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 <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> TAB <cookie>
- M: "USER" TAB <id> TAB <userid> TAB service=<service> [TAB <parameters>]
-
- S: "NOTFOUND" TAB <id>
- S: "FAIL" TAB <id> [TAB <parameters>]
- S: "USER" TAB <id> TAB <userid> [TAB <parameters>]
-
-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=<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.
More information about the dovecot-cvs
mailing list