Kunzisoft / Kunzisoft/KeePassDX

Biometric-gated keyfile storage via Android Keystore (app-managed, encrypted at rest)

Open
#2,676 1 comment 0 reactions 0 assignees View on GitHub
feature
Dominant language
Kotlin
Stars
7.3k
Forks
401
Avg merge
2d 10h
Merged PRs (30d)
1

Description

### Checks

- [x] I have read the Wiki, searched the open issues, and still think this is a new feature.

### Explain the problem clearly and succinctly:

### Brief Summary

When using a keyfile as part of a composite master key, the keyfile currently sits as a plaintext file (in app-private or shared storage, depending on setup) with no protection beyond standard filesystem/storage-scoping. Biometric unlock in KeePassDX substitutes for typing the master password, but doesn't change how the keyfile itself is stored — anything with access to that file location (another app with matching permissions, a device backup, a compromised process) can read it directly, independent of whether biometric unlock is enabled at all.

I'd like to propose that KeePassDX optionally manage the keyfile the way Android's platform primitives already support for other secrets: encrypted at rest using a key held in the Android Keystore, decrypted only transiently in memory and gated by a fresh BiometricPrompt on each access, rather than existing as a permanently readable plaintext file.

### Motivation

This pattern is already established and shipping in the adjacent SSH-key space, just not yet applied to KeePass-style keyfiles:

- **[Secretive](https://github.com/maxgoedjen/secretive)** (macOS) generates SSH keys directly inside the Secure Enclave — key material never exists as a plaintext file and can't be exported; every use requires Touch ID.
- **fssh** (macOS) takes the more directly relevant "wrap an existing secret" approach: encrypts existing SSH keys and stores the decryption key in the Keychain, gated by Touch ID, decrypting transiently per use rather than leaving plaintext on disk.
- Android's own Keystore + `BiometricPrompt` (with `setUserAuthenticationRequired`/`CryptoObject`) provides the equivalent primitive natively — a key that can be bound to require biometric authentication before it can be used to decrypt data, with the key material itself never leaving the secure hardware (TEE/StrongBox where available).

Given KeePassDX already integrates biometric authentication for master-password Quick Unlock, extending an equivalent Keystore-backed wrapping to the standalone keyfile seems like a incremental extension of infrastructure tha

### Describe the solution you'd like:

- Opt-in setting alongside existing biometric unlock options, e.g. "Protect keyfile with biometrics."
- On enabling: KeePassDX generates a Keystore key with biometric-authentication-required, encrypts the keyfile content with it, and stores the ciphertext (app-private storage is fine — the security comes from the Keystore-gated key, not file location).
- The original plaintext keyfile is removed/overwritten, with a clear warning that this ties the wrapped keyfile to this specific device/Keystore and it can't be casually copied to another device afterward (same tradeoff as Android's existing Keystore-backed secrets generally).
- On each unlock requiring the keyfile, the app triggers a `BiometricPrompt` to authorize decryption in memory, rather than reading a plaintext file from disk.

### Describe alternatives you've considered:

- Storing the keyfile in app-private storage only (already possible) — protects against other apps reading it via shared storage, but not against anything running with root, a compromised backup, or Android's own backup/restore flow if not explicitly excluded.
- Full-device encryption — protects at-rest/offline theft but not a live compromised session, which is the threat this addresses.

### Additional context:

Happy to test on a device if a prototype build is available. I have raised this as a feature request in KeePassXC: https://github.com/keepassxreboot/keepassxc/issues/13637 and the same idea would be relevant and useful in other clients such as KeePass2Android and KeePassium (iOS)

(Disclosure: I used Claude AI to help draft this feature request - some of the deep technical content is a little beyond me ;-)

Contributor guide

Open the contributing guide

Research direction

No specific files or tests are named. Start by tracing KeePassDX's existing biometric Quick Unlock and keyfile-loading entry points, then determine how an opt-in Keystore-backed flow fits both; done means keyfile ciphertext is stored instead of plaintext and each required access uses biometric authorization without breaking existing keyfile unlocks.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
authentication, mobile-dev, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.