一个面向桌面环境的安全、离线双因素认证(2FA)管理器。使用 Python 构建,具备强加密能力且不依赖云服务。
🌐 落地页:desktop-2fa.org
| 功能 | 描述 |
|---|---|
| 🔐 保险库安全 | 采用 AES-256-GCM 加密,并使用 Argon2id 进行密钥派生 |
| ⏱️ TOTP 生成 | 符合 RFC 6238 的验证码生成 |
| 💻 完整 CLI | 用于管理令牌的完整命令行界面 |
| 📋 剪贴板支持 | 自动将 TOTP 验证码复制到剪贴板 |
| 🔓 会话控制 | CLI 对每条命令进行身份验证;UI 在写入时重新验证,并在五分钟无输入后锁定 |
| 🛡️ 密码策略 | 使用 zxcvbn 强制执行可配置的密码强度要求 |
| 🧪 测试完善 | 回归测试包含 RFC 6238 测试向量和历史保险库测试夹具 |
| 📖 安全模型 | 详细的威胁分析与密码学设计文档 |
| 🖥️ Textual UI | 账户与保险库表单、实时 TOTP 倒计时和剪贴板操作(0.11.0) |
以下为 Desktop-2FA 0.10.0 的英文深色终端 CLI 截图,随后是 0.11.0 的 Textual UI。所有账户和凭据均为合成数据。 终端图像渲染的是实际命令输出;交互式提示使用测试 运行器,Textual 以无头模式运行。 参见截图说明与报告。
添加条目时不显示其密钥。
初始化保险库并列出合成账户。
人类可读、原始和 JSON 三种验证码输出格式。
加密导出、拒绝覆盖以及恢复到独立保险库。
Textual UI:实时验证码以及完整的账户/保险库操作。截图方法与限制。
pip install desktop-2fa
验证安装:
python -c "import desktop_2fa; print(desktop_2fa.__version__)"
# Output: 0.11.0
# Initialize a new vault
d2fa vault init
# Add a new TOTP token
d2fa add GitHub GitHub JBSWY3DPEHPK3PXP
# Or add a provisioning URI (quote it so the shell preserves '&')
d2fa add "otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA256&digits=8&period=60"
# List all entries
d2fa list
# Generate a code
d2fa code GitHub
默认情况下,保管库存储在 ~/.desktop-2fa/vault。可通过全局 --vault 选项为任意命令指定其他文件,或设置 DESKTOP_2FA_VAULT 以默认选择其他文件。显式指定的 --vault 优先于环境变量;若两者均未设置,则默认仍为 ~/.desktop-2fa/vault。
# Use a separate vault for this command
d2fa --vault ./development-vault list
# Show the currently selected vault path
d2fa --vault ./development-vault vault path
# Launch the Textual terminal UI with that vault
d2fa --vault ./development-vault ui
基于 URI 的添加会保留算法、位数和周期;省略的参数默认使用 SHA1、6 位数字和 30 秒。标签会进行百分号解码,并且 issuer 查询参数必须与任何 issuer 前缀一致。不受支持或相互矛盾的配置数据会在访问 vault 之前以状态码 6 退出。交互式添加也接受在 issuer 提示符处输入 URI,并跳过单独的 secret 提示符。URI 标签提供账户名称。
交互式 add 会在专用的 Secret 提示符处隐藏输入;名称和 issuer 保持可见。作为参数传递的 secret/URI 可能会出现在 shell 历史记录或进程检查中,而粘贴到可见 issuer 提示符中的 URI 可能会被回显。优先使用纯 issuer 名称加上隐藏的 secret 提示符,以避免这些暴露。参见交互式添加。
0.11.0 Textual UI 支持账户管理、vault 创建/解锁、加密导入/导出/备份以及密码更改。验证码会通过倒计时和有效性条自动刷新。使用 d2fa ui 启动;在未提供凭据的情况下,它会打开一个锁定屏幕。写入操作会再次要求输入密码;Ctrl+L 或五分钟无活动会锁定会话。参见 UI 指南。版本 0.10.0 包含较早的原型;请升级到 0.11.0 以使用这些账户和 vault 工作流。
# Provide password via command line
d2fa --password mypassphrase add GitHub GitHub JBSWY3DPEHPK3PXP
# Provide password via file
d2fa --password-file /path/to/passphrase.txt add GitHub GitHub JBSWY3DPEHPK3PXP
保险库是一个加密存储文件,默认位于
~/.desktop-2fa/vault;使用 --vault 或 DESKTOP_2FA_VAULT 可选择其他
路径。保险库文件必须是常规文件,且大小不超过 10 MiB。
当前加载器支持保险库格式版本 1。未来版本不保证 支持所有旧格式。升级之前,请创建加密 备份并将其安全存储。
Desktop-2FA 0.9.0 更改了公共 Python API:Vault.save() 和
Vault.load() 要求显式且非空的密码。由
早期 Python API 版本创建的无密码保险库,必须在升级前使用
上一版本以非空密码打开并重新保存。CLI 和
Textual UI 流程已经要求非空密码。
d2fa backup
新的 TOTP 密钥使用共享的 Base32 规则:接受 ASCII 大小写和空格,
正确的尾部填充是可选的,空解码密钥在访问保险库之前会被拒绝。新记录使用规范的大写填充文本,解码后的字节完全相同。现有密钥文本在加载/保存时保持不变。遗留的空密钥或历史上被接纳的 Unicode 折叠密钥仍可列出,但无法生成验证码;code 会报告 invalid_secret,状态码为 6。参见
显式修复流程。
在 CLI 中,只有 vault init、list 和 add 会创建缺失的保险库。其他内容命令
会报告保险库缺失错误。创建时:
--password/--password-file(非交互模式)list 创建一个空的加密保险库;add 创建一个包含已验证条目的保险库Vault created at <path>0.11.0 的 Textual UI 可以通过 Create vault 显式创建保险库, 并带有密码确认和针对现有目标的覆盖复选框。
当命令需要保险库且保险库存在时:
code 和 remove 命令以区分大小写的方式解析名称。精确的
account_name 匹配优先于其他条目的发行者。如果没有
精确的账户匹配,则接受唯一的发行者匹配以保持兼容性。
多个精确账户匹配或多个回退发行者匹配会被拒绝,
并报 Ambiguous entry 错误(退出状态码 6);保险库保持不变。
code --json 会报告 entry_ambiguous。Python 的 Vault.get_entry() 和
Vault.remove_entry(),以及公开的验证码/删除辅助函数,使用相同的规则;
有歧义的查找会抛出 desktop_2fa.vault.AmbiguousEntry,它是 ValueError 的子类。
rename 命令使用相同的精确账户名/唯一发行者规则,并在变更前
拒绝已占用的目标账户名。没有显式选择器时的歧义、无效选择器和已占用的
目标会以状态码 6 退出。账户名和发行者都会被更新;将唯一命名的
条目重命名为自身是允许的,并且仍会更新其发行者。
对于遗留的重复项,运行 d2fa list --indices,然后
使用显示的一基条目编号运行 d2fa rename OLD NEW --index N。
所选条目必须在普通查找会使用的账户名/发行者层级上与 OLD 匹配。
索引描述的是当前列表顺序,而非永久 ID;
在添加/删除条目后再次列出,并避免并发编辑保险库。
参见 重复项恢复。
| 命令 | 描述 |
|---|---|
d2fa add <name> <issuer> <secret> | 添加新的 TOTP 条目 |
d2fa list | 列出所有已存储的 TOTP 条目 |
d2fa rename <old> <new> | 重命名条目 |
d2fa remove <name> | 删除条目 |
d2fa code <name> [--copy|--copy-only] | 生成 TOTP 验证码,并支持复制到剪贴板选项 |
| 命令 | 描述 |
|---|---|
d2fa vault init [--force] | 初始化一个新的保险库(d2fa init-vault 是别名) |
d2fa vault unlock | 使用弱密码警告打开保险库(如果已配置) |
d2fa vault change-password | 更改保险库密码 |
d2fa vault path | 显示当前选定的保险库路径 |
d2fa backup | 创建保险库的加密备份 |
d2fa export <path> [--force] | 导出加密的 D2FA v1;现有文件需要 --force |
d2fa import <path> [--force] | 从文件导入保险库 |
d2fa ui | 启动 Textual 终端 UI |
外部格式的 Python 辅助工具在 适配器契约中描述;它们不是 CLI 导入模式。