annotate doc/auth-protocol.txt @ 8413:24c8bc8098ee HEAD

Give a different error message if authentication succeeds but authorization fails. Added a new "authz" parameter for FAIL result in the auth protocol for this.
author Timo Sirainen <tss@iki.fi>
date Sat, 15 Nov 2008 21:29:59 +0200
parents 40ce533c88f9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
e2fe8222449d s/occured/occurred/
Timo Sirainen <tss@iki.fi>
parents: 3338
diff changeset
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.