Keyrust is alpha software and has not been audited by a third party. It is designed to be safe to use, and this document says exactly what that means. Keep backups of your database.
Please do not open a public issue. Report vulnerabilities privately through GitHub's private vulnerability reporting ("Report a vulnerability" in the repository's Security tab).
Please include the affected version or commit, steps to reproduce and the impact you expect. You can expect an acknowledgement within 7 days. Fixes are released as soon as practical, and reporters are credited unless they prefer otherwise.
| Version | Supported |
|---|---|
0.1.x |
✅ |
main |
✅ best effort |
| anything else | ❌ |
This threat model covers Keyrust 0.1: the desktop app for Linux, Windows and macOS, opening and saving KDBX files protected by a master password. Keyfiles, hardware keys, TOTP, browser integration and auto-type do not exist in this version. Every statement below refers to code or tests in this repository. When the code and this document disagree, that is a bug.
| Asset | Where it lives |
|---|---|
| Passwords, entry history, attachments, protected custom fields | The KDBX file, encrypted. While unlocked, in clear in the Rust process; a password also reaches the webview while it is edited, revealed or generated (The webview boundary) |
| Titles, usernames, URLs, notes, group names | The KDBX file, encrypted. While unlocked, in clear in the Rust process and in the webview, which displays them |
| The master password | Typed by the user in the webview; the Rust process keeps it in a SecretString while unlocked |
| The derived key | Rust process memory, while unlocked |
| Values copied to the clipboard | The system clipboard, until cleared |
settings.json in the app config folder |
Not secret, but it reveals the paths of recent databases |
flowchart LR
subgraph process["Keyrust process (Rust)"]
core["keyrust-core<br/>vault, KDBX, crypto"]
app["keyrust-app<br/>IPC commands, clipboard, auto-lock"]
os["keyrust-os<br/>screen lock, suspend (FFI)"]
end
webview["Webview<br/>(SvelteKit UI)"]
fs[("KDBX file<br/>local disk or sync folder")]
clip["System clipboard"]
osys["Operating system<br/>session, power"]
webview <-->|"IPC: a fixed list of commands"| app
app --- core
app --- os
core <-->|"atomic save, bounded reads"| fs
app -->|"copy, clear"| clip
os <-->|"lock and sleep notifications"| osys
- Rust ↔ webview. The webview is treated as less trusted than the Rust process. It talks to the backend only through the IPC commands listed below, with the default Tauri core permissions and no file system, shell or opener plugin access.
- Rust ↔ file system and sync provider. The file may be read and modified by other programs at any time: a sync client, another KeePass app, or an attacker who controls the sync account.
- Rust ↔ clipboard. Anything on the clipboard is readable by every program of the same user.
- Rust ↔ operating system. Screen-lock and sleep notifications come from the OS. Only
crates/osmakes foreign function calls to obtain them.
| Attacker | Capability | Mitigation | Where | Residual risk |
|---|---|---|---|---|
| Thief of the file (lost laptop, leaked backup, cloud breach) | Reads the file offline | KDBX4 encryption; Argon2id for new databases (64 MiB, 2 lanes, iterations calibrated to about 1 s) | crates/core/src/vault.rs (create, argon2id) |
A weak master password can still be guessed |
| Hostile sync provider | Reads, alters, deletes or rolls back the file | HMAC-authenticated header and content; key-derivation limits checked before deriving the key; bounded reads; external changes detected before every save | crates/core/src/kdbx/limits.rs, crates/core/src/file.rs, fuzz targets in fuzz/ |
Deletion and rollback to an older valid file cannot be detected: keep backups |
| Compromised webview content (a hypothetical XSS) | Runs script in the UI | Strict CSP (no inline or remote script, no network except IPC), minimal capabilities; file paths come only from native dialogs or the recent files; lists and entry details never carry passwords | crates/app/tauri.conf.json, crates/app/capabilities/, crates/app/src/commands.rs, crates/app/tests/security_config.rs |
It can read what is open in the editor, revealed or generated, and call the allowed commands, including copy_field and reveal_field (see The webview boundary) |
| Someone at the computer | Uses an unlocked or locked session | Auto-lock on inactivity, screen lock, sleep and optionally minimize; masked passwords; clipboard cleared | crates/app/src/autolock/, crates/os/ |
An unlocked, unattended session before the idle delay expires |
| Other programs of the same user | Read the clipboard, memory, the screen, input | Clipboard cleared after a delay, on lock and on exit, and excluded from clipboard history where the platform supports it | crates/app/src/clipboard.rs |
Not defended: see What Keyrust does not protect against |
| Supply chain | Malicious or vulnerable dependency | Pinned lockfiles, cargo deny (advisories, licenses, sources), no hand-written cryptography, pinned CI actions |
deny.toml, .github/workflows/ci.yml |
A compromised upstream release that passes these checks |
-
Encryption at rest. The file is encrypted per the KDBX4 specification. New databases use Argon2id with explicit parameters, never library defaults; the parameters can be changed in Database settings. KDBX 3.1 and 4.0 files open normally; the first save converts them to KDBX 4.1, and Keyrust says so with a notice when such a file is opened.
-
Tampering. KDBX4 authenticates the header and the payload with HMAC. KDBX 3.1 has no header HMAC: Keyrust compares the header with the
HeaderHashstored in the encrypted part, which keepass-rs does not check, so a changed header field is caught there too. A modified file is rejected rather than silently opened. KDBX 3.1 files written by KeePass before 2.20 carry noHeaderHashand are opened without that check, as KeePassXC does. -
Hostile files. The key-derivation parameters are read before anything is authenticated, so a tampered file could ask for any amount of memory or time. Keyrust checks them before deriving the key and refuses files beyond Argon2 2 GiB of memory, 1000 iterations or 256 lanes, 2·10⁹ AES-KDF rounds, or a file size of 512 MiB ("This database asks for more memory or time than Keyrust allows"). The same limits bound what Keyrust itself lets you create, and a save that would write a file beyond the size limit is refused, leaving the file on disk as it was. Reads are bounded too, including the checks for external changes. The parsing path is fuzzed: headers, whole files, and save/open round trips (fuzz/README.md).
-
Data loss on save. Saves are atomic: a temporary file in the same folder, fsync, then rename. Before replacing the file, Keyrust checks twice that it still holds exactly the bytes it last read or wrote (length and SHA-256). If another program changed it, the save is refused and you choose between Reload and Keep mine. Keyrust instances on the same computer also coordinate through a lock file. The reported KDBX version changes only once the file has been replaced.
-
Resurrected deletions. Permanently deleted entries and groups are recorded as KDBX tombstones, so merging in another KeePass client does not bring them back.
-
Secrets in the Rust process. Secret values are held in
zeroize/secrecytypes and wiped when dropped. They are never logged (a test checks the log output), never written to disk in clear text, and redacted inDebugoutput. -
Clipboard. Copying happens in Rust (
copy_field): the password does not pass through the webview. Keyrust keeps only a hash of what it copied, and clears the clipboard after the configured time, on lock and on exit, only if the clipboard still holds that value. It asks the platform to exclude copied secrets from clipboard history where supported. -
Auto-lock, decided in the Rust process. The vault is dropped and zeroized there, even if the webview hangs:
- after the configured minutes of inactivity (keyboard, pointer and wheel input in the window);
- when the screen locks (option, on by default): Windows and macOS poll the session state
every 2 s, Linux listens to the desktop's
ScreenSaver.ActiveChangedsignal on D-Bus; - when the computer goes to sleep, always: Windows power notification, Linux logind
PrepareForSleep, and everywhere a detector of wall-clock jumps (the only one on macOS); - when the window is minimized (option, off by default).
An unlock still deriving the key when a lock arrives is discarded, so it cannot undo the lock. Like the manual Lock, an automatic lock asks nothing: changes that could not be saved are lost, and the Unlock screen says so.
-
Memory safety. Rust with
unsafe_codeforbidden inkeyrust-coreandkeyrust-app. The onlyunsafecode is incrates/os/src/lib.rs, a few FFI calls: whether the screen is locked (WindowsOpenInputDesktop, macOSCGSessionCopyCurrentDictionary) and the Windows suspend notification (PowerRegisterSuspendResumeNotification). There it is denied crate-wide and allowed function by function, each block with aSAFETY:comment (enforced by clippy). -
Compatibility as a safety property. Files written by Keyrust are read back by KeePassXC (
keepassxc-cli) in CI, and KeePassXC files are opened and saved by Keyrust without loss (crates/core/tests/). An end-to-end test drives the real app and checks the saved file with KeePassXC (crates/app/e2e/).
The UI runs in a webview, whose JavaScript strings cannot be reliably erased. Keyrust therefore keeps passwords out of it except when the user is working with one:
- Never sent to the webview: the group tree, the entry list (
EntrySummary: title, username, URL), the entry details (EntryDetail: notes, dates, whether a password exists), search results and custom protected fields. Copying a password to the clipboard happens in Rust. The end-to-end test checks that no fixture password appears anywhere in the page (text, attributes, field values) after unlocking and after selecting an entry. - Sent to the webview, on request: the password of the entry being edited
(
get_entry_for_edit), a password the user reveals (reveal_field), and a generated password (generate_password). - Typed in the webview: the master password (Unlock, Create, Change master password) and the entry fields the user types. The Unlock field is cleared after every attempt.
Everything the webview displays (titles, usernames, URLs, notes, group names) is in its memory too. From there the limit above applies: those strings may remain in the webview's memory until it reuses it. A compromised webview could read whatever is open in the editor, revealed or generated, and could call the allowed IPC commands. It could not choose which files to open or create: paths come only from native dialogs and the recent files.
- A compromised computer while the vault is unlocked. Malware running as your user (keyloggers, screen capture, memory readers, clipboard monitors) can read what you can read. No password manager can defend against this.
- A weak or reused master password. The key derivation slows guessing down; it cannot make a weak password strong.
- Physical access to an unlocked session.
- Memory forensics after the fact. Wiping is best effort. The operating system may swap memory to disk or produce crash dumps, and the webview's JavaScript engine does not guarantee that strings are erased (see The webview boundary).
- Clipboard managers and history. Keyrust cannot control third-party clipboard tools.
- Sync conflicts and malicious sync providers. A provider cannot read the file, but it can delete it or roll it back to an older version. Keep backups. A program that does not use Keyrust's lock (another KeePass client, a sync tool) can still write in the instant between Keyrust's last check and its rename; that window cannot be closed without operating-system support. Keyrust does not merge concurrent changes: it detects them and asks.
- Auto-lock gaps. Screen-lock detection on Linux depends on the desktop sending the D-Bus signal (GNOME, KDE, MATE and Cinnamon do; some minimal window managers do not). On macOS sleep is detected from a jump of the clock, so a sleep and wake cycle shorter than 4 seconds, with "require password after sleep" turned off, is not noticed. Setting the clock forward by more than 4 seconds locks needlessly (the safe side). The idle timer only counts input inside Keyrust's window.
- Decompression bombs inside an authenticated file. keepass-rs decompresses the content only after verifying its HMAC with your key, so such a file can only be made by someone who has your master password, and with it they already have everything. A decompression cap is to be requested upstream.
- Very old KeePass clients. After the first save a database is KDBX 4.1; clients that only read KDBX 3.1 cannot open it any more.
- Side channels, and a compromised build or update channel.
The webview can call exactly these commands, defined in
crates/app/src/commands.rs. A test
(crates/app/tests/security_config.rs) fails if one is added
or removed without updating it, and also checks the capabilities, the plugin permissions and the
production CSP.
| Commands | What they expose or do |
|---|---|
app_info, get_settings, update_settings, exit_app |
Version, preferences (no secrets); the recent files belong to the backend and cannot be set from the webview |
recent_files, choose_database_file, choose_new_database_path |
File names and paths; new paths only from native dialogs |
unlock, create, lock_vault, activity |
Open or create a database at an allowed path, lock it, report activity for the idle timer |
database_info, tree, list_entries, get_entry |
Names, cipher, KDF parameters, version; groups; summaries and details without passwords |
get_entry_for_edit, reveal_field |
The editable entry, password included; one field on request |
copy_field |
Copies a field to the clipboard from Rust and returns the clear delay |
save_entry, delete_entry, restore_entry, create_group, rename_group, delete_group |
Changes to entries and groups |
update_database, change_master_password |
Database name, cipher, KDF and recycle bin; master password |
save, save_overwrite, reload, check_file |
Write the file (refused if it changed on disk, unless Keep mine), re-read it, detect an external change |
generate_password, estimate_strength, benchmark_kdf |
Generated passwords (system CSPRNG), strength estimates, KDF calibration |
open_url |
Opens an entry's URL in the system browser, http and https only |
- No hand-written cryptographic primitives: only standard, maintained libraries (RustCrypto, keepass-rs).
- Argon2id for new databases, with explicit parameters (never library defaults).
- Secrets:
zeroize/secrecy, never logged, never serialised in clear text, never inDebugoutput. - Minimal Tauri capabilities and a strict Content Security Policy; no remote resources and no network access in v1.
- A new IPC command is a security change: it is added to the test above and to the table in this document.
Every release on the Releases page carries, next to the installers:
SHA256SUMS: the SHA-256 of every installer;SHA256SUMS.sigstore.json: a Sigstore cosign signature ofSHA256SUMS. It is keyless: instead of a long-lived key, it binds the file to the GitHub Actions run of this repository's release workflow for that tag, and is recorded in the public Rekor transparency log.
Verifying takes two steps: the signature proves that SHA256SUMS was produced by Keyrust's release
workflow, and the checksum proves that your installer is the one listed there.
1. Check the signature (needs cosign 3
or later; replace v0.1.0 with the release you downloaded):
cosign verify-blob SHA256SUMS \
--bundle SHA256SUMS.sigstore.json \
--certificate-identity "https://github.com/downlevel/keyrust/.github/workflows/release.yml@refs/tags/v0.1.0" \
--certificate-oidc-issuer https://token.actions.githubusercontent.comIt must print Verified OK. Any other identity means the file was not signed by a Keyrust release.
2. Check your installer against its line of SHA256SUMS (you need only the installer you
downloaded, not all of them):
# Linux
grep ' Keyrust_0.1.0_amd64.deb$' SHA256SUMS | sha256sum -c -
# macOS
grep ' Keyrust_0.1.0_universal.dmg$' SHA256SUMS | shasum -a 256 -c -# Windows (PowerShell)
$file = "Keyrust_0.1.0_x64-setup.exe"
$expected = (Select-String -Path SHA256SUMS -Pattern " $([regex]::Escape($file))$").Line.Split(" ")[0]
if ((Get-FileHash $file -Algorithm SHA256).Hash -eq $expected) { "OK" } else { "MISMATCH" }The check must print OK.
Code signing. Installers are signed for Windows (Authenticode) or macOS (Developer ID and notarization) only when the maintainer has configured a certificate; the Build section of each release's notes says which. Without it, SmartScreen and Gatekeeper warn before the first launch, and the cosign check above is the way to know the installer is genuine.
Reproducibility. Builds are reproducible on a best-effort basis; the release notes report whether the Linux binary came out identical when built twice, and docs/RELEASING.md explains how to rebuild it yourself.