Skip to content

Introduce master key encryption with OS-backed device key support#10

Closed
Zayan-Mohamed wants to merge 3 commits intopre-v2from
main
Closed

Introduce master key encryption with OS-backed device key support#10
Zayan-Mohamed wants to merge 3 commits intopre-v2from
main

Conversation

@Zayan-Mohamed
Copy link
Owner

This PR documents the security architecture change introduced in v2.0.0.

Before v2, vault encryption relied on a single password-derived key. This allowed offline brute-force attacks if a vault directory was stolen, because attackers could attempt to guess the password against encrypted data without any additional protection.

v2 introduces a layered key model:

  • A random master key is generated for each vault
  • The user password unlocks the master key via Argon2id
  • The master key encrypts a device-bound key
  • The device-bound key encrypts all vault data
  • The device key is stored in the OS keyring when available (macOS Keychain, Windows DPAPI, Linux Secret Service)

This binds a vault to the physical machine, making offline attacks against stolen vault files infeasible without access to both the password and the original device.

A graceful fallback is provided when OS keyring storage is unavailable, allowing password-only operation when required for portability.

Security impact:

  • Vault files copied off a device cannot be decrypted without the device key
  • Password guessing alone is no longer sufficient
  • Metadata and file contents remain encrypted at rest

This PR exists to provide a formal design and review trail for the v2.0.0 security upgrade, which was previously merged directly into main.

Closes #2

Signed-off-by: Zayan-Mohamed <itsm.zayan@gmail.com>
Release v2.0.0: Master key encryption model with recovery key support
Merge pull request #8 from Zayan-Mohamed/main
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant