Tehnična referenca

Priročnik za wkidentity: javna pogodba, vstopne točke postopkov z enkratno kodo, shranjevanje na disku, vse nastavitve in vsi razredi. Zakaj so stvari zgrajene tako, kot so, pojasnjujejo Koncepti; kaj želite narediti, najdete na strani Identity.

Paket: wkidentity · Različica: 1.0.0 · Mesto: lib/plugins/wkidentity/
Vrsta: vtičnik action in helper – brez authtype, brez oznake syntax
Avtor: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs) · Licenca: GPL 2

Javna pogodba, prek katere drug vtičnik prebere trenutno sejo in lahko zahteva višje zagotovilo, ne da bi sam izvajal TOTP ali enkratne kode po e-pošti. Ta stran je povzetek za upravljavce; zavezujoča in popolna specifikacija (API, zagotovilo, dejavniki, življenjski cikel, povezava z delovno površino, vedenje ob napakah, primer) je v repozitoriju: lib/plugins/wkidentity/docs/contract-v1.md.

Zakaj ta pogodba obstaja: pred njo wkidentity ni imel niti ene javne metode – iskanje po celotnem besedilu vseh drugih nameščenih vtičnikov ne najde nobene dejanske uporabe. Pogodba delovne površine Fluent UI (glejte Workbench Plugin Contract v1, v nemščini) je že rezervirala polje deskriptorja (requiresIdentity) in izrecno določila, da pravo uveljavljanje ostane pri lastnih jedrnih kljukah paketa wkidentity – ničesar pa ni bilo, kar bi to obljubo izpolnilo.

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

Nobena javna metoda ne izda skrivnosti TOTP, ne ustvari kode za e-pošto in ne preveri dejavnika. Ti osnovni gradniki ostanejo natanko tam, kjer so bili – v helper_plugin_wkidentity, ki ga uporablja samo ta vtičnik. Vtičnik, ki pogodbo uporablja, do skrivnosti in kod zato nima dostopa.

Brez kakršne koli spremembe v wkfluentui. Ta pogodba že ima polje deskriptorja permission (funkcija, ki velja dodatno k ACL in ob napaki dostop zavrne – fail-closed), ki ga prispevek lahko nastavi prav za ta primer:

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

Za ukaz, ki naj ob dejanski izvedbi zahteva dodatno preverjanje (in naj ne bo samo skrit, ko se prikazuje), obdelava ukaza sama pokliče require(). Polje requiresIdentity v wkfluentui ostane natanko to, kar je bilo že dokumentirano: svetovalno in brez porabnika. Ta pogodba ga ne nadomesti, temveč izpolni.

supports($name) – pet stalnih nizov: identity.authentication, identity.stepup, identity.factor.totp, identity.factor.mailOtp, identity.assurance.anyMfa. V tej različici vseh pet vrne pritrdilen odgovor.

Obe jedrni dejanji sta prevzeti, ne nadomeščeni – obstoječi zaznamki, stara e-poštna sporočila in povezave na prijavni kartici kažejo tja, in uporabnik, ki pristane na starem obrazcu in naleti na staro vedenje, mora razumeti dva sistema namesto enega:

ID postopka (ticket) v povezavi je neobvezen. Uporabnik, ki ima kodo, e-poštno sporočilo pa ni nikoli prispelo (na primer kodo, ki mu jo je predal skrbnik), jo lahko vnovči s svojim prijavnim imenom – sicer bi imel kodo brez obrazca, v katerega sodi.

recovery_factor določa, kateri dokaz sprejme ponastavitev – in tri vrednosti niso tri točke na isti lestvici. Dve sta pravilnik, ena je meritev:

Dve podrobnosti, ki izhajata iz zasnove in sta sicer videti kot napaki:

• auto se pri računu brez aplikacije za preverjanje vrne k e-pošti, tudi če so vrata SMTP merljivo zaprta. Meritev je napoved, ne potrdilo: lahko je zastarela, krajevnega poštnega strežnika ne vidi, popravilo – druga povezava – pa učinkuje takoj in je od tu nevidno. Če poskusa ne bi bilo, bi račun izgubil edino pot, ki jo je imel; poskus stane kvečjemu prekoračitev časa.
• »Ni mogoče ugotoviti« pomeni »dovoljeno«, nikoli »zavrnjeno«. auto potrebuje wkmail s prenosom SMTP; brez tega ni česa meriti in vrednost se vede kot mail. Pri vprašanjih razpoložljivosti negotov rezultat pomeni »na voljo« (fail open), sicer bi vsaka namestitev, ki je ni mogoče izmeriti, izgubila pot, ki jo je doslej brez težav uporabljala.

