This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 4 and 22 (spanning 18 versions)
Revision 4 as of 2016-07-27 18:58:15
Size: 3754
Editor: 172
Comment:
Revision 22 as of 2019-04-20 08:35:28
Size: 7439
Editor: AkiTuomi
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
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.
Line 3: Line 4:
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 it's 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.
Line 6: Line 13:
Line 9: Line 15:
 * 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. (mandatory)
 * auth_policy_server_api_header - Header and value to add to request (for API authentcation)
 * auth_policy_server_timeout_msecs - Request timeout in milliseconds
 * auth_policy_hash_mech - Hash mechanism to use for password, you can use any hash mechanism supported by Dovecot (md4,md5,sha1,sha256,sha512)
 * auth_policy_hash_nonce - Cluster-wide nonce to add to hash (mandatory)
 * auth_policy_request_attributes - Request attributes specification (see attributes)
 * auth_policy_reject_on_fail - If policy request fails for some reason should users be rejected
 * auth_polich_hash_truncate - How many '''bits''' to use from password hash.
 * '''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}}}
Line 18: Line 42:
== Default values ==

 *
auth_policy_server_timeout_msecs = 2000
 * auth_policy_hash_mech = sha256
 * auth_policy_request_attributes = login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}
 *
auth_policy_reject_on_fail = no
 * auth_policy_hash_truncate = 12
==== Required Minimum Configuration ====
{{{
auth_policy_ser
ver_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
}}}
Line 27: Line 57:
Line 35: Line 64:
== 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:
Line 36: Line 67:
== 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:
Line 43: Line 71:
Line 49: Line 76:
Line 56: Line 82:
Line 59: Line 86:
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.
Line 61: Line 129:
Line 63: Line 130:
{"status":-1,"message":"go away"} {"status":-1,"msg":"go away"}
Line 65: Line 132:
{{{status}}} values: see below
Line 67: Line 135:
=== 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.
Line 68: Line 138:
Auth policy check is done twice during the authentication. 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. If the result here is negative, the user authentication is failed, if the result is positive, the user is tarpitted for as many seconds. The command used here is 'allow' and will appear on the URL as command=allow.
Line 70: Line 140:
Second allow lookup is done if authentication succeeds, and if the result here is negative, the authentication is failed. If the result is non-negative, the user authentication succeeds. {{{status}}} result values:
Line 72: Line 142:
Finally, a report lookup is done, and the result is ignored. Here the JSON request is added with two attributes, success and wf_reject. The first is true/false depending whether the overall authentication succeeded, and the second one is whether the failure was due to policy server.  * '''-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

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)

  • 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

None: Authentication/Policy (last edited 2022-02-04 23:22:47 by TimoSirainen)