Watch
1
0
Fork
You've already forked LUKSRemoteUnlocker
0
No description
  • Dart 91.5%
  • Shell 2.7%
  • CSS 2.1%
  • HTML 1.2%
  • CMake 0.7%
  • Other 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
manzari d43bb53684 Move the promo engine to apppage 81fb0e3
The engine picks up the source-code channel, which turns the source_url set
in _config.yml into a download button and a footer link, and the optional
per-project webfonts in fonts/. en.yml gains the strings the source channel
needs. The Impressum keeps its DDG citations.
2026-11-20 23:30:48 +01:00
app Bump the app version to 0.2.3 2026-11-20 22:02:15 +01:00
bench Prepare the repository for publishing 2026-11-18 01:05:29 +01:00
docs Link the privacy policy and the terms from Settings 2026-11-20 19:01:42 +01:00
packages Show the pre-boot ping as its own step 2026-11-18 01:19:42 +01:00
promo Move the promo engine to apppage 81fb0e3 2026-11-20 23:30:48 +01:00
tool Render the promo screenshots as JPEG and add the Play feature graphic 2026-11-20 19:03:18 +01:00
.gitignore Prepare the repository for publishing 2026-11-18 01:05:29 +01:00
analysis_options.yaml Scaffold workspace, Docker toolchain and empty Android/Linux app 2026-11-14 22:15:36 +01:00
codemagic.yaml Promote Play releases through Codemagic and drop the local bundle target 2026-11-20 21:48:09 +01:00
LICENSE Prepare the repository for publishing 2026-11-18 01:05:29 +01:00
Makefile Promote Play releases through Codemagic and drop the local bundle target 2026-11-20 21:48:09 +01:00
pubspec.lock Scaffold workspace, Docker toolchain and empty Android/Linux app 2026-11-14 22:15:36 +01:00
pubspec.yaml Scaffold workspace, Docker toolchain and empty Android/Linux app 2026-11-14 22:15:36 +01:00
README.md Promote Play releases through Codemagic and drop the local bundle target 2026-11-20 21:48:09 +01:00
SECURITY.md Prepare the repository for publishing 2026-11-18 01:05:29 +01:00

LUKS Remote Unlocker

Unlocks LUKS-encrypted Linux servers that wait at the Dropbear pre-boot prompt, from Android, Linux desktop or the command line. One tap per server, or all of them at once.

What it does

For each server the app:

  1. waits until the pre-boot SSH port answers,
  2. checks the server's pinned host key and stops if it changed,
  3. logs in with the SSH key assigned to that server,
  4. hands the disk passphrase to cryptroot-unlock and reads the result from its exit code,
  5. confirms the boot: the unlock counts as done only when the booted system answers with a different SSH host key than the pre-boot one.

Servers, SSH keys and passphrases are managed in the app. Runs are kept in a history with sanitized logs, and the configuration can be exported and imported.

Platforms

Platform Status
Android (7.0 and later) Works; a run continues with the screen off
Linux desktop Works
Command line (luks-unlock) Works; see packages/unlock_cli/README.md
iOS Not finished and not yet tested on a device

Servers: Debian and Ubuntu with dropbear-initramfs.

Server setup

The server needs Dropbear in its initramfs, started with cryptroot-unlock as the forced command. docs/server-setup.md has the four steps.

Install

There are no published releases yet; build from source. Docker is the only requirement:

make apk-release   # signed Android APK, needs app/android/key.properties
make apk           # debug Android APK
make linux         # Linux desktop build
make cli           # build/luks-unlock

Security model

The passphrase is only as safe as the server it is sent to, so host-key pinning matters as much as the vault.

  • Vault. Every private key and passphrase is encrypted with XChaCha20-Poly1305 under one random vault key. On phones that key is released by a fingerprint or face through the device's secure hardware; a recovery password (Argon2id) is the second way in, and the only one on Linux.
  • Host-key pinning. The pre-boot host key is confirmed on first connect or pasted in advance. A changed key stops that host before login, and there is no "accept anyway" during a run.
  • No retries of a rejected passphrase. Debian allows three tries by default, so the app never spends them on its own.
  • Nothing leaves the device. Android backups and device transfer are switched off, screenshots are blocked, only public keys can be copied or shared, and passphrases are stripped from logs.
  • No accounts, no telemetry. The app talks only to the servers you configure.

Details are in docs/design.md. To report a vulnerability, see SECURITY.md.

Development

Everything runs in Docker (tool/Dockerfile.dart, tool/Dockerfile.flutter, tool/Dockerfile.emulator); nothing is installed on the host.

Target What it does
make test Analysis and tests for unlock_core, unlock_cli and the app
make test-core / test-cli / test-app Same for one package; ARGS="test/x_test.dart" narrows the run
make cli Builds build/luks-unlock
make apk Debug Android APK
make apk-release Signed release APK; needs app/android/key.properties
make linux Debug Linux desktop build
make shell-dart / shell-flutter Interactive shell in the toolchain container
make run-dart CMD="..." / run-flutter CMD="..." One command in the toolchain container
make bench-up / bench-down Start or remove the Dropbear test bench
make test-bench Engine and CLI tests against the running bench
make test-app-bench Linux app under Xvfb unlocks the three bench targets in parallel (resets them first)
make test-android-bench Same flow on an Android emulator (tool/Dockerfile.emulator); needs a Docker daemon that sees /dev/kvm, EMULATOR_ACCEL=off runs without it, very slowly
make promo / promo-up Builds the landing page image, or builds and serves it on localhost:8888
make promo-shots Renders the app's screens in widget tests and writes them to promo/images
make promo-feature Renders promo/feature-graphic.svg into the Play Store feature graphic, promo/images/feature-graphic.png

Landing page

luksremoteunlocker.manzari.dev is built from promo/ by the apppage engine, a copy of which is in promo/engine: texts in promo/i18n/en.yml, links and Impressum data in promo/_config.yml, colours in promo/brand.css, and the privacy policy and terms from promo/engrossify.yaml. promo/compose.yaml is the deployment and names the one secret its build needs.

Android blocks screenshots of the app, so the images on the page are the real screens rendered by make promo-shots with made-up hosts.

License

MIT