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