Initial commit.

2026-06-02 17:29:55 -04:00
commit db522d7d66
33 changed files with 4017 additions and 0 deletions
@@ -0,0 +1,91 @@
+I38Lock - accessible screen locker for I38
+==========================================
+I38Lock is an accessible screen locker for I38, based on
+[i3lock](https://i3wm.org/i3lock/).
+After starting it, you will see a white screen (you can configure the
+color/an image). You can return to your screen by entering your password.
+
+It retains i3lock's behavior while adding blind-accessible password feedback:
+
+- I38Lock forks, so you can combine it with an alias to suspend to RAM
+  (run "i38lock && echo mem > /sys/power/state" to get a locked screen
+   after waking up your computer from suspend to RAM)
+
+- You can specify either a background color or a PNG image which will be
+  displayed while your screen is locked. Note that I38Lock is not an image
+manipulation software. If you need to resize the image to fill the screen
+or similar, use existing tooling to do this before passing it to I38Lock.
+
+- You can specify whether I38Lock should bell upon a wrong password.
+
+- When Cthulhu or Orca is running, I38Lock sends password-entry feedback to the
+  screen reader over its D-Bus remote-controller interface. Empty passwords are
+  rejected locally without invoking PAM.
+
+- I38Lock uses PAM and therefore is compatible with LDAP etc.
+  On OpenBSD I38Lock uses the bsd_auth(3) framework.
+
+Install
+-------
+
+See [the upstream i3lock home page](https://i3wm.org/i3lock/).
+
+Requirements
+------------
+- pkg-config
+- libxcb
+- libxcb-util
+- libpam-dev
+- libcairo-dev
+- libglib2.0-dev
+- libxcb-xinerama
+- libxcb-randr
+- libev
+- libx11-dev
+- libx11-xcb-dev
+- libxkbcommon >= 0.5.0
+- libxkbcommon-x11 >= 0.5.0
+- libxcb-image
+- libxcb-xrm
+
+Running I38Lock
+---------------
+
+To test I38Lock, you can directly run the `i38lock` command. To get out of it,
+enter your password and press enter.
+
+For a more permanent setup, we strongly recommend using `xss-lock` so that the
+screen is locked *before* your laptop suspends:
+
+```
+xss-lock --transfer-sleep-lock -- i38lock --nofork
+```
+
+On OpenBSD the `i38lock` binary needs to be setgid `auth` to call the
+authentication helpers, e.g. `/usr/libexec/auth/login_passwd`.
+
+Building I38Lock
+----------------
+We recommend you use the provided package from your distribution. Do not build
+I38Lock unless you have a reason to do so.
+
+First install the dependencies listed in requirements section, then run these
+commands (might need to be adapted to your OS):
+```
+rm -rf build/
+mkdir -p build && cd build/
+
+meson setup -Dprefix=/usr
+ninja
+```
+
+Before testing a locally built binary on Linux, install the PAM policy:
+```
+sudo install -Dm644 ../pam/i38lock /etc/pam.d/i38lock
+```
+Without this file, I38Lock refuses to lock rather than risk creating a session
+that cannot be unlocked.
+
+Upstream
+--------
+I38Lock is based on https://github.com/i3/i3lock.