diff --git a/README.md b/README.md index 3b8cad6..e3b7303 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

Face ID for KDE Plasma.

- Look at the screen and it unlocks: the lock screen, sudo and admin prompts. A photo on a phone does not fool it. + Unlock the lock screen, sudo and admin prompts with your face.

@@ -29,19 +29,19 @@ The bubble above the lock screen: looking, recognised, not recognised

-Come back to your locked screen and look at it. A bubble drops down at the top, finds your face, -and you are in. It works for `sudo` and Plasma's admin prompts too, if you want. Everything runs on -your computer, and your face is saved as numbers, never as a picture. - ## Install -**Arch, CachyOS, EndeavourOS, Manjaro** (AUR) +
+Arch, CachyOS, EndeavourOS, Manjaro ```bash yay -S plasma-face-unlock ``` -**Fedora** +
+ +
+Fedora ```bash sudo curl -fsSL -o /etc/yum.repos.d/plasma-face-unlock.repo \ @@ -49,7 +49,10 @@ sudo curl -fsSL -o /etc/yum.repos.d/plasma-face-unlock.repo \ sudo dnf install plasma-face-unlock ``` -**Debian, Kubuntu** +
+ +
+Debian, Kubuntu ```bash codename="$(sed -n 's/^VERSION_CODENAME=//p' /etc/os-release)" @@ -61,10 +64,9 @@ echo "deb [signed-by=/etc/apt/keyrings/plasma-face-unlock.gpg] https://loonixtoo sudo apt update && sudo apt install plasma-face-unlock ``` -The packages are built for the current release of each. Updates then come with your normal system -updates. +
-You need Plasma 6 on Wayland and a camera. Infrared cameras (the Windows Hello kind) work too. +Needs Plasma 6 on Wayland and a camera. Updates come with your system updates. ## How to use @@ -72,76 +74,71 @@ You need Plasma 6 on Wayland and a camera. Infrared cameras (the Windows Hello k plasma-face-unlock ``` -This opens a menu: -

The plasma-face-unlock menu in Konsole: face unlock on, one face, lock screen, sudo and admin prompts on

-Press **1** and follow the setup window: look at the camera, then turn your head slowly in a circle -until the ring is full. Then lock the screen and look at it. **2** adds another face, for example -with glasses, and **5** runs one test scan that shows what the camera sees. Try that first when -something does not work. +Press **1** and look at the camera. Then lock the screen and look at it. -**4** opens the settings. The text at the bottom says what the selected one does: +
+Settings

The settings in Konsole, grouped into lock screen, password prompts, recognition and bubble, with the photo check explained at the bottom

-Without the menu: `plasma-face-unlock enable`, `disable`, `setup [NAME]`, `faces`, `remove ID`, -`test` and `status`. +
## Is it safe? -It is a convenience, not a security upgrade. Face ID on a phone sees your face in 3D. A webcam only -sees a flat picture. - -- You do not have to blink. A photo on a phone or tablet, or a glossy print, is still refused: - it gives itself away by its reflection and its straight edges. -- A matte printed photo can get past that. Set the photo check to *strict* in the settings: then - the face has to blink or turn a little, and a photo can do neither. -- A video of you can still get in. -- Five failed tries in a row pause it for 15 minutes, or until you use your password. -- Only root can read your face data. Adding or deleting a face always needs your password. -- sudo and admin prompts never take a face over SSH. - -If the computer guards something important, leave sudo and admin prompts off. - -## How it works +A convenience, not extra security. A webcam only sees a flat picture. | | | |---|---| -| `plasma-face-unlockd` | Runs as root when needed. It owns the camera and the face data and decides. | -| `plasma-face-unlock-agent` | Runs in your session. It watches the lock screen and draws the bubble. | -| `pam_plasma_face_unlock.so` | Lets sudo and admin prompts ask the daemon. No match: you type your password as usual. | +| Photo on a phone, tablet or glossy paper | ✅ Stopped | +| Matte printed photo | ⚠️ Only stopped with photo check *strict* | +| Video of you | ❌ Can get in | +| Five failed tries | ⏸️ Paused for 15 minutes | +| Your face data | 🔒 Numbers, no pictures. Root only. | +| sudo over SSH | 🚫 Never unlocked by a face | + +## More + +
+How it works + +| | | +|---|---| +| `plasma-face-unlockd` | The root service. Owns the camera and the face data. | +| `plasma-face-unlock-agent` | Runs in your session. Watches the lock screen, draws the bubble. | +| `pam_plasma_face_unlock.so` | Lets sudo and admin prompts ask the service. | | `plasma-face-unlock` | The menu. | -Two small networks from the OpenCV model zoo find the face (YuNet) and turn it into numbers (SFace). -They run on the CPU in a few milliseconds. The lock screen is unlocked through logind, the same way -`loginctl unlock-session` does it. `man plasma-face-unlock` has all the details. +Two small networks from the OpenCV model zoo run on the CPU: YuNet finds the face, SFace turns it +into numbers. All details: `man plasma-face-unlock`. -## Build from source +
+ +
+Build from source ```bash -make models # downloads the two networks and checks them +make models make make test sudo make install ``` -You need CMake, a C++20 compiler, Qt 6, LayerShellQt, KI18n, OpenCV 4.5.4 or newer (with DNN), -Linux-PAM and libsystemd. `scdoc` and `msgfmt` are optional (man page, translations). -[packaging/README.md](packaging/README.md) explains releases. +Needs CMake, a C++20 compiler, Qt 6, LayerShellQt, KI18n, OpenCV 4.5.4+ (with DNN), Linux-PAM and +libsystemd. + +
## Credits -- [Glance](https://github.com/jonnyoo/glance) by Jonathan Zhou (MIT): face unlock for the Mac. The - idea, the look of the bubble and the photo check come from there. The code here is new. -- [YuNet](https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet) (MIT) and - [SFace](https://github.com/opencv/opencv_zoo/tree/main/models/face_recognition_sface) (Apache-2.0) - from the OpenCV model zoo. - -## License +- [Glance](https://github.com/jonnyoo/glance) by Jonathan Zhou: the idea and the look of the bubble. +- [YuNet](https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet) and + [SFace](https://github.com/opencv/opencv_zoo/tree/main/models/face_recognition_sface) from the + OpenCV model zoo. GPL-3.0-or-later.