"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "dovecot-1.0.15/doc/auth-protocol.txt" of archive dovecot-1.0.15.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 Dovecot Authentication Protocol v1.0
2
3
4 General
5 -------
6
7 This is a line based protocol. Each line is a command which ends with an LF
8 character. The maximum line length isn't defined, but it's currently
9 expected to fit into 8192 bytes. Authentication mechanism specific data
10 transfers are the largest single parameters.
11
12 Each command is in format:
13
14 <command name> TAB <parameters separated with TAB>
15
16 Parameters are split into required and optional parameters. Required
17 parameters aren't in any specific format, but optional parameters are
18 either booleans without a value, or a name=value pair. If optional parameter
19 name is unknown, the parameter should just be ignored.
20
21 Typical command looks like (without spaces):
22
23 command TAB param1 TAB param2 TAB optname=value TAB optboolean
24
25 There is no way to have TABs or LFs in parameters.
26
27
28 Client <-> Server
29 -----------------
30
31 Client is an untrusted authentication client process. It can serve one or
32 more users, so from user's point of view it's usually eg. IMAP or SMTP
33 server process.
34
35 Server is an authentication server process.
36
37 The connection starts by both client and server sending handshakes:
38
39 C: "VERSION" TAB <major> TAB <minor>
40 C: "CPID" TAB <pid>
41
42 S: "VERSION" TAB <major> TAB <minor>
43 S: "SPID" TAB <pid>
44 S: "CUID" TAB <pid>
45 S: "MECH" TAB <name> [TAB <parameters>] (multiple times)
46 S: "DONE"
47
48 Both client and server should check that they support the same major version
49 number. If they don't, the other side isn't expected to be talking the same
50 protocol and should be disconnected. Minor version can be ignored. This
51 document is version number 1.0.
52
53 CPID, SPID and specify client and server PIDs. They should be unique
54 identifiers for the specific process. UNIX process IDs are good choices.
55
56 CUID is a server process-specific unique connection identifier. It's
57 different each time a connection is established for the server.
58
59 CPID is used by master's REQUEST command.
60
61 SPID can be used by authentication client to tell master what server
62 process handled the authentication.
63
64 CUID is currently useful only for APOP authentication.
65
66 DONE finishes the handshake from server. CPID finishes the handshake from
67 client.
68
69
70 Authentication Mechanisms
71 -------------------------
72
73 MECH command announces an available authentication SASL mechanism.
74 Mechanisms may have parameters giving some details about them:
75
76 - anonymous : Anonymous authentication
77 - plaintext : Transfers plaintext passwords
78 - dictionary : Subject to passive (dictionary) attack
79 - active : Subject to active (non-dictionary) attack
80 - forward-secrecy : Provides forward secrecy between sessions
81 - mutual-auth : Provides mutual authentication
82 - private : Don't advertise this as available SASL mechanism (eg. APOP)
83
84
85 Authentication Request
86 ----------------------
87
88 C: "AUTH" TAB <id> TAB <mechanism> TAB service=<service> [TAB <parameters>]
89
90 S1: "FAIL" TAB <id> [TAB <parameters>]
91 S2: "CONT" TAB <id> TAB <base64 data>
92 S3: "OK" TAB <id> [TAB <parameters>]
93
94 ID is a connection-specific unique request identifier. It must be a 32bit
95 number, so typically you'd just increment it by one.
96
97 Service is the service requesting authentication, eg. POP3, IMAP, SMTP.
98
99 AUTH parameters are:
100
101 - lip=<local ip> : Local IP - in standard string format,
102 - rip=<remote ip> : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1
103 - secured : Remote user has secured transport to auth client
104 (eg. localhost, SSL, TLS)
105 - valid-client-cert : Remote user has presented a valid SSL certificate.
106 - resp=<base64> : Initial response for authentication mechanism.
107 NOTE: This must be the last parameter. Everything
108 after it is ignored. This is to avoid accidental
109 security holes if user-given data is directly put to
110 base64 string without filtering out tabs.
111
112 FAIL parameters may contain "reason=.." parameter which should be sent to
113 remote user instead of a standard "Authentication failed" message. For
114 example "invalid base64 data". It should NOT be used to give exact reason
115 for authentication failure (ie. "user not found" vs. "password mismatch").
116 Sending "temp" parameter indicates that the error was a temporary internal
117 failure, eg. connection was lost to SQL database.
118
119 CONT command means that the authentication continues, and more data is
120 expected from client to finish the authentication. Given base64 data should
121 be sent to client.
122
123 FAIL and OK may contain multiple unspecified parameters which
124 authentication client may handle specially. The only one specified here is
125 "user=<userid>" parameter, which should always be sent if userid is known.
126
127
128 Server <-> Master
129 -----------------
130
131 Master is a trusted process which may query results of previous client
132 authentication or information about a specific user. Master is optional and
133 in SMTP AUTH case it's not needed.
134
135 The connection starts by both server and master sending handshakes:
136
137 S: "VERSION" TAB <major> TAB <minor>
138 S: "SPID" TAB <pid>
139
140 M: "VERSION" TAB <major> TAB <minor>
141
142 Auth with client <-> server, both should check that the version numbers are
143 valid.
144
145 SPID can be used to let master identify the server process.
146
147
148 Master Requests
149 ---------------
150
151 M: "REQUEST" TAB <id> TAB <client-pid> TAB <client-id>
152 M: "USER" TAB <id> TAB <userid> TAB service=<service> [TAB <parameters>]
153
154 S: "NOTFOUND" TAB <id>
155 S: "FAIL" TAB <id> TAB <error message>
156 S: "USER" TAB <id> TAB <userid> [TAB <parameters>]
157
158 Master commands can request information about existing authentication
159 request, or about a specified user.
160
161 USER command's service and parameters are the same as with AUTH client
162 request.
163
164 ID is a connection-specific unique request identifier. It must be a 32bit
165 number, so typically you'd just increment it by one.
166
167 NOTFOUND reply means that the request or user wasn't found. Master
168 shouldn't even try to send REQUEST commands for nonexisting requests, so if
169 it happens it means either a timeout caused by very high load, or client
170 lying to master about the request.
171
172 FAIL reply means an internal error occurred. Usually either a configuration
173 mistake or temporary error caused by lost resource (eg. database down).
174
175 USER reply is sent if request succeeded. It can return parameters:
176
177 uid=<uid> : System user ID.
178 gid=<gid> : System group ID.
179 home=<dir> : Home directory.
180 chroot=<dir> : Chroot directory.
181 mail=<data> : Mail location.
182 system_user=<user> : System user name which can be used to get extra groups.
183 This will probably be replaced later by giving just
184 multiple gid fields.