pn-lock

E-ink optimized Wayland screen locker for the Pine64 PineNote, using the ext-session-lock-v1 protocol.

Features

• Touch-friendly PIN pad with large buttons optimized for E-ink touchscreens
• Progressive PIN dots - shows only entered digits, no fixed length revealed
• Time display in HH:MM format, updates only when needed to save battery
• E-ink optimizations via pinenote-service D-Bus integration
• Secure authentication using PAM in an isolated forked process
• Memory protection - passwords are locked in memory and zeroed after use

Building

Release build (recommended for deployment)

cargo build --release

Debug build with verbose logging

cargo build --features debug-verbose

Debug build with mock E-ink (for testing on non-PineNote)

cargo build --features debug-mock-ebc,debug-verbose

Debug build without forking (easier debugging)

cargo build --features debug-no-fork,debug-verbose

Installation (directly on the PineNote)

1. Build the release binary:

   cargo build --release

2. Install the binary:

   sudo install -m755 target/release/pn-lock /usr/bin/

3. Install the PAM configuration:

   sudo install -m644 pam.d/pn-lock /etc/pam.d/

Installation (cross-compiling from an amd64 machine)

1. Cross-compile for aarch64:

cross build --target aarch64-unknown-linux-gnu --release

2. Copy the binary and PAM config to the PineNote:

scp target/aarch64-unknown-linux-gnu/release/pn-lock archuser@pinenote:~/pn-lock
scp pam.d/pn-lock archuser@pinenote:~/pn-lock.pam

3. On the PineNote, install the binary and PAM config:

ssh archuser@pinenote 'sudo install -m755 ~/pn-lock /usr/bin/ && sudo install -m644 ~/pn-lock.pam /etc/pam.d/pn-lock && rm ~/pn-lock ~/pn-lock.pam'

4. On the PineNote, add this to the end of /usr/bin/before_sleep.sh:

killall pn-lock
sleep 0.1
pn-lock

Debug Features

All compiled out in release builds:

• debug-verbose — extra logging for Wayland events, touch coords, etc.
• debug-mock-ebc — skips D-Bus calls to pinenote-service, for testing on non-PineNote hardware
• debug-no-fork — runs PAM in the main process instead of forking, easier to attach a debugger

RUST_LOG=debug cargo run --features debug-verbose,debug-mock-ebc

Architecture

The main process runs a calloop event loop that drives everything:

• wayland/ — ext-session-lock-v1 session lock, keyboard/pointer/touch input via smithay-client-toolkit
• render/ — software-rendered UI with tiny-skia (7-seg clock, PIN pad, dot indicators)
• ebc/ — e-ink display controller, talks to pinenote-service over D-Bus
• input/ — mlock'd password buffer with zeroize-on-drop
• auth/ — PAM authentication in a forked child process, communicates over pipes

Security

• Session lock is atomic - if pn-lock crashes, the session remains locked
• PAM authentication runs in an isolated forked child process
• Password buffer is mlock'd to prevent swapping
• Password memory is zeroed after use with zeroize
• No bypass mechanisms in release builds

Disclaimer

pn-lock is under development and has not yet received a formal security audit. While it has been tested on my PineNote for daily use, I cannot guarantee its security.

License

See LICENSE