Document how to use Dovecot Lua adapter

docs/installation/dovecot.md

@@ -0,0 +1,63 @@
+# Dovecot Authentication 
+
+Userli provides an API for `userdb` and `passdb` lookups.
+This can be used to authenticate users with Dovecot by using [Lua based authentication](https://doc.dovecot.org/2.3/configuration_manual/authentication/lua_based_authentication/).
+An adapter script is provided in the source code in `contrib/dovecot/userli.lua`.
+
+If the mailcrypt is enabled in Userli, the Lua adapter will also forward the required key material with each lookup.
+
+## On the Userli Host
+
+In `.env.local`, following environment variables needs to be configured:
+
+```shell
+DOVECOT_API_ENABLED=true
+DOVECOT_API_IP_ALLOWLIST="127.0.0.1, ::1"
+DOVECOT_API_ACCESS_TOKEN="replace-me-with-a-secure-token"
+```
+
+## On the Dovecot host
+
+### Prerequisites
+
+* `lua`
+* `json-lua`
+* `dovecot-auth-lua`
+
+### Example configuration
+
+`/etc/dovecot/conf.d/auth-lua.conf.ext`:
+
+```text
+import_environment=USERLI_API_ACCESS_TOKEN USERLI_HOST DOVECOT_LUA_DEBUG DOVECOT_LUA_INSECURE
+
+passdb {
+  driver = lua
+  args = file=/path/to/userli-adapter.lua blocking=yes
+}
+
+userdb {
+  driver = lua
+  args = file=/path/to/userli-adapter.lua blocking=yes
+}
+```
+
+Export the env vars to be picked up by Dovecots `import_environment` config:
+
+- `USERLI_API_ACCESS_TOKEN` (mandatory)
+- `USERLI_HOST` (mandatory)
+- `DOVECOT_LUA_AGENT`, defaults "Dovecot-Lua-Auth"
+- `DOVECOT_LUA_INSECURE`, to connect to the Userli host via unencrypted HTTP, defaults to `false`
+- `DOVECOT_LUA_DEBUG`, defaults to `false`
+- `DOVECOT_LUA_MAX_ATTEMPTS`, defaults to `3` 
+- `DOVECOT_LUA_TIMEOUT`, defaults to `10000`
+
+## MailCrypt
+
+In order to enable MailCrypt in Dovecot, the following is required:
+
+* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf`
+* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf`
+
+The latter disables MailCrypt per default and is necessary to not break incoming mail for legacy users without MailCrypt keys.
+The Lua adapter automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt keys.

docs/mail_crypt/index.md

@@ -3,8 +3,9 @@
 The software has builtin support for
 [Dovecot's mailbox encryption](https://wiki.dovecot.org/Plugins/MailCrypt), using the
 [global keys mode](https://wiki.dovecot.org/Plugins/MailCrypt#Global_keys).
-Keys are created and maintained by userli and handed over to Dovecot via
-`checkpassword` script.
+Keys are created and maintained by userli and handed over via an API and can
+be consumed by Dovecot by a Lua script. See [here](/installation/dovecot)
+for how to configure authentication and mailcrypt in Dovecot.
 
 The MailCrypt feature is enabled per default and can optionally be switched
 off globally by setting `MAIL_CRYPT=0` in the dotenv (`.env`) file.
@@ -20,16 +21,6 @@ have MailCrypt enabled per default, you can set `MAIL_CRYPT=1` in the dotenv
 * `MAIL_CRYPT=3` - Enforce MailCrypt key generation for all users, see the
                    documentation about migrating legacy users for more info
 
-In order to enable MailCrypt in Dovecot, the following is required:
-
-* Add `mail_crypt` to the `mail_plugins` list in `/etc/dovecot/conf.d/10-mail.conf`
-* Set `mail_crypt_save_version = 0` in `/etc/dovecot/conf.d/90-mail-crypt.conf`
-
-The latter disables MailCrypt per default and is necessary to not break
-incoming mail for legacy users without MailCrypt keys. The checkpassword script
-automatically sets `mail_crypt_save_version = 2` for all users with MailCrypt
-keys.
-
 MailCrypt can be turned on/off for individual users by setting the `mail_crypt`
 switch in the `virtual_users` database table. This switch is mainly meant to
 provide a migration path from legacy users without MailCrypt keys. On new

mkdocs.yml

@@ -13,11 +13,11 @@ nav:
       - Tests: development/tests.md
   - Installation:
       - Installation: installation/index.md
-      - Checkpassword: installation/checkpassword.md
       - Commands: installation/commands.md
       - Configuration: installation/configuration.md
       - Customize: installation/customize.md
       - Database: installation/database.md
+      - Dovecot: installation/dovecot.md
       - Finalize: installation/finalize.md
       - Webserver: installation/webserver.md
   - MailCrypt: