build: fix the docs path
lock 0.5.1
release 0.5.1
A wayland screen locker for touch-based Linux mobile devices
Install peanutbutter from the Alpine Linux repos:
doas apk add peanutbutter
If you are using another distro, compile this repo via cargo build and move peanutbutter into your $PATH.
Add peanutbutter to your sxmo_hook_screenoff.sh hook.
For example, my sxmo_hook_screenoff.sh looks like:
#!/bin/sh
# configversion: 63228ca431ea6d18709d2b3ad80aabf6
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2022 Sxmo Contributors
#
# See man 7 sxmo.states.
#
# This will:
# - turn screen off
# - turn input off
# - launch a demon to blink purple led every 2s
# - check wakelocks and if none suspend after 3s hold
# include common definitions
# shellcheck source=scripts/core/sxmo_common.sh
. sxmo_common.sh
# This hook is called when the system reaches a off state (screen off)
sxmo_led.sh blink red blue &
[ "$SXMO_WM" = "sway" ] && swaymsg mode default
sxmo_wm.sh dpms on
sxmo_wm.sh inputevent touchscreen off
sxmo_jobs.sh start periodic_blink sxmo_run_periodically.sh - 2 sxmo_led.sh blink red blue
case "$SXMO_WM" in
dwm)
# dmenu will grab input focus (i.e. power button) so kill it before going to
# screenoff unless proximity lock is running (i.e. there's a phone call).
if ! sxmo_jobs.sh running proximity_lock -q; then
sxmo_dmenu.sh close
fi
;;
esac
wait
peanutbutter &
By default, the screen is segregated into 4 quadrants (resolution 2):
The passcode consists of any combination of these and is configured through the
environment variable PEANUTBUTTER_PASSCODE which takes a sequence of digits
to represent the quadrants, e.g. 1132 for TOP_LEFT, TOP_LEFT,
BOTTOM_LEFT, TOP_RIGHT. This happens to also be the default passcode if the
environment variable is not set.
There is no confirm or clear option. The passcode is checked after each touch and stored in a stack with the exact length of the passcode. If you make a mistake, simply start tapping the sequence anew.
A touch will be acknowledged by flipping the background, this provides only provides a indication whether the touch was registered, not whether it is a valid touch in the passcode sequence. The feedback will be over the entire screen and will not specifically highlight the quadrant you tapped (as a security measure).
For extra security, visual feedback can be disabled entirely by passing the
-F or --nofeedback option.
Another way to increase security, is to set the parameter -3 to change the
resolution to 3 (3x3 = 9 quadrants). Which takes the following configuration:
1 2 3
4 5 6
7 8 9
You can even go up to -4, which will give you this next configuration (4x4 =
16 quadrants):
0 1 2 3
4 5 6 7
8 9 a b
c d e f
By default, if a certain number of touches (10 by default) did not lead to a successful unlock, then the locker will go into a deeper lock state and show a red background. This is a time-out state during which the device can not be unlocked, it will time out after a number of seconds (20 by default) and go back to normal lock mode. This is a security measure to prevent brute-force attacks.
The number of tries is configured via --tries, the timeout (in seconds) via --deeplock.
You can set --paranoid to make the timeout double each time the deep lock state is reached, which
may lead to the timeout being so long that you need to force a hard reboot.
This program implements the ext-session-lock-v1 protocol.
If peanutbutter inadvertently crashes, your information is not exposed.
If peanutbutter crashes, it will display a red screen. To debug, run the following command in your terminal (on the phone):
peanutbutter --debug 2> /tmp/peanutbutter.log
When peanutbutter crashes, ssh into your phone and check the /tmp/peanutbutter.log file for the error message.