1 files changed, 182 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.txt b/doc/wiki/PasswordDatabase.txt
new file mode 100644
index 0000000..f41a93e
--- /dev/null
+++ b/doc/wiki/PasswordDatabase.txt
@@ -0,0 +1,182 @@
+Password Databases
+==================
+
+Dovecot authenticates users against password databases. It can also be used to
+configure things like <proxies> [PasswordDatabase.ExtraFields.Proxy.txt].
+
+You can use multiple databases, so if the password doesn't match in the first
+database, Dovecot checks the next one. This can be useful if you want to easily
+support having both virtual users and also local system users (see
+<Authentication.MultipleDatabases.txt>).
+
+Success/failure databases
+-------------------------
+
+These databases simply verify if the given password is correct for the user.
+Dovecot doesn't get the correct password from the database, it only gets a
+"success" or a "failure" reply. This means that these databases can't be used
+with non-plaintext <authentication mechanisms> [Authentication.Mechanisms.txt].
+
+Databases that belong to this category are:
+
+ * <PAM> [PasswordDatabase.PAM.txt]: Pluggable Authentication Modules.
+ * <BSDAuth> [PasswordDatabase.BSDAuth.txt]: BSD authentication.
+ * <CheckPassword> [AuthDatabase.CheckPassword.txt]: External checkpassword
+   program without Dovecot extensions.
+ * <IMAP> [PasswordDatabase.IMAP.txt]: Authenticate against remote IMAP server.
+
+ * <OAuth2> [PasswordDatabase.oauth2.txt]: Authenticate against oauth2 provider
+   (v2.2.29+)
+
+Lookup databases
+----------------
+
+Dovecot does a lookup based on the username and possibly other information
+(e.g. IP address) and verifies the password validity itself. Fields that the
+lookup can return:
+
+ * * <password> [Authentication.PasswordSchemes.txt]*: User's password.
+    * *password_noscheme*: Like "password", but if a password begins with "{",
+      assume it belongs to the password itself instead of treating it as a
+      <scheme> [Authentication.PasswordSchemes.txt] prefix. This is usually
+      needed only if you use plaintext passwords.
+ * * <user> [PasswordDatabase.ExtraFields.User.txt]*: Returning a user field
+   can be used to change the username. Typically used only for case changes
+   (e.g. "UseR" -> "user").
+    * *username*: Like user, but doesn't drop existing domain name (e.g.
+      "username=foo" for "user@domain" gives "foo@domain").
+    * *domain*: Updates the domain part of the username.
+ * Other special <extra fields> [PasswordDatabase.ExtraFields.txt].
+
+Databases that support looking up only passwords, but no user or extra fields:
+
+ * <Passwd> [AuthDatabase.Passwd.txt]: System users (NSS, '/etc/passwd', or
+   similiar).
+ * <Shadow> [PasswordDatabase.Shadow.txt]: Shadow passwords for system users
+   (NSS,'/etc/shadow' or similiar).
+    * Dovecot supports reading all <password schemes>
+      [Authentication.PasswordSchemes.txt] from passwd and shadow databases (if
+      prefix is specified), but that is of course incompatible with all other
+      tools using/modifying the passwords.
+ * <VPopMail> [AuthDatabase.VPopMail.txt]: External software used to handle
+   virtual domains.
+
+Databases that support looking up everything:
+
+ * <Passwd-file> [AuthDatabase.PasswdFile.txt]: '/etc/passwd'-like file in
+   specified location.
+ * <LDAP> [AuthDatabase.LDAP.txt]: Lightweight Directory Access Protocol.
+ * <SQL> [AuthDatabase.SQL.txt]: SQL database (PostgreSQL, MySQL, SQLite).
+ * <Dict> [AuthDatabase.Dict.txt]: Dict key-value database (Redis, memcached,
+   etc.)
+ * <CheckPassword> [AuthDatabase.CheckPassword.txt]: External checkpassword
+   program when used with Dovecot extensions.
+ * <Static> [PasswordDatabase.Static.txt]: Static passdb for simple
+   configurations
+ * <Lua> [AuthDatabase.Lua.txt]: Lua script for authentication (v2.3.0+)
+
+Passdb settings
+---------------
+
+An example passdb passwd-file with its default settings:
+
+---%<-------------------------------------------------------------------------
+passdb {
+  driver = passwd-file
+  args = scheme=ssha256 /usr/local/etc/passwd.replica
+  default_fields =
+  override_fields =
+
+  deny = no
+  master = no
+  pass = no
+  skip = never
+  mechanisms =
+  username_filter =
+
+  result_failure = continue
+  result_internalfail = continue
+  result_success = return-ok
+
+  # v2.2.24+
+  auth_verbose = default
+}
+---%<-------------------------------------------------------------------------
+
+First we have the settings that provide content for the passdb lookup:
+
+ * driver: The passdb backend name
+ * args: Arguments for the passdb backend. The format of this value depends on
+   the passdb driver. Each one uses different args.
+ * default_fields: Passdb fields (and <extra fields>
+   [PasswordDatabase.ExtraFields.txt]) that are used, unless overwritten by the
+   passdb backend. They are in format 'key=value key2=value2 ...'. The values
+   can contain <%variables> [Variables.txt].
+ * override_fields: Same as default_fields, but instead of providing the
+   default values, these values override what the passdb backend returned.
+ * auth_verbose: If this is explicitly set to yes or no, it overrides the
+   global auth_verbose setting. (However, auth_debug=yes overrides the
+   auth_verbose setting.) (v2.2.24+)
+
+Then we have the settings which specify when the passdb is used:
+
+ * deny: If "yes", used to provide "denied users database". If the user is
+   found from the passdb, the authentication will fail.
+ * master: If "yes", used to provide <master users database>
+   [Authentication.MasterUsers.txt]. The users listed in the master passdb can
+   log in as other users.
+    * pass: This is an alias for 'result_success = continue' as described
+      below. This was commonly used together with master passdb to specify that
+      even after a successful master user authentication, the authentication
+      should continue to the actual non-master passdb to lookup the user.
+ * skip: Do we sometimes want to skip over this passdb?
+    * never
+    * authenticated: Skip if an earlier passdb already authenticated the user
+      successfully.
+    * unauthenticated: Skip if user hasn't yet been successfully authenticated
+      by the previous passdbs.
+ * mechanisms: Skip, if non-empty and the current auth mechanism is not listed
+   here. Space or comma-separated list of auth mechanisms (e.g. "PLAIN LOGIN").
+   Also "none" can be used to match for a non-authenticating passdb lookup.
+   (v2.2.30+)
+ * username_filter: Skip, if non-empty and the username doesn't match the
+   filter. This is mainly used to assign specific passdbs to specific domains.
+   Space or comma-separated list of username filters that can have "*" or "?"
+   wildcards. If any of the filters matches, the filter succeeds. However,
+   there can also be negative matches preceded by "!". If any of the negative
+   filters matches, the filter won't succeed. For example if the filter is
+   "*@example.com *@example2.com !user@example.com", "any@example.com" or
+   "user@example2.com" matches but "user@example.com" won't match. (v2.2.30+)
+
+And finally we can control what happens when we're finished with this passdb:
+
+ * result_success: What to do if the authentication succeeded (default:
+   return-ok)
+ * result_failure: What to do if authentication failed (default: continue)
+ * result_internalfail: What to do if the passdb lookup had an internal failure
+   (default: continue). If any of the passdbs had an internal failure and the
+   final passdb also returns "continue", the authentication will fail with
+   "internal error".*WARNING*: If multiple passdbs are required (results are
+   merged), it's important to set result_internalfail=return-fail to them,
+   otherwise the authentication could still succeed but not all the intended
+   extra fields are set.
+
+The result values that can be used:
+
+ * return-ok: Return success, don't continue to the next passdb.
+ * return-fail: Return failure, don't continue to the next passdb.
+ * return: Return earlier passdb's success or failure, don't continue to the
+   next passdb. If this was the first passdb, return failure.
+ * continue-ok: Set the current authentication state to success, and continue
+   to the next passdb. The following passdbs will skip password verification.
+ * continue-fail: Set the current authentication state to failure, and continue
+   to the next passdb. The following passdbs will still verify the password.
+ * continue: Continue to the next passdb without changing the authentication
+   state. The initial state is failure. If this was set in result_success, the
+   following passdbs will skip password verification.
+
+*NOTICE*: when using "continue*" values on a *master* passdb (master = yes),
+execution will jump to the first *non-master* passdb instead of continuing with
+the next master passdb (verified at lest up to v2.2.27).
+
+(This file was created from the wiki on 2019-06-19 12:42)