Technische Referenz

Nachschlagewerk zu wkidentity: der öffentliche Vertrag, die Einstiege der Einmalcode-Abläufe, die Ablage auf dem Datenträger, jede Einstellung und jede Klasse. Warum die Dinge so gebaut sind, steht in den Konzepten; was Sie tun wollen, auf Identity.

Paket: wkidentity · Fassung: 1.0.0 · Ablage: lib/plugins/wkidentity/
Art: Action- und Helper-Plugin — kein authtype, kein syntax-Tag
Autor: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs) · Lizenz: GPL 2

Der öffentliche Vertrag, über den ein anderes Plugin die aktuelle Sitzung liest und eine höhere Absicherung anfordern kann, ohne selbst TOTP oder Email-Einmalcodes zu implementieren. Diese Seite ist die deutsche Kurzfassung für Betreiber; die verbindliche, vollständige Spezifikation (API, Assurance, Faktoren, Lifecycle, Workbench-Integration, Fehlerverhalten, Beispiel) steht im Repository: lib/plugins/wkidentity/docs/contract-v1.md.

Warum es diesen Vertrag gibt: Vor ihm hatte wkidentity keine einzige öffentliche Methode — eine Volltextsuche über jedes andere installierte Plugin ergibt null echte Aufrufe. Der Fluent-UI-Workbench-Vertrag (siehe Workbench Plugin Contract v1) hatte bereits ein Deskriptorfeld (requiresIdentity) reserviert und ausdrücklich benannt, dass echte Durchsetzung bei wkidentitys eigenen Kern-Hooks bleibt — aber nichts stand bereit, das einzulösen.

helper_plugin_wkidentity_contract (plugin_load('helper', 'wkidentity_contract')):

Keine öffentliche Methode gibt ein TOTP-Secret heraus, erzeugt einen Email-Code oder verifiziert einen Faktor. Diese Primitiven bleiben genau da, wo sie schon waren — auf helper_plugin_wkidentity, nur von innerhalb dieses Plugins aufgerufen.

Ohne jede Änderung an wkfluentui. Jener Vertrag hat bereits ein Deskriptorfeld permission (ein Callable, additiv zur ACL, fail-closed), das ein Beitrag genau für diesen Fall setzen kann:

'permission' => function () {
    $identity = plugin_load('helper', 'wkidentity_contract');
    return $identity !== null && $identity->satisfies('MFA_ANY');
},

Für einen Befehl, der beim tatsächlichen Ausführen einen Step-up verlangen soll (nicht nur beim Anzeigen ausgeblendet werden soll), ruft die Befehls-Handhabung selbst require() auf. wkfluentuis requiresIdentity-Feld bleibt genau das, was es schon dokumentiert war — beratend, ohne Verbraucher — und wird durch diesen Vertrag nicht ersetzt, sondern eingelöst.

supports($name) — fünf feste Zeichenketten: identity.authentication, identity.stepup, identity.factor.totp, identity.factor.mailOtp, identity.assurance.anyMfa. Alle fünf sind mit dieser Fassung wahr.

Die beiden Kern-Aktionen werden übernommen, nicht ersetzt — vorhandene Lesezeichen, alte E-Mails und die Links auf der Anmeldekarte zeigen alle dorthin, und wer auf dem alten Formular landet und das alte Verhalten vorfindet, hat zwei Systeme zu verstehen statt eines:

Ein Ticket im Link ist optional. Wer den Code hat, aber die E-Mail nie ankam, kann ihn über seinen Anmeldenamen einlösen — sonst hielte er einen Code ohne Formular, in das er gehört.

recovery_factor entscheidet, welchen Nachweis ein Zurücksetzen annimmt — und die drei Werte sind keine drei Punkte auf einer Skala. Zwei sind Richtlinie, einer ist eine Messung:

Zwei Feinheiten, die aus der Bauform folgen und sonst wie Fehler aussehen:

