Mercurial > dovecot > original-hg > dovecot-1.2
annotate doc/auth-protocol.txt @ 9301:85e39b7710ee HEAD
autocreate: Fixed autosubscribing to mailboxes in subscriptions=no namespaces.
Also log autosubscribe failures if mail_debug=yes.
author | Timo Sirainen <tss@iki.fi> |
---|---|
date | Sun, 09 Aug 2009 14:55:11 -0400 |
parents | 24c8bc8098ee |
children |
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: "CPID" TAB <pid> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
41 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
42 S: "VERSION" TAB <major> TAB <minor> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
43 S: "SPID" TAB <pid> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
44 S: "CUID" TAB <pid> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
45 S: "MECH" TAB <name> [TAB <parameters>] (multiple times) |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
46 S: "DONE" |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
47 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
48 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
|
49 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
|
50 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
|
51 document is version number 1.0. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
52 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
53 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
|
54 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
|
55 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
56 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
|
57 different each time a connection is established for the server. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
58 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
59 CPID is used by master's REQUEST command. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
60 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
61 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
|
62 process handled the authentication. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
63 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
64 CUID is currently useful only for APOP authentication. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
65 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
66 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
|
67 client. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
68 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
69 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
70 Authentication Mechanisms |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
71 ------------------------- |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
72 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
73 MECH command announces an available authentication SASL mechanism. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
74 Mechanisms may have parameters giving some details about them: |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
75 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
76 - anonymous : Anonymous authentication |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
77 - plaintext : Transfers plaintext passwords |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
78 - dictionary : Subject to passive (dictionary) attack |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
79 - active : Subject to active (non-dictionary) attack |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
80 - forward-secrecy : Provides forward secrecy between sessions |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
81 - mutual-auth : Provides mutual authentication |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
82 - 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
|
83 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
84 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
85 Authentication Request |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
86 ---------------------- |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
87 |
3338
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
88 C: "AUTH" TAB <id> TAB <mechanism> TAB service=<service> [TAB <parameters>] |
2810
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 S1: "FAIL" TAB <id> [TAB <parameters>] |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
91 S2: "CONT" TAB <id> TAB <base64 data> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
92 S3: "OK" TAB <id> [TAB <parameters>] |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
93 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
94 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
|
95 number, so typically you'd just increment it by one. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
96 |
3338
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
97 Service is the service requesting authentication, eg. POP3, IMAP, SMTP. |
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
98 |
2810
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
99 AUTH parameters are: |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
100 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
101 - lip=<local ip> : Local IP - in standard string format, |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
102 - rip=<remote ip> : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1 |
5882
40ce533c88f9
Send local/remote ports to dovecot-auth. They're now in %a and %b variables.
Timo Sirainen <tss@iki.fi>
parents:
4800
diff
changeset
|
103 - lport=<port> : Local port number |
40ce533c88f9
Send local/remote ports to dovecot-auth. They're now in %a and %b variables.
Timo Sirainen <tss@iki.fi>
parents:
4800
diff
changeset
|
104 - rport=<port> : Remote port number |
2810
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
105 - secured : Remote user has secured transport to auth client |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
106 (eg. localhost, SSL, TLS) |
4099
0c11f0b05e19
Fixed outdated information: ssl-valid-cert -> valid-client-cert
Timo Sirainen <timo.sirainen@movial.fi>
parents:
3520
diff
changeset
|
107 - valid-client-cert : Remote user has presented a valid SSL certificate. |
4682
bc071307fc2a
Require that the "resp" parameter for AUTH command is the last.
Timo Sirainen <tss@iki.fi>
parents:
4099
diff
changeset
|
108 - resp=<base64> : Initial response for authentication mechanism. |
bc071307fc2a
Require that the "resp" parameter for AUTH command is the last.
Timo Sirainen <tss@iki.fi>
parents:
4099
diff
changeset
|
109 NOTE: This must be the last parameter. Everything |
bc071307fc2a
Require that the "resp" parameter for AUTH command is the last.
Timo Sirainen <tss@iki.fi>
parents:
4099
diff
changeset
|
110 after it is ignored. This is to avoid accidental |
bc071307fc2a
Require that the "resp" parameter for AUTH command is the last.
Timo Sirainen <tss@iki.fi>
parents:
4099
diff
changeset
|
111 security holes if user-given data is directly put to |
bc071307fc2a
Require that the "resp" parameter for AUTH command is the last.
Timo Sirainen <tss@iki.fi>
parents:
4099
diff
changeset
|
112 base64 string without filtering out tabs. |
2810
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
113 |
8413
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
114 FAIL parameters may contain: |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
115 |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
116 - reason=<str> : <str> should be sent to remote user instead of the standard |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
117 "Authentication failed" messages. For example "invalid base64 |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
118 data". It must NOT be used to give exact reason for |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
119 authentication failure (i.e. "user not found" vs. "password |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
120 mismatch"). |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
121 - temp : This is a temporary internal failure, e.g. connection was |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
122 lost to SQL database. |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
123 - authz : Authentication succeeded, but authorization failed (master |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
124 user's password was ok, but destnation user was not ok). |
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
125 Added in Dovecot v1.2. |
2810
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 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
|
128 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
|
129 be sent to client. |
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 FAIL and OK may contain multiple unspecified parameters which |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
132 authentication client may handle specially. The only one specified here is |
8413
24c8bc8098ee
Give a different error message if authentication succeeds but authorization fails.
Timo Sirainen <tss@iki.fi>
parents:
5882
diff
changeset
|
133 "user=<userid>" parameter, which should always be sent if the userid is known. |
2810
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 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
136 Server <-> Master |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
137 ----------------- |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
138 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
139 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
|
140 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
|
141 in SMTP AUTH case it's not needed. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
142 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
143 The connection starts by both server and master sending handshakes: |
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 S: "VERSION" TAB <major> TAB <minor> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
146 S: "SPID" TAB <pid> |
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 M: "VERSION" TAB <major> TAB <minor> |
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 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
|
151 valid. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
152 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
153 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
|
154 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
155 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
156 Master Requests |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
157 --------------- |
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 M: "REQUEST" TAB <id> TAB <client-pid> TAB <client-id> |
3338
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
160 M: "USER" TAB <id> TAB <userid> TAB service=<service> [TAB <parameters>] |
2810
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 S: "NOTFOUND" TAB <id> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
163 S: "FAIL" TAB <id> TAB <error message> |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
164 S: "USER" TAB <id> TAB <userid> [TAB <parameters>] |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
165 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
166 Master commands can request information about existing authentication |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
167 request, or about a specified user. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
168 |
3338
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
169 USER command's service and parameters are the same as with AUTH client |
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
170 request. |
e5ce49c8524a
USER auth command requires now service parameter and supports also others
Timo Sirainen <tss@iki.fi>
parents:
3070
diff
changeset
|
171 |
2810
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
172 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
|
173 number, so typically you'd just increment it by one. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
174 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
175 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
|
176 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
|
177 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
|
178 lying to master about the request. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
179 |
3520 | 180 FAIL reply means an internal error occurred. Usually either a configuration |
2810
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
181 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
|
182 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
183 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
|
184 |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
185 uid=<uid> : System user ID. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
186 gid=<gid> : System group ID. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
187 home=<dir> : Home directory. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
188 chroot=<dir> : Chroot directory. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
189 mail=<data> : Mail location. |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
190 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
|
191 This will probably be replaced later by giving just |
74517c34a687
Dovecot authentication protocol v1.0
Timo Sirainen <tss@iki.fi>
parents:
diff
changeset
|
192 multiple gid fields. |