1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
Authentication policy support
=============================
Dovecot supports (v2.2.25+) external authentication policy server. This server
can be used to decide whether the connecting user is permitted, tarpitted or
outright rejected. While dovecot can do tarpitting and refusal on its own, this
adds support for making cluster-wide decisions to make it easier to deter and
defeat bruteforce attacks.
Known issues
------------
Prior v2.2.27 request policy was mostly broken.
Prior v2.2.34, the request attributes contained *orig_username* which was not
correct in all cases, especially with master login.
Prior v2.3.5.2 / 2.2.36.3, invalid UTF-8 would crash auth server if auth policy
is used.
Configuration
-------------
The auth-policy server is a core feature and does not require plugin(s) to
work. To activate this feature, you need to configure it.
* *auth_policy_server_url*: URL of the policy server, url is appended with
?command=allow/report unless it ends with '&', at which just
command=allow/report is added.
* /Default/: None (*REQUIRED* configuration)
* Example: 'auth_policy_server_url = http://example.com:4001/'
* *auth_policy_server_api_header*: Header and value to add to request (for API
authentication)
* /Default/: None (No authentication is done)
* See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
* Example: 'Authorization: Basic <base64-encoded value>'
* *auth_policy_server_timeout_msecs*: Request timeout in milliseconds
* /Default/: 'auth_policy_server_timeout_msecs = 2000'
* *auth_policy_hash_mech*: Hash mechanism to use for password, you can use any
hash mechanism supported by Dovecot (md4,md5,sha1,sha256,sha512)
* /Default/: 'auth_policy_hash_mech = sha256'
* *auth_policy_hash_nonce*: Cluster-wide nonce to add to hash
* /Default/: None (*REQUIRED* configuration)
* Example: 'auth_policy_hash_nonce = localized_random_string'
* *auth_policy_request_attributes*: Request attributes specification (see
attributes section below)
* /Default/: 'auth_policy_request_attributes = login=%{requested_username}
pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id}
protocol=%s'
* *auth_policy_reject_on_fail*: If policy request fails for some reason should
users be rejected
* /Default/: 'auth_policy_reject_on_fail = no'
* *auth_policy_hash_truncate*: How many *bits* to use from password hash.
* /Default/: 'auth_policy_hash_truncate = 12'
* *auth_policy_check_before_auth*: Whether to do policy lookup before
authentication is started
* /Default/: 'auth_policy_check_before_auth = yes'
* *auth_policy_check_after_auth*: Whether to do policy lookup after
authentication is completed
* /Default/: 'auth_policy_check_after_auth = yes'
* *auth_policy_report_after_auth*: Whether to report authentication result
* /Default/: 'auth_policy_report_after_auth = yes'
Required Minimum Configuration
------------------------------
---%<-------------------------------------------------------------------------
auth_policy_server_url = http://example.com:4001/
auth_policy_hash_nonce = localized_random_string
#auth_policy_server_api_header = Authorization: Basic <base64-encoded value>
#auth_policy_server_timeout_msecs = 2000
#auth_policy_hash_mech = sha256
#auth_policy_request_attributes = login=%{requested_username}
pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id} protocol=%s
#auth_policy_reject_on_fail = no
#auth_policy_hash_truncate = 12
#auth_policy_check_before_auth = yes
#auth_policy_check_after_auth = yes
#auth_policy_report_after_auth = yes
---%<-------------------------------------------------------------------------
Password hash algorithm
-----------------------
To generate the hash, you concatenate nonce, login name, nil byte, password and
run it through the hash algorithm once. The hash is truncated when truncation
is set to non-zero. The hash is truncated by first choosing bits from MSB to
byte boundary (rounding up), then right-shifting the remainding bits.
---%<-------------------------------------------------------------------------
hash = H(nonce||user||'\x00'||password)
bytes = round8(bits*8)
hash = HEX(hash[0:bytes] >> (bytes-bits*8))
---%<-------------------------------------------------------------------------
Request attributes
------------------
Auth policy server requests are JSON requests. The JSON format can be specified
with auth_policy_request_attributes. The syntax is key=value pairs, and key can
contain one or more / to designate that a JSON object should be made. For
example:
---%<-------------------------------------------------------------------------
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
---%<-------------------------------------------------------------------------
produces
---%<-------------------------------------------------------------------------
{"login":"john.doe","pwhash":"1234","remote":"127.0.0.1"}
---%<-------------------------------------------------------------------------
And
---%<-------------------------------------------------------------------------
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
attrs/cos=%{userdb:cos}
---%<-------------------------------------------------------------------------
produces
---%<-------------------------------------------------------------------------
{"login":"john.doe","pwhash":"1234","remote":"127.0.0.1",
"attrs":{"cos":"premium"}}
---%<-------------------------------------------------------------------------
Since v2.2.29/v2.3 you can include IMAP ID command result in auth policy
requests, this is achieved with using %{client_id}, which will expand to IMAP
ID command arglist. You must set
---%<-------------------------------------------------------------------------
imap_id_retain=yes
---%<-------------------------------------------------------------------------
for this to work.
Default values for auth_policy_request_attributes
-------------------------------------------------
Since v2.2.25
---%<-------------------------------------------------------------------------
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
---%<-------------------------------------------------------------------------
Since v2.2.30
---%<-------------------------------------------------------------------------
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
device_id=%{client_id} protocol=%s
---%<-------------------------------------------------------------------------
Since v2.2.34
---%<-------------------------------------------------------------------------
login=%{requested_username} pwhash=%{hashed_password} remote=%{rip}
device_id=%{client_id} protocol=%s
---%<-------------------------------------------------------------------------
Since v2.3.0 (note that 2.2 and 2.3 branches have been developed in parallel
for a while)
---%<-------------------------------------------------------------------------
login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
device_id=%{client_id} protocol=%s
---%<-------------------------------------------------------------------------
Since v2.3.1
---%<-------------------------------------------------------------------------
login=%{requested_username} pwhash=%{hashed_password} remote=%{rip}
device_id=%{client_id} protocol=%s
---%<-------------------------------------------------------------------------
Since v2.3.2 the request contains 'tls' attribute when TLS has been used. TLS
is also detected if it's offloaded by a load balancer that can provide this
information using HAProxy v2 protocol to dovecot.
Response
--------
---%<-------------------------------------------------------------------------
{"status":-1,"msg":"go away"}
---%<-------------------------------------------------------------------------
'status' values: see below
Mode of operation
-----------------
Auth policy check: Authentication ''before'' userdb/passdb
----------------------------------------------------------
First query is done *before* password and user databases are consulted. This
means that any userdb/passdb attributes are left empty.
The command used here is 'allow' and will appear on the URL as command=allow.
'status' result values:
* *-1*: Reject
* *0*: Accept
* *(Any other positive value)*: Tarpit for this number of seconds.
Auth policy check: Authentication ''after'' successful userdb/passdb lookup
---------------------------------------------------------------------------
Second lookup is done *after* authentication succeeds.
The command used here is 'allow' and will appear on the URL as command=allow.
'status' result values:
* *-1*: Authentication fail
* *>= 0*: Authentication succeed
Auth policy check: Reporting after authentication succeeds
----------------------------------------------------------
A report request is sent at end of authentication.
The command used here is 'report' and will appear on the URL as command=report.
The JSON request is sent with two additional attributes:
* *success*: boolean true/false depending on whether the overall
authentication succeeded
* *policy_reject*: boolean true/false whether the failure was due to policy
server
'status' result value is ignored.
External Auth Policy Servers
----------------------------
* http://oxpedia.org/wiki/index.php?title=AppSuite:Dovecot_Antiabuse_Shield
(This file was created from the wiki on 2019-06-19 12:42)
|
