extend FIDO2 description

README.en.md

@@ -13,7 +13,8 @@ The key management is done in the admin area and in the user's "My Account".
 
 ## Table of content
 
-- [Installation](#installation)
+- [What is FIDO2?](#what-is-fido2)
+- [Module installation](#module-installation)
 - [Usage](#usage)
 - [Configuration](#configuration)
 - [Changelog](#changelog)
@@ -21,7 +22,36 @@ The key management is done in the admin area and in the user's "My Account".
 - [License](#license)
 - [Further licences and terms of use](#further-licences-and-terms-of-use)
 
-## Installation
+## What is FIDO2?
+
+It enables secure authentication of the user in web-based user interfaces via a browser. Instead of a password ("knowledge" factor), one logs in with special hardware that uses strong public key cryptography for verification ("ownership" factor). Due to the way it is implemented, FIDO2 logins cannot be intercepted by phishing. 
+
+FIDO2 describes the entire authentication process, WebAuthn and CTAP are subcomponents of this process. CTAP is the communication from the FIDO2 device to the client / browser. WebAuthn handles the transmission from the browser to the application (shop).
+
+Any FIDO2-certified hardware can be used for registration. This can be:
+
+- Cross-Platform Authenticators (device-independent):
+  - USB tokens (e.g. Solokey or YubiKey),
+  - NFC transmitters
+  - Bluetooth transmitters
+  - Smartcards
+- Platform Authenticators (device-dependent)
+  - Face ID devices
+  - Windows Hello devices
+- Hybrid authenticators
+  - Smartphones with Touch ID (Android from version 7, iOS from version 14),
+
+FIDO2 can be used as:
+- an additional 2nd factor to the existing username-password combination
+- as a secure substitute instead of a password (passwordless, still in connection with the entry of a user name)
+- as a complete substitute for user name and password (with login data stored in the FIDO2 device).
+
+In this module, passwordless login is currently implemented (2nd option). 
+For the 1st options we see too little security gain compared to option 2. The implementation of the 3rd option is technically feasible, but for the normal field of application not very relevant and technically complex. If required, we are available for enquiries.
+
+When registering a FIDO2 key, access data is created in order to be able to check a later login attempt. These access data are firmly bound to the customer account and the shop and cannot be exchanged with each other.
+
+## Module installation
 
 This package requires an Composer installed OXID eShop as defined in [composer.json](composer.json).
 
@@ -45,21 +75,24 @@ To use the registered FIDO2 keys, simply leave the password field blank when log
 
 The keys can be easily managed in the My Account area of the frontend and also in the customer account in the backend. The administration includes the registration of new keys (multiple keys per account are possible and recommended). A free text name can be assigned to each key. Furthermore, all registered keys are displayed with their names. Registered keys can also be deleted there.
 
-Any FIDO2-certified hardware can be used for registration. This can be:
-- USB tokens (e.g. Solokey or YubiKey), 
-- NFC transmitters
-- Bluetooth transmitter
-- Smartphones with Touch ID (Android from version 7, iOS from version 14),
-- smart cards
-- Face ID devices
-- Windows Hello devices
-
 Since a password is no longer required with a FIDO2-based login, the backup password can also be more complex than passwords suitable for everyday use.
 
 ## Configuration
 
 The FIDO2 accesses created are fixed to the respective shop and cannot be exchanged between different shops. The basis for the accesses is the current URL of the shop. If your shop is accessible under different URLs or moves to a new address, you can overwrite the default value in the module settings. This way, existing accesses do not become invalid with the change.
 
+Options used:
+
+- allows Platform and Cross-Platform Authenticators
+- does not define interface restrictions (USB, NFC, ...)
+- User verification recommended, but not required
+  - Not all browsers can e.g. request the PIN from Cross-Platform Authenticators, with User Verification these browsers are excluded from use
+- does not request attestation
+- no request for user data stored on the device
+- Timeout: 60 seconds
+
+All other options can be freely adapted to individual requirements by overloading.
+
 ## Changelog
 
 See [CHANGELOG](CHANGELOG.md) for further informations.

README.md

@@ -13,7 +13,8 @@ Die Schlüsselverwaltung erfolgt im Adminbereich sowie im "Mein Konto" des Benut
 
 ## Inhaltsverzeichnis
 
-- [Installation](#installation)
+- [Was ist FIDO2?](#was-ist-fido2)
+- [Modulinstallation](#modulinstallation)
 - [Verwendung](#verwendung)
 - [Konfiguration](#konfiguration)
 - [Changelog](#changelog)
@@ -21,7 +22,36 @@ Die Schlüsselverwaltung erfolgt im Adminbereich sowie im "Mein Konto" des Benut
 - [Lizenz](#lizenz)
 - [weitere Lizenzen und Nutzungsbedingungen](#weitere-lizenzen-und-nutzungsbedingungen)
 
-## Installation
+## Was ist FIDO2?
+
+Es ermöglicht die sichere Authentisierung des Benutzers in webbasierten Benutzeroberflächen über einen Browser. Statt eines Passworts (Faktor "Wissen") meldet man sich mit einer speziellen Hardware an, die zur Prüfung die starke Public Key cryptography verwendet (Faktor "Besitz"). FIDO2-Anmeldungen können durch die Art der Umsetzung nicht mit Phishing abgefangen werden. 
+
+FIDO2 beschreibt den gesamten Authentisierungsprozess, WebAuthn und CTAP sind Unterbestandteile dieses Prozesses. Bei CTAP handelt es sich um die Kommunikation vom FIDO2-Gerät zum Client / Browser. WebAuthn übernimmt die Übermittlung vom Browser zur Anwendung (Shop).
+
+Zur Anmeldung ist jede FIDO2-zertifizierte Hardware nutzbar. Das können sein:
+
+- Cross-Platform Authenticators (geräteunabhängig):
+  - USB-Tokens (z.B. Solokey oder YubiKey),
+  - NFC-Sender
+  - Bluetoothsender
+  - Smartcards
+- Platform Authenticators (geräteabhängig)
+  - Face ID Geräte
+  - Windows Hello Geräte
+- hybride Authenticators
+  - Smartphones mit Touch ID (Android ab Version 7, iOS ab Version 14),
+
+FIDO2 kann verwendet werden als:
+- ein zusätzlicher 2. Faktor zur bisherigen Benutzername-Passwort-Kombination
+- als sicherer Ersatz statt eines Passworts (passwortlos, noch in Verbindung mit der Eingabe eines Benutzernamens)
+- als kompletter Ersatz für Benutzernamen und Passwort (mit im FIDO2-Gerät abgelegten Anmeldedaten)
+
+In diesem Modul ist derzeit die passwortlose Anmeldung umgesetzt (2. Option). 
+Für die 1. Optionen sehen wir einen zu geringen Sicherheitsgewinn gegenüber Option 2. Die Umsetzung der 3. Option ist technisch machbar, jedoch für den normalen Einsatzbereich wenig relevant und technisch aufwändig. Bei Bedarf stehen wir gern für Anfragen zur Verfügung.
+
+Bei der Registrierung eines FIDO2-Keys werden Zugangsdaten erstellt, um einen späteren Anmeldeversuch prüfen zu können. Diese Zugangsdaten sind fest an das Kundenkonto und an den Shop gebunden und nicht untereinander austauschbar.
+
+## Modulinstallation
 
 Dieses Paket erfordert einen mit Composer installierten OXID eShop in einer in der [composer.json](composer.json) definierten Version.
 
@@ -45,21 +75,24 @@ Zur Verwendung der registrierten FIDO2-Keys wird bei der Anmeldung einfach das P
 
 Die Keys können einfach im Mein-Konto-Bereich des Frontends und auch im Kundenkonto im Backend verwaltet werden. Die Verwaltung umfasst das Registrieren neuer Keys (mehrfache Keys pro Konto sind möglich und empfohlen). Jedem Key kann ein Freitextname zugeordnet werden. Weiterhin werden alle registrierten Keys mit ihrem Namen dargestellt. Ebenso sind registrierte Keys dort löschbar.
 
-Zur Anmeldung ist jede FIDO2-zertifizierte Hardware nutzbar. Das können sein:
-- USB-Tokens (z.B. Solokey oder YubiKey), 
-- NFC-Sender
-- Bluetoothsender
-- Smartphones mit Touch ID (Android ab Version 7, iOS ab Version 14),
-- Smartcards
-- Face ID Geräte
-- Windows Hello Geräte
-
 Da bei einer FIDO2-basierten Anmeldung kein Passwort mehr benötigt wird, kann das Backupkennwort auch komplexer als alltagstaugliche Passworte sein.
 
 ## Konfiguration
 
 Die angelegten FIDO2-Zugänge sind auf den jeweiligen Shop festgeschrieben und können nicht zwischen unterschiedlichen Shops ausgetauscht werden. Basis für die Zugänge ist die aktuelle URL des Shops. Wenn Ihr Shop unter verschiedenen URLs erreichbar ist oder auf eine neue Adresse umzieht, können Sie die Vorgabe in den Moduleinstellungen überschreiben. So werden bestehende Zugänge mit dem Wechsel nicht ungültig.
 
+Weitere verwendete Optionen:
+
+- erlaubt Platform und Cross-Platform Authenticators
+- definiert keine Schnittstellen-Einschränkungen (USB, NFC, ...)
+- User Verification empfohlen, aber nicht erforderlich
+  - nicht alle Browser können z.B. die PIN bei Cross-Platform Authenticators anfordern, bei User Verification sind diese Browser von der Verwendung ausgeschlossen
+- fordert keine Attestation an
+- keine Abfrage von auf dem Gerät gespeicherter Benutzerdaten
+- Timeout: 60 Sekunden
+
+Alle weiteren Optionen sind durch Überladungen frei an individuelle Erfordernisse anpassbar.
+
 ## Changelog
 
 Siehe [CHANGELOG](CHANGELOG.md) für weitere Informationen.