Mercurial > dovecot > original-hg > dovecot-1.2
comparison doc/auth-protocol.txt @ 2810:74517c34a687 HEAD
Dovecot authentication protocol v1.0
author | Timo Sirainen <tss@iki.fi> |
---|---|
date | Fri, 22 Oct 2004 16:44:03 +0300 |
parents | |
children | 052f3a5743af |
comparison
equal
deleted
inserted
replaced
2809:0b1bef51f207 | 2810:74517c34a687 |
---|---|
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: "SERVICE" TAB <service> (optional) | |
41 C: "CPID" TAB <pid> | |
42 | |
43 S: "VERSION" TAB <major> TAB <minor> | |
44 S: "SPID" TAB <pid> | |
45 S: "CUID" TAB <pid> | |
46 S: "MECH" TAB <name> [TAB <parameters>] (multiple times) | |
47 S: "DONE" | |
48 | |
49 Both client and server should check that they support the same major version | |
50 number. If they don't, the other side isn't expected to be talking the same | |
51 protocol and should be disconnected. Minor version can be ignored. This | |
52 document is version number 1.0. | |
53 | |
54 CPID, SPID and specify client and server PIDs. They should be unique | |
55 identifiers for the specific process. UNIX process IDs are good choices. | |
56 | |
57 CUID is a server process-specific unique connection identifier. It's | |
58 different each time a connection is established for the server. | |
59 | |
60 CPID is used by master's REQUEST command. | |
61 | |
62 SPID can be used by authentication client to tell master what server | |
63 process handled the authentication. | |
64 | |
65 CUID is currently useful only for APOP authentication. | |
66 | |
67 SERVICE command can be used to specify default service name for | |
68 authentication requests. If it's not set, each request must specify the | |
69 service separately. | |
70 | |
71 DONE finishes the handshake from server. CPID finishes the handshake from | |
72 client. | |
73 | |
74 | |
75 Authentication Mechanisms | |
76 ------------------------- | |
77 | |
78 MECH command announces an available authentication SASL mechanism. | |
79 Mechanisms may have parameters giving some details about them: | |
80 | |
81 - anonymous : Anonymous authentication | |
82 - plaintext : Transfers plaintext passwords | |
83 - dictionary : Subject to passive (dictionary) attack | |
84 - active : Subject to active (non-dictionary) attack | |
85 - forward-secrecy : Provides forward secrecy between sessions | |
86 - mutual-auth : Provides mutual authentication | |
87 - private : Don't advertise this as available SASL mechanism (eg. APOP) | |
88 | |
89 | |
90 Authentication Request | |
91 ---------------------- | |
92 | |
93 C: "AUTH" TAB <id> TAB <mechanism> [TAB <parameters>] | |
94 | |
95 S1: "FAIL" TAB <id> [TAB <parameters>] | |
96 S2: "CONT" TAB <id> TAB <base64 data> | |
97 S3: "OK" TAB <id> [TAB <parameters>] | |
98 | |
99 ID is a connection-specific unique request identifier. It must be a 32bit | |
100 number, so typically you'd just increment it by one. | |
101 | |
102 AUTH parameters are: | |
103 | |
104 - lip=<local ip> : Local IP - in standard string format, | |
105 - rip=<remote ip> : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1 | |
106 - service=<service> : Service name (eg. POP3, IMAP, SMTP) | |
107 - resp=<base64> : Initial response for authentication mechanism | |
108 - secured : Remote user has secured transport to auth client | |
109 (eg. localhost, SSL, TLS) | |
110 - ssl-valid-cert : Remote user has presented a valid SSL certificate. | |
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" or "temporary internal failure". It should | |
115 NOT be used to give exact reason for authentication failure (ie. "user not | |
116 found" vs. "password mismatch"). | |
117 | |
118 CONT command means that the authentication continues, and more data is | |
119 expected from client to finish the authentication. Given base64 data should | |
120 be sent to client. | |
121 | |
122 FAIL and OK may contain multiple unspecified parameters which | |
123 authentication client may handle specially. The only one specified here is | |
124 "user=<userid>" parameter, which should always be sent if userid is known. | |
125 | |
126 | |
127 Server <-> Master | |
128 ----------------- | |
129 | |
130 Master is a trusted process which may query results of previous client | |
131 authentication or information about a specific user. Master is optional and | |
132 in SMTP AUTH case it's not needed. | |
133 | |
134 The connection starts by both server and master sending handshakes: | |
135 | |
136 S: "VERSION" TAB <major> TAB <minor> | |
137 S: "SPID" TAB <pid> | |
138 | |
139 M: "VERSION" TAB <major> TAB <minor> | |
140 | |
141 Auth with client <-> server, both should check that the version numbers are | |
142 valid. | |
143 | |
144 SPID can be used to let master identify the server process. | |
145 | |
146 | |
147 Master Requests | |
148 --------------- | |
149 | |
150 M: "REQUEST" TAB <id> TAB <client-pid> TAB <client-id> | |
151 M: "USER" TAB <id> TAB <userid> | |
152 M: "DIE" | |
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 ID is a connection-specific unique request identifier. It must be a 32bit | |
162 number, so typically you'd just increment it by one. | |
163 | |
164 DIE makes the server stop accepting new requests, and as soon as the | |
165 existing requests are finished, it kills itself. | |
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 occured. 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. |