From 4c86881c1ddebe3e75b41ec28fddbc19238c489e Mon Sep 17 00:00:00 2001
From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Fri, 13 Sep 2024 10:40:45 +0300
Subject: [PATCH] auth: Clarify how auth failure delay settings interact

---
 data/settings.js                 | 10 ++++++++--
 docs/core/config/auth/passdb.md  | 14 ++++++++++----
 docs/core/config/auth/penalty.md |  6 +++++-
 3 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/data/settings.js b/data/settings.js
index 84266e13a..c743ed099 100644
--- a/data/settings.js
+++ b/data/settings.js
@@ -2945,11 +2945,17 @@ and appending an \`@domain\` element to the username in cleartext logins.`
 		values: setting_types.TIME,
 		seealso: [ 'auth_internal_failure_delay' ],
 		text: `
-This is the delay before replying to failed authentication attempts.
+This is the delay before replying to failed authentication attempts. Using
+[[link,passdb_extra_field_nodelay]] bypasses this setting.
 
 This setting defines the interval for which the authentication process
 flushes all auth failures. Thus, this is the maximum interval a user may
-encounter.`
+encounter. However, there can be additional delays added by
+[[link,auth_penalty]].
+
+This setting doesn't affect internal failures. See
+[[setting,auth_internal_failure_delay]].
+`
 	},
 
 	auth_gssapi_hostname: {
diff --git a/docs/core/config/auth/passdb.md b/docs/core/config/auth/passdb.md
index 384f4fb82..18bfd7577 100644
--- a/docs/core/config/auth/passdb.md
+++ b/docs/core/config/auth/passdb.md
@@ -9,6 +9,9 @@ dovecotlinks:
   passdb_extra_fields:
     hash: extra-fields
     text: passdb extra fields
+  passdb_extra_field_nodelay:
+    hash: nodelay
+    text: passdb nodelay extra field
   passdb_user_extra_field:
     hash: user-extra-field
     text: passdb user extra field
@@ -508,11 +511,14 @@ The order of preference is: `proxy`, `host`, then `nologin`.
 
 #### `nodelay`
 
-Don't delay reply to client in case of an authentication failure.
+Don't delay reply to client in case of an authentication failure. However, this
+doesn't affect internal failure delays
+([[setting,auth_internal_failure_delay]]).
 
-If the authentication fails, Dovecot typically waits 0-2 seconds before
-sending back the "authentication failed" reply. If this field is set, no
-such delay is done.
+If the authentication fails, Dovecot typically waits 0-2 seconds
+([[setting,auth_failure_delay]]) before sending back the "authentication
+failed" reply. If this field is set, no such delay is done. Additionally,
+[[link,auth_penalty]] won't be increased.
 
 Commonly used with [[link,authentication_proxies]] and [[link,auth_referral]],
 but may also be used standalone.
diff --git a/docs/core/config/auth/penalty.md b/docs/core/config/auth/penalty.md
index 9b7cde9d2..71a7be1a8 100644
--- a/docs/core/config/auth/penalty.md
+++ b/docs/core/config/auth/penalty.md
@@ -8,7 +8,11 @@ dovecotlinks:
 # Authentication Penalty
 
 Dovecot anvil process tracks authentication penalties for different IPs
-to slow down brute force login attempts.
+to slow down brute force login attempts. The penalty is increased after failed
+logins until a maximum value, unless [[link,passdb_extra_field_nodelay]] is
+used. The penalty is applied for the IP before passdb lookups are done, so
+the delay might exist even with `nodelay` if it is not used for all
+authentication attempts for the IP.
 
 ## Algorithm