• auto fällt bei einem Konto ohne Authentifikator auf E-Mail zurück, auch wenn der Port messbar zu ist. Die Messung ist eine Vorhersage, keine Quittung: sie kann veraltet sein, sie sieht keinen lokalen Mailserver, und die Reparatur — eine andere Leitung — ist sofort wirksam und von hier aus unsichtbar. Einen Versuch zu unterlassen kostet den einzigen Weg, den dieses Konto hatte; ihn zu unternehmen kostet eine Zeitüberschreitung.
• „Nicht ermittelbar“ heißt Erlaubnis, nie Verweigerung. auto braucht wkmail mit SMTP-Transport; ohne das gibt es nichts zu messen und der Wert verhält sich wie mail. Verfügbarkeitsfragen scheitern nach oben offen, sonst verlöre jede nicht messbare Installation einen Weg, den sie problemlos benutzt hat.

min_password_length (Vorgabe 14) wird serverseitig geprüft. Eine Regel, die nur im Hinweis unter dem Feld steht, ist ein Vorschlag — und das Feld ist nicht der Ort, an dem ein Angreifer tippt. Das Kennwort wird zudem vor dem Code geprüft: wer sich beim neuen Kennwort zweimal vertippt, soll dafür nicht einen Code verbrauchen und auf den nächsten warten müssen.

Abgelaufene Vorgänge räumt INDEXER_TASKS_RUN ab — derselbe Wartungslauf, den DokuWiki ohnehin anstößt. Kein eigener Zeitplan, kein Dienst.

Es gibt keine SQLite-/DB-Anbindung. Genau eine Datei pro Nutzer:

data/meta/wkidentity/<login>.secret

• Inhalt: ein kleiner JSON-Umschlag — seit der Sicherheits-Härtung {"v":2,"factors":{"totp"?:{"secret":"BASE32..."},"email"?:{}}}, wobei beide Schlüssel gleichzeitig vorhanden sein können — als Ganzes AES-verschlüsselt mit Cores eigenem auth_encrypt()/auth_decrypt() (inc/auth.php), demselben Mechanismus, den Core für das „Angemeldet bleiben“-Cookie nutzt. Zwei ältere Formen werden weiterhin gelesen, nie geschrieben: ein unversioniertes {"method":"totp"|"email",...}-Format, und — vor jeder JSON-Form — ein blankes Base32-Secret.
• Schlüsselableitung: hash_hmac('sha256', 'wkidentity-secret-at-rest-v1', auth_cookiesalt()) — derselbe Installations-Cookie-Salt wie beim Core-Cookie, aber mit fixem Kontext-Label, sodass niemals dasselbe Schlüsselmaterial wie das Cookie-Feature verwendet wird.
• isEnrolled() prüft, ob der entschlüsselte Umschlag mindestens einen Faktor enthält — kein Index, kein Cache, keine Registry-Datei.
• Das Pending-TOTP-Secret während der Bestätigung liegt ausschließlich in der PHP-Session (Konzepte: Workflow (Enrollment)), nie in dieser Datei. Der Email-Bestätigungscode liegt gesalzen gehasht (password_hash() seit der Sicherheits-Härtung, zuvor ungesalzenes SHA-256 — siehe docs/threat-model.md, Befund F2) in einer eigenen, kurzlebigen Datei data/meta/wkidentity/<login>.emailcode.
• Neu seit der Sicherheits-Härtung: data/meta/wkidentity/<login>.totpreplay — eine winzige Datei, die nur den zuletzt akzeptierten HOTP-Zähler für dieses Login hält, damit ein einmal verwendeter TOTP-Code nicht innerhalb seines Toleranzfensters ein zweites Mal angenommen wird (Befund F1). Kein Geheimnis, nur eine Zahl.
• Admin-Policy (welche Benutzer/Gruppen/Namensräume/Befehle einen zweiten Faktor bzw. welche Absicherungsstufe verlangen) liegt getrennt davon in conf/wkidentity-policy.json (siehe Admin-Panel unten) — keine Vermischung von Enrollment-Daten und Durchsetzungs-Regeln.
• Offene Einmalcode-Vorgänge liegen wiederum getrennt unter data/meta/wkidentity/otp/, eine Datei je Vorgang. Der Code selbst steht dort nie im Klartext, nur sein Hash — die Datei beantwortet also „gab es einen Vorgang, wie oft wurde gesendet, wie viele Versuche sind übrig, wann läuft er ab„, aber nie „wie lautet der Code“.

Das Paket bringt zwei Verwaltungsbildschirme mit, beide nur für den Superuser:

