← Back to documentation

Security Model

Desktop-2FA is designed for offline, local storage of TOTP secrets. This is a summary of the project's published security documentation, not a guarantee against every threat.

Vault protection

  • AES-256-GCM provides authenticated encryption for vault contents.
  • Argon2id derives a key from the vault password. Published parameters: time cost 4, memory cost 128 MiB, parallelism 2.
  • zxcvbn evaluates passwords during interactive vault creation and password changes. By default, weak passwords trigger a warning and confirmation; configuration can reject them.
  • Vault access requires password authentication; the application does not rely on a persistent unlocked session.
  • Vault loading is limited to regular files of at most 10 MiB, and saves use atomic replacement.
  • Stale concurrent writes are refused under a short OS publication lock. Unknown payload versions and fields are rejected before rewriting; version 0.10.0 keeps the D2FA v1 format and cryptographic parameters unchanged.

What this does not protect against

Encryption does not protect a vault after it has been unlocked on a compromised device. Desktop-2FA cannot defend against malware or a compromised operating system, physical observation, or unsafe handling of exported backups. Keep your operating system and dependencies trusted, protect the device, and store backups securely.

Password and backup responsibilities

Interactive vault creation and password changes treat zxcvbn scores below 3 as weak. By default, the app warns and asks for confirmation; set security.reject_weak_passwords = true in ~/.config/d2fa/config.toml to reject them. Passwords supplied with --password or --password-file are not checked by this creation/change flow. Set security.warn_on_weak_existing_passwords = true to also warn during d2fa vault unlock, including when those options provide the password. --allow-weak-passwords or D2FA_ALLOW_WEAK_PASSWORDS=1 bypasses the interactive creation/change check.

In version 0.9.0, the public Python Vault.save() and Vault.load() API require an explicit, non-empty password. Vaults created by earlier API versions without a password cannot be opened through the 0.9.0 API. Before upgrading that API usage, use the previous release to open and re-save each such vault with a non-empty password. This does not affect vaults created through the normal CLI or Textual UI flows, which already require a non-empty password.

There is no password reset or recovery key. Backups are encrypted with the vault password; create them before upgrades and store them separately and securely. A backup is not a substitute for remembering the password.

Review the source

For the full threat analysis and cryptographic details, see the upstream security documentation. Report vulnerabilities privately to security@desktop-2fa.org; use the GitHub security page for security reporting guidance. For general questions and support, email contact@desktop-2fa.org.