min_password_length (privzeto 14) se preverja na strežniku. Pravilo, ki je zapisano samo v namigu pod poljem, je predlog – in polje ni mesto, kjer tipka napadalec. Geslo se poleg tega preveri pred kodo: če se uporabnik pri vnosu novega gesla zatipka, zaradi tega ne porabi kode in mu ni treba čakati na novo.

Potekle postopke odstrani INDEXER_TASKS_RUN – isti vzdrževalni zagon, ki ga DokuWiki tako ali tako sproži. Brez lastnega urnika, brez storitve.

Povezave s SQLite ali drugo zbirko podatkov ni. Natanko ena datoteka na uporabnika:

data/meta/wkidentity/<prijavno-ime>.secret

• Vsebina: majhna ovojnica JSON – od utrditve varnosti {"v":2,"factors":{"totp"?:{"secret":"BASE32..."},"email"?:{}}}, pri čemer sta lahko hkrati prisotna oba ključa – kot celota šifrirana z AES z jedrnima funkcijama auth_encrypt()/auth_decrypt() (inc/auth.php), istim mehanizmom, ki ga jedro uporablja za piškotek »Zapomni si me«. Dve starejši obliki se še naprej bereta, nikoli pa ne zapisujeta: oblika brez različice {"method":"totp"|"email",...} in – pred vsako obliko JSON – gola skrivnost Base32.
• Izpeljava ključa: hash_hmac('sha256', 'wkidentity-secret-at-rest-v1', auth_cookiesalt()) – ista namestitvena sol piškotkov kot pri jedrnem piškotku, vendar s stalno oznako konteksta, tako da se nikoli ne uporabi isto ključno gradivo kot pri piškotku.
• isEnrolled() preveri, ali dešifrirana ovojnica vsebuje vsaj en dejavnik – brez indeksa, brez predpomnilnika, brez datoteke registra.
• Čakajoča skrivnost TOTP je med potrditvijo izključno v seji PHP (Koncepti: potek dela (vpis)), nikoli v tej datoteki. Potrditvena koda za e-pošto je shranjena kot zgoščena vrednost s soljo (od utrditve varnosti password_hash(), prej SHA-256 brez soli – glejte docs/threat-model.md, ugotovitev F2) v lastni, kratkotrajni datoteki data/meta/wkidentity/<prijavno-ime>.emailcode.
• Novo od utrditve varnosti: data/meta/wkidentity/<prijavno-ime>.totpreplay – drobna datoteka, ki hrani samo zadnji sprejeti števec HOTP za to prijavno ime, da enkrat uporabljena koda TOTP v svojem oknu tolerance ne bi bila sprejeta še enkrat (ugotovitev F1). Ni skrivnost, samo število.
• Skrbniški pravilnik (kateri uporabniki, skupine, imenski prostori in ukazi zahtevajo drugi dejavnik oziroma katero stopnjo zagotovila) je ločeno v conf/wkidentity-policy.json (glejte skrbniško ploščo spodaj) – podatki o vpisu in pravila uveljavljanja se ne mešajo.
• Odprti postopki z enkratno kodo so spet ločeno, v data/meta/wkidentity/otp/, ena datoteka na postopek. Koda sama tam nikoli ni v golem besedilu, samo njena zgoščena vrednost – datoteka torej odgovori na vprašanja »ali je postopek obstajal, kolikokrat je bilo poslano, koliko poskusov je ostalo, kdaj poteče«, nikoli pa na vprašanje »kakšna je koda«.

Paket prinese dva skrbniška zaslona, oba samo za skrbnika (superuser):

Tri površine izberete v desnem stolpcu z ikonami (naslov ?tab=overview, users ali namespaces). Ukazi so v vrstici ukazov, števila v vrstici stanja:

