← Back to branch summary

~james-page/ubuntu/raring/dovecot/autopkgtest

« back to all changes in this revision

Viewing changes to doc/auth-protocol.txt

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2012-06-11 11:11:54 UTC
  • mfrom: (1.15.2) (4.1.27 sid)
  • Revision ID: package-import@ubuntu.com-20120611111154-678cwbdj6ktgsv1h
Tags: 1:2.1.7-1ubuntu1
* Merge from Debian unstable, remaining changes:
  + Add mail-stack-delivery package:
    - Update d/rules
    - d/control: convert existing dovecot-postfix package to a dummy
      package and add new mail-stack-delivery package.
    - Update maintainer scripts.
    - Rename d/dovecot-postfix.* to debian/mail-stack-delivery.*
    - d/mail-stack-delivery.preinst: Move previously installed backups and
      config files to a new package namespace.
    - d/mail-stack-delivery.prerm: Added to handle downgrades.
  + Use Snakeoil SSL certificates by default:
    - d/control: Depend on ssl-cert.
    - d/dovecot-core.postinst: Relax grep for SSL_* a bit.
  + Add autopkgtest to debian/tests/*.
  + Add ufw integration:
    - d/dovecot-core.ufw.profile: new ufw profile.
    - d/rules: install profile in dovecot-core.
    - d/control: dovecot-core - suggest ufw.
  + d/{control,rules}: enable PIE hardening.
  + d/dovecot-core.dirs: Added usr/share/doc/dovecot-core
  + Add apport hook:
    - d/rules, d/source_dovecot.py
  + Add upstart job:
    - d/rules, d/dovecot-core.dovecot.upstart, d/control,
      d/dovecot-core.dirs, dovecot-imapd.{postrm, postinst, prerm},
      d/dovecot-pop3d.{postinst, postrm, prerm}.
      d/mail-stack-deliver.postinst: Convert init script to upstart.
  + d/control: Added Pre-Depends: dpkg (>= 1.15.6) to dovecot-dbg to support
    xz compression in Ubuntu.
  + d/control: Demote dovecot-common Recommends: to Suggests: to prevent
    install of extra packages on upgrade.
  + d/patches/dovecot-drac.patch: Updated with version for dovecot >= 2.0.0.
  + d/control: Drop B-D on systemd.
* Dropped changes:
  + d/patches/fix-racey-restart.patch: part of 2.1.x, no longer required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/auth-protocol.txt
1
 
Dovecot Authentication Protocol v1.1
2
 
 
3
 
 
4
 
General
5
 
-------
6
 
 
7
 
This is a line based protocol. Each line is a command which ends with an LF
8
 
character. The maximum line length isn't defined, but it's currently
9
 
expected to fit into 8192 bytes. Authentication mechanism specific data
10
 
transfers are the largest single parameters.
11
 
 
12
 
Each command is in format:
13
 
 
14
 
  <command name> TAB <parameters separated with TAB>
15
 
 
16
 
Parameters are split into required and optional parameters. Required
17
 
parameters aren't in any specific format, but optional parameters are
18
 
either booleans without a value, or a name=value pair. If optional parameter
19
 
name is unknown, the parameter should just be ignored.
20
 
 
21
 
Typical command looks like (without spaces):
22
 
 
23
 
 command TAB param1 TAB param2 TAB optname=value TAB optboolean
24
 
 
25
 
There is no way to have TABs or LFs in parameters.
26
 
 
27
 
 
28
 
Client <-> Server
29
 
-----------------
30
 
 
31
 
Client is an untrusted authentication client process. It can serve one or
32
 
more users, so from user's point of view it's usually eg. IMAP or SMTP
33
 
server process.
34
 
 
35
 
Server is an authentication server process.
36
 
 
37
 
The connection starts by both client and server sending handshakes:
38
 
 
39
 
 C: "VERSION" TAB <major> TAB <minor>
40
 
 C: "CPID" TAB <pid>
41
 
 
42
 
 S: "VERSION" TAB <major> TAB <minor>
43
 
 S: "SPID" TAB <pid>
44
 
 S: "CUID" TAB <pid>
45
 
 S: "COOKIE" TAB <cookie>
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.1.
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
 
COOKIE returns connection-specific 128 bit cookie in hex. It must be
68
 
given to REQUEST command. (Protocol v1.1+ / Dovecot v2.0+)
69
 
 
70
 
DONE finishes the handshake from server. CPID finishes the handshake from
71
 
client.
72
 
 
73
 
 
74
 
Authentication Mechanisms
75
 
-------------------------
76
 
 
77
 
MECH command announces an available authentication SASL mechanism.
78
 
Mechanisms may have parameters giving some details about them:
79
 
 
80
 
 - anonymous   : Anonymous authentication
81
 
 - plaintext   : Transfers plaintext passwords
82
 
 - dictionary  : Subject to passive (dictionary) attack
83
 
 - active      : Subject to active (non-dictionary) attack
84
 
 - forward-secrecy : Provides forward secrecy between sessions
85
 
 - mutual-auth : Provides mutual authentication
86
 
 - private     : Don't advertise this as available SASL mechanism (eg. APOP)
87
 
 
88
 
 
89
 
Authentication Request
90
 
----------------------
91
 
 
92
 
 C: "AUTH" TAB <id> TAB <mechanism> TAB service=<service> [TAB <parameters>]
93
 
 
94
 
 S1: "FAIL" TAB <id> [TAB <parameters>]
95
 
 S2: "CONT" TAB <id> TAB <base64 data>
96
 
 S3: "OK" TAB <id> [TAB <parameters>]
97
 
 
98
 
ID is a connection-specific unique request identifier. It must be a 32bit
99
 
number, so typically you'd just increment it by one.
100
 
 
101
 
Service is the service requesting authentication, eg. POP3, IMAP, SMTP.
102
 
 
103
 
AUTH parameters are:
104
 
 
105
 
 - lip=<local ip>    : Local IP  - in standard string format,
106
 
 - rip=<remote ip>   : Remote IP - ie. for IPv4 127.0.0.1 and for IPv6 ::1
107
 
 - lport=<port>      : Local port number
108
 
 - rport=<port>      : Remote port number
109
 
 - secured           : Remote user has secured transport to auth client
110
 
                       (eg. localhost, SSL, TLS)
111
 
 - valid-client-cert : Remote user has presented a valid SSL certificate.
112
 
 - resp=<base64>     : Initial response for authentication mechanism.
113
 
                       NOTE: This must be the last parameter. Everything
114
 
                       after it is ignored. This is to avoid accidental
115
 
                       security holes if user-given data is directly put to
116
 
                       base64 string without filtering out tabs.
117
 
 
118
 
FAIL parameters may contain:
119
 
 
120
 
 - reason=<str> : <str> should be sent to remote user instead of the standard
121
 
                  "Authentication failed" messages. For example "invalid base64
122
 
                  data". It must NOT be used to give exact reason for
123
 
                  authentication failure (i.e. "user not found" vs. "password
124
 
                  mismatch").
125
 
 - temp         : This is a temporary internal failure, e.g. connection was
126
 
                  lost to SQL database.
127
 
 - authz        : Authentication succeeded, but authorization failed (master
128
 
                  user's password was ok, but destnation user was not ok).
129
 
                  Added in Dovecot v1.2.
130
 
 
131
 
CONT command means that the authentication continues, and more data is
132
 
expected from client to finish the authentication. Given base64 data should
133
 
be sent to client.
134
 
 
135
 
FAIL and OK may contain multiple unspecified parameters which
136
 
authentication client may handle specially. The only one specified here is
137
 
"user=<userid>" parameter, which should always be sent if the userid is known.
138
 
 
139
 
 
140
 
Server <-> Master
141
 
-----------------
142
 
 
143
 
Master is a trusted process which may query results of previous client
144
 
authentication or information about a specific user. Master is optional and
145
 
in SMTP AUTH case it's not needed.
146
 
 
147
 
The connection starts by both server and master sending handshakes:
148
 
 
149
 
 S: "VERSION" TAB <major> TAB <minor>
150
 
 S: "SPID" TAB <pid>
151
 
 
152
 
 M: "VERSION" TAB <major> TAB <minor>
153
 
 
154
 
Auth with client <-> server, both should check that the version numbers are
155
 
valid.
156
 
 
157
 
SPID can be used to let master identify the server process.
158
 
 
159
 
 
160
 
Master Requests
161
 
---------------
162
 
 
163
 
 M: "REQUEST" TAB <id> TAB <client-pid> TAB <client-id> TAB <cookie>
164
 
 M: "USER" TAB <id> TAB <userid> TAB service=<service> [TAB <parameters>]
165
 
 
166
 
 S: "NOTFOUND" TAB <id>
167
 
 S: "FAIL" TAB <id> [TAB <parameters>]
168
 
 S: "USER" TAB <id> TAB <userid> [TAB <parameters>]
169
 
 
170
 
Master commands can request information about existing authentication
171
 
request, or about a specified user.
172
 
 
173
 
USER command's service and parameters are the same as with AUTH client
174
 
request.
175
 
 
176
 
ID is a connection-specific unique request identifier. It must be a 32bit
177
 
number, so typically you'd just increment it by one.
178
 
 
179
 
NOTFOUND reply means that the user wasn't found.
180
 
 
181
 
FAIL reply means an internal error occurred. Usually either a configuration
182
 
mistake or temporary error caused by lost resource (eg. database down).
183
 
Also unknown request IDs are reported as FAILs. Currently the only
184
 
specified parameter is "reason", which is used when user is wanted to be
185
 
put into "temporarily disabled" state and the reason string will be shown
186
 
to user on login or to LMTP RCPT TO reply.
187
 
 
188
 
USER reply is sent if request succeeded. It can return parameters:
189
 
 
190
 
 uid=<uid>          : System user ID.
191
 
 gid=<gid>          : System group ID.
192
 
 home=<dir>         : Home directory.
193
 
 chroot=<dir>       : Chroot directory.
194
 
 mail=<data>        : Mail location.
195
 
 system_user=<user> : System user name which can be used to get extra groups.
196
 
                      This will probably be replaced later by giving just
197
 
                      multiple gid fields.