diff --git a/README.md b/README.md new file mode 100644 index 0000000..9834b29 --- /dev/null +++ b/README.md @@ -0,0 +1,148 @@ +# bscreensaver + +## What + +`bsreensaver` is a simple X11 screen locker for Linux that is designed +to be secure (in the same vein as `xscreensaver`), but also secure, +meaning that once the screen is locked, it will be incredibly difficult +to unlock the screen without a password, even if crash-level bugs are +found in many of `bscreensaver`'s isolated components. + +## Why + +`xscreensaver` is likely one of (if not the) most secure screen lockers +out there. However, the unlock dialog, despite my attempts to theme it +(mainly by changing colors and border widths) is extremely ugly. Even +if I could get it to look decently nice, it would still not fit in with +my GTK-based desktop. + +The last time I looked at the other GTK-based screensavers +(`gnome-screensaver`, `xfce4-screensaver`), they both embedded the +unlock dialog into the main screen locking process. This is terrible +for security, as GTK is a very large toolkit that is difficult to +secure. Crasher bugs may not always be high-priority items for the +developers to fix, especially if a crash is obscure and only happens +in unlikely scenarios. Unfortunately, these types of crash bugs are +critical for a screen locker, as this can mean that doing something +strange (like, say, repeatedly pressing some key combination while +shaking the mouse around) can cause the locker to crash, unlocking the +system without authentication. + +## Build and Installation + +`bscreensaver` is written in Rust, and requires `cargo` and a Rust +compiler installed. Stable rust is fine, though something fairly recent +(as of May 2022) is required. + +A `Makefile` is provided to make things easy. Run `make` to build a +release version of the software, and `make install` to install it. By +default, components will be installed under `/usr/local`. You may pass +`PREFIX`, `BINDIR`, `LIBEXECDIR`, `DATADIR`, and `MANDIR` to your +invocation of `make` and `make install` to customize the installation. +Be sure to pass these with `make` as well, because the build process +embeds filesystem paths into the binary so the main locker process can +find its helper applications. + +You can also pass `DESTDIR` to install to a staging directory (e.g. for +building distribution packages). I've also included a `deb-pkg` target +that will use Docker to build a Debian package. + +## Configuration + +The locker looks for a configuration file in the relative path +`bscreensaver/bscreensaver.toml` using the XDG base directories +specification. In practice, by default it should look for files in the +following places: + +* `/etc/xdg/bscreensaver/bscreensaver.toml` +* `$HOME/.config/bscreensaver/bscreensaver.toml` + +Settings in these files are "additive" in that each file is read and +parsed, and settings in "later" files override settings specified in +"earlier" files. + +A sample configuration file is included (`bscreensaver.toml.example`). +Distributions may install this to `/usr/share/doc/bscreensaver` or +possibly `/etc/xdg/bscreensaver`. + +You need not edit the configuration file manually, but can instead run +the `bscreensaver-settings` program, which displays a settings UI. + +## Architecture + +`bscreensaver` is broken up into several pieces, each which run in their +own isolated process: + +* locker +* dialog +* dbus-service +* systemd-service +* command +* settings + +### Locker + +The locker component is the most critical. It's responsible for drawing +blank windows on the screen and grabbing the keyboard and mouse. When +it detects mouse movement or key presses, it will run the dialog +component, and examine its exit status to determine if the screen should +be unlocked. + +This component must not crash under any circumstances. A crash here +means that a locked screen is now unlocked. This component should have +has few dependencies as possible, and should handle errors in such a way +that the program tries very hard to stay running even when unexpected +things happen. + +### Command + +The command component is a small bit of functionality that uses a hidden +X11 window to allow the locker process to be sent commands (such as +"lock", "deactivate", or "restart"). The locker process, on startup, +creates a hidden X11 window, and then publishes the ID of this window in +a property on the screen's root window. When someone uses the command +component to send a command to the locker, the command component finds +the command window's ID, and then sends it a client message. + +### Dialog + +The dialog component draws a password prompt on the screen, and then +validates that the password entered was correct. If the password is +correct, the dialog exits with status 0. If not, or if authentication +is canceled, it exits with a failure status. + +The dialog process and locker process also communicate using the XEMBED +protocol, which allows us to seamlessly embed X11 UI from one process +into another. + +### DBus Service + +The DBus service is launched by the locker process and acquires the +`org.freedesktop.ScreenSaver` bus name, and responds to requests to +inhibit and uninhibit the screen locker (for example, when you are +playing a video on your computer, you don't want the screen to lock, +even if you don't move the mouse or touch a key). + +It communicates with the locker process using the command component. To +inhibit the locker, it periodically sends a "deactivate" command to the +locker, which causes it to reset its user activity timeout (assuming the +locker is currently unlocked). + +### Systemd Service + +The systemd service handles locking the screen on suspend and presenting +the unlock dialog on resume. If you close the lid of your laptop, you +probably want the screen to lock immediately. The `bscreensaver` +systemd service registers a sleep inhibitor with systemd that causes it +to delay sleep so that the systemd service can be notified of impending +sleep, and use the command component to instruct the locker to lock, +before telling systemd that it's ok to sleep. + +When the computer wakes back up, it again receives a notification from +systemd, which allows it to present the unlock dialog immediately after +resuming. + +### Settings + +The settings component is a standalone GTK app that presents a settings +dialog, which reads from and writes to your configuration file.