Fluent-Tab-Muster wie wvdsentra (ARIA-Tablist, ohne JavaScript bleiben alle Panels sichtbar):

Persistenz getrennt vom DokuWiki-Konfigurationsmanager in conf/wkidentity-policy.json (PolicyStore.php, 1:1-Muster nach wvdsentra/MappingStore.php: .bak-Backup vor jedem Überschreiben, robuste Normalisierung).

Aufruf: do=admin&page=wkidentity_invites. Der Bildschirm ist um eine Grenze herum gebaut: der Code lässt sich nicht nachschlagen. Er steht nur gehasht in der Ablage, und das ist die Eigenschaft, die den ganzen Ablauf trägt. Also beantwortet der Bildschirm alle übrigen Fragen, die ein Support-Anruf stellt — wurde ein Vorgang eröffnet, an welche Adresse, wie oft wurde gesendet, wann läuft der aktuelle Code ab, wie viele Versuche sind übrig, wann schließt der Vorgang.

Dieselben Handgriffe gibt es auf der Kommandozeile (php bin/plugin.php wkidentity <befehl>), für den Fall, dass die E-Mail niemanden erreicht: list, code, invite, cancel, purge.

Admin → Konfigurationseinstellungen ($conf['plugin']['wkidentity'][…]). 19 Einstellungen in drei Gruppen (seit der Sicherheits-Härtung: plus assurance_ttl).

Ausführliche Begründung im Abschnitt „Einmalcode-Abläufe„ oben — hier nur Werte und Wirkung.

Kein Wert dieser Gruppe führt zu einem Abbruch:

• recovery_factor — jeder nicht erkannte Wert wird wie mail behandelt. Eine unlesbare Einstellung darf nicht ändern, wie Menschen sich wiederherstellen, und mail ist, was sie vorher hatten.
• digits wird auf 6–8 geklemmt, period auf 5–300, window auf 0–10; außerhalb liegende Werte fallen auf 6 / 30 / 1 zurück.

Datei: lib/plugins/wkidentity/action.php

Datei: lib/plugins/wkidentity/helper.php

Datei: lib/plugins/wkidentity/PolicyStore.php (Namespace dokuwiki\plugin\wkidentity)

Datei: lib/plugins/wkidentity/action/otpflows.php

Besitzt die Aktion wkidentity_otp und übernimmt die beiden Kern-Einstiege.

Datei: lib/plugins/wkidentity/helper/otpflows.php

Datei: lib/plugins/wkidentity/Domain/OtpStore.php (Namespace dokuwiki\plugin\wkidentity\Domain)

Die Ablage der Vorgänge, ohne jede DokuWiki-Kenntnis — die Prüfung eines Authentifikator-Codes wird ihr als Rückruf hereingereicht, statt dass sie ihn selbst holt.

Der Rückruf zur Code-Prüfung kennt drei Antworten, nicht zwei: stimmt, stimmt nicht (kostet einen Versuch — das ist es, was Raten begrenzt) und nicht feststellbar (kostet nichts, weil es unser Fehler ist und nicht der des Besuchers). Fielen die letzten beiden zusammen, könnte ein defekter Authentifikator-Zweig in fünf Anfragen das ganze Budget eines Menschen verbrennen und ihn aus einer Wiederherstellung aussperren, die er nie versuchen durfte.

Datei: lib/plugins/wkidentity/LoginGate.php (Namespace dokuwiki\plugin\wkidentity)

Datei: lib/plugins/wkidentity/helper/contract.php

Die öffentliche Fassade des Identity Plugin Contract v1 — siehe Abschnitt oben und docs/contract-v1.md.

Datei: lib/plugins/wkidentity/StepUp.php (Namensraum dokuwiki\plugin\wkidentity)

• Identity — Einstieg und häufige Aufgaben
• Konzepte — Assurance, Richtlinien-Engine, Abläufe, Sicherheit
• API-Referenz — die Vertragsmethoden, gespiegelt aus dem Repositorium
• Fehlerdiagnose
• Zwei-Faktor-Authentifizierung — die laienverständliche Endnutzer-Anleitung
• Workbench Plugin Contract v1 — dessen permission-Feld dieser Vertrag nutzt
• wkmail — der Postversand, über den Einmalcodes zugestellt werden