From 9dacef6c9a52f2b2edef32d70de2eb09135abe53 Mon Sep 17 00:00:00 2001
From: andryyy <andre.peters@debinux.de>
Date: Sat, 14 Nov 2020 19:18:04 +0100
Subject: [PATCH] Add info about FIDO2/WebAuthn

---
 docs/model-fido2.md | 15 +++++++++++++++
 mkdocs.yml          |  1 +
 2 files changed, 16 insertions(+)
 create mode 100644 docs/model-fido2.md

diff --git a/docs/model-fido2.md b/docs/model-fido2.md
new file mode 100644
index 000000000..49dc78fb8
--- /dev/null
+++ b/docs/model-fido2.md
@@ -0,0 +1,15 @@
+## How is UV handled in mailcow?
+
+The UV flag (as in "user verification") enforces WebAuthn to verify the user before it allows access to the key (think of a PIN). We don't enforce UV to allow logins via iOS and NFC (YubiKey).
+
+## Login and key processing
+
+mailcow uses **client-side key processing**. We ask the authenticator (i.e. YubiKey) to save the registration in its memory.
+
+A user does not need to enter a username. The available credentials - if any - will be shown to the user when selecting the "key login" via mailcow UI login.
+
+When calling the login process, the authenticator is not given any credential IDs. This will force it to lookup credentials in its own memory.
+
+## Who can use WebAuthn to login to mailcow?
+
+As of today, only administrators and domain administrators are able to setup WebAuthn/FIDO2.
diff --git a/mkdocs.yml b/mkdocs.yml
index 621031721..f3d977873 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,6 +44,7 @@ nav:
   - 'Sender and receiver model': 'model-sender_rcv.md'
   - 'ACL': 'model-acl.md'
   - 'Password hashing': 'model-passwd.md'
+  - 'WebAuthn / FIDO2': 'model-fido2.md'
 - 'Debugging & Troubleshooting':
     - 'Introduction': debug.md
     - 'Logs': 'debug-logs.md'