Razlika med prvima stolpcema površine Uporabniki je bistvena: Dejavnik priporočen računu samo prikazuje opozorilo in ničesar ne zaklene; pri Aplikacija za preverjanje obvezna vsebina wikija za račun ostane zaklenjena, dokler aplikacija za preverjanje ni nastavljena in v tekoči seji dokazana – stran profila za nastavitev ostane dosegljiva.

Trajno shranjevanje je ločeno od Splošnih nastavitev DokuWikija, v conf/wkidentity-policy.json (PolicyStore.php, vzorec 1:1 po wvdsentra/MappingStore.php: varnostna kopija .bak pred vsakim prepisom, odporna normalizacija vnosov).

Naslov: do=admin&page=wkidentity_invites. Zaslon je zgrajen okoli ene meje: kode ni mogoče poiskati. V shrambi je samo kot zgoščena vrednost, in prav ta lastnost nosi celoten potek. Zato zaslon odgovori na vsa druga vprašanja, ki se pojavijo, ko uporabnik pokliče podporo – ali je bil postopek odprt, na kateri naslov, kolikokrat je bilo poslano, kdaj poteče trenutna koda, koliko poskusov je ostalo, kdaj se postopek zapre.

Isti prijemi so na voljo v ukazni vrstici (php bin/plugin.php wkidentity <ukaz>), za primer, ko e-pošta ne doseže nikogar: list, code, invite (z --groups=a,b in --mfa), cancel, purge.

Skrbništvo → Splošne nastavitve ($conf['plugin']['wkidentity'][…]). 22 nastavitev: nastavitve drugega dejavnika (z obema stranema s pomočjo), nastavitve postopkov z enkratno kodo in ena za upravljanje računov.

Podrobna utemeljitev je v razdelku »Postopki z enkratno kodo« v Konceptih – tu so samo vrednosti in njihov učinek.

Nobena vrednost te skupine ne povzroči prekinitve:

• recovery_factor – vsaka neprepoznana vrednost se obravnava kot mail. Neberljiva nastavitev ne sme spremeniti, kako ljudje obnovijo dostop do računa, in mail je to, kar so imeli prej.
• digits je omejen na 6–8, period na 5–300, window na 0–10; vrednosti zunaj teh mej se nadomestijo s 6 / 30 / 1.

Datoteka: lib/plugins/wkidentity/action.php

Datoteka: lib/plugins/wkidentity/helper.php

Datoteka: lib/plugins/wkidentity/PolicyStore.php (imenski prostor dokuwiki\plugin\wkidentity)

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

Je lastnik dejanja wkidentity_otp in prevzame obe jedrni vstopni točki.

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

Datoteka: lib/plugins/wkidentity/Domain/OtpStore.php (imenski prostor dokuwiki\plugin\wkidentity\Domain)

Shramba postopkov, brez kakršnega koli znanja o DokuWikiju – preverjanje kode iz aplikacije za preverjanje ji je podano kot povratni klic, namesto da bi ga izvedla sama.

Povratni klic za preverjanje kode pozna tri odgovore, ne le dva: ujema se, ne ujema se (stane en poskus – prav to omejuje ugibanje) in ni mogoče ugotoviti (ne stane nič, ker je napaka na naši strani in ne na strani obiskovalca). Če bi se zadnja dva združila, bi lahko pokvarjena veja za aplikacijo za preverjanje v petih zahtevah porabila celoten proračun poskusov in osebo zaklenila iz obnovitve, ki je dejansko sploh ni mogla poskusiti.

Datoteka: lib/plugins/wkidentity/LoginGate.php (imenski prostor dokuwiki\plugin\wkidentity)

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

Javna fasada pogodbe Identity Plugin Contract v1 – glejte razdelek zgoraj in docs/contract-v1.md.

Datoteka: lib/plugins/wkidentity/StepUp.php (imenski prostor dokuwiki\plugin\wkidentity)

• Identity – začetna stran in pogosta opravila
• Koncepti – zagotovilo, pravilnik, postopki, varnost
• Referenca API – metode pogodbe, zrcaljene iz repozitorija
• Diagnostika
• Nastavitev dvostopenjskega preverjanja – navodila za končne uporabnike, razumljiva brez tehničnega predznanja
• Workbench Plugin Contract v1 – njegovo polje permission ta pogodba uporablja
• wkmail – pošiljanje pošte, prek katerega prispejo enkratne kode