Amazevault 是一款专注于本地安全的桌面密码管理器

系列文章目录

Amazevault 是一款专注于本地安全的桌面密码管理器
AmazeVault 核心功能分析，认证、安全和关键的功能
AmazeVault 快速开始，打造个人专属桌面密码管理器

---

项目概述

Amazevault 是一款专注于本地安全的桌面密码管理器，其核心设计哲学是“无云、纯本地、高安全”。它旨在为用户提供一个完全掌控自己数据的解决方案，避免了将敏感信息上传至云端所带来的隐私泄露风险。

核心目标

项目的核心目标是提供一个高安全性、离线可用、用户可控的密码存储解决方案。它不依赖任何网络服务或云同步，所有数据（包括密码库、设置和日志）都存储在用户本地的data/目录下，确保了数据的绝对私密性。

目标用户群体

• 技术爱好者：欣赏其开源、透明的架构和现代的加密技术。
• 隐私倡导者：不信任云服务，希望完全掌控自己的数据。
• 需要离线访问的用户：在没有网络连接的环境下也能安全地管理密码。

使用场景与优势

• 离线可用性：由于数据完全本地化，用户可以在任何没有网络连接的环境下使用，非常适合在飞机上或保密网络中工作。
• 端到端加密：从解锁到数据存储，整个流程都由强大的加密算法保护，即使设备丢失，攻击者也难以破解数据。
• 跨平台支持：基于Python和PySide6开发，理论上可以在Windows、macOS和Linux上运行。

主要功能特性

• 5×5点阵图形解锁：使用鼠标或触控板绘制图形进行解锁，支持轨迹高亮和撤销操作。
• 强大的加密存储：使用Argon2id密钥派生函数和AES-256-GCM加密算法保护数据。
• 密码条目管理：支持对密码条目进行增、删、改、查（CRUD）操作。
• 分类与标签支持：用户可以为密码条目创建分类和标签，以便更好地组织和管理。
• 安全剪贴板：复制密码等敏感信息后，会在设定的时间（默认6秒）后自动清空剪贴板，防止信息被其他程序窃取。
• TOTP双因素认证集成：支持生成和管理TOTP（基于时间的一次性密码）验证码。
• 数据备份与恢复：支持导出加密的备份文件，并可通过恢复密钥在忘记图形时重置。
• 锁定策略：支持连续错误尝试后的延迟锁定，以及最小化或失去焦点后的自动锁定。

功能详解

应用启动流程

应用程序的启动入口是run.py文件，它非常简洁，仅调用amazevault.main模块中的main()函数。真正的初始化逻辑在amazevault/main.py中。

5×5点阵图形解锁控件

PatternLockWidget是实现图形解锁的核心UI组件，位于ui/widgets/pattern_lock_widget.py。它继承自QtWidgets.QWidget，并实现了完整的交互逻辑。

关键特性分析：

• 数据结构：使用List[Tuple[int, int]]存储路径点的坐标，Set[Tuple[int, int]]记录已访问的节点，防止重复（除非在设置中允许）。

• 事件处理：

  • mousePressEvent: 开始绘制，记录第一个点。
  • mouseMoveEvent: 在拖动过程中，实时计算鼠标位置对应的网格节点，并将其添加到路径中。
  • mouseReleaseEvent: 结束绘制，发出sequenceFinished信号。
  • keyPressEvent: 支持退格键（Backspace）来撤销上一个节点。

• 序列化：sequence()方法将二维坐标(r, c)转换为一维索引r * cols + c，并以逗号分隔的字符串形式返回，便于存储和验证。

• 视觉效果：实现了流畅的动画效果，包括连线的光效流动和验证失败时的抖动反馈，提升了用户体验。

# 位于 Amazevault /ui/widgets/pattern_lock_widget.py
def sequence(self) -> str:
    res = []
    for (r, c) in self.path:
        res.append(str(r * self.cols + c))
    return ",".join(res)

AES-256-GCM加密模块

AesGcmBox类是项目中负责对称加密的核心，位于crypto/aesgcm.py。它封装了cryptography库的AESGCM功能，提供了简单易用的接口。

实现细节：

• 构造函数：接受一个key（字节串），并检查其长度是否为16、24或32字节（分别对应AES-128, 192, 256）。项目中使用256位（32字节）密钥。
• 加密：encrypt()方法生成一个12字节的随机nonce，使用AESGCM对象进行加密，返回的密文格式为[nonce][ciphertext||tag]。
• 解密：decrypt()方法从输入的blob中分离出nonce和密文+认证标签，然后进行解密。如果输入为空，则返回空字节串。
• 文本加解密：提供了encrypt_text和decrypt_to_text方法，方便对字符串进行加解密，内部会自动处理UTF-8编码。

# 位于 Amazevault /crypto/aesgcm.py
def encrypt(self, plaintext: bytes, aad: Optional[bytes] = None) -> bytes:
    nonce = os.urandom(12)
    aes = AESGCM(self._key)
    ct = aes.encrypt(nonce, plaintext, aad)
    return nonce + ct  # [12B nonce][ciphertext||tag]

Argon2id密钥派生函数

derive_master_key函数负责将用户绘制的图形序列（作为密码）和一个随机盐值（salt）派生出一个256位的主密钥（master key），位于crypto/kdf.py。

实现细节：

• 参数：使用Argon2Params数据类定义了派生参数，默认为time_cost=3, memory_cost_kib=65536（64 MiB）, parallelism=2, hash_len=32（256位）。
• 调用：函数内部调用argon2.low_level.hash_secret_raw，传入密码（图形序列的UTF-8编码）、盐值和参数，返回派生出的密钥。
• 用途：这个派生出的主密钥是整个密码库的“根密钥”，用于加密和解密所有敏感的密码条目。

# 位于 Amazevault /crypto/kdf.py
def derive_master_key(secret: bytes, salt: bytes, params: Argon2Params) -> bytes:
    return hash_secret_raw(
        secret,
        salt,
        time_cost=params.time_cost,
        memory_cost=params.memory_cost_kib,
        parallelism=params.parallelism,
        hash_len=params.hash_len,
        type=Type.ID, # 指定使用 Argon2id
    )

SQLite数据库存储与访问

Repository类是项目的数据访问层（DAL），位于models/repository.py。它负责与SQLite数据库进行交互，执行所有数据的增删改查操作。

数据库结构： 数据库文件位于./data/vault.db。核心表结构如下：

• entries: 存储密码条目。关键设计：title, url, notes, custom_json等字段以明文存储，而username_ct, password_ct, phone_ct, email_ct等敏感字段则存储AES-GCM加密后的密文（BLOB类型）。
• categories: 存储分类信息。
• tags 和 entry_tags: 实现多标签功能。
• meta: 存储数据库的元信息，如schema_version。
• entry_tokens: 用于实现“盲索引”搜索，存储从条目内容派生出的、不可逆的搜索令牌。
• entries_fts: 一个FTS5（全文搜索）虚拟表，用于实现高效的全文搜索。

初始化流程： _ensure_schema()方法负责创建数据库表和索引。它会检查meta表是否存在来判断是否为新数据库，并创建所有必需的表。如果检测到数据库文件损坏或为旧版（SQLCipher），会自动进行备份和重建。

系统架构与数据流

Amazevault 采用经典的MVC（Model-View-Controller）架构模式，各层职责分明。

数据流示例（解锁并查看条目）：

1. 用户输入：用户在UnlockView中绘制图形。
2. 控制器验证：AuthController接收图形序列，使用derive_master_key函数派生密钥，并与存储的哈希值进行比对。
3. 数据访问：验证成功后，AuthController持有主密钥。AppController通过Repository查询entries表。
4. 解密数据：Repository使用主密钥和AesGcmBox对username_ct和password_ct等密文字段进行解密。
5. 更新视图：解密后的明文数据被传递给MainWindow，并在UI上显示给用户。

安全机制详解

Amazevault 通过多层安全机制来保护用户数据：

1. 物理隔离：数据完全存储在本地，不与任何外部服务器通信，从根本上杜绝了云端数据泄露的风险。
2. 强密钥派生：使用Argon2id算法，该算法是密码哈希竞赛的获胜者，具有很高的抗暴力破解和抗硬件加速破解的能力。其高内存消耗（64 MiB）使得使用GPU或ASIC进行大规模破解变得非常困难。
3. 现代加密算法：使用AES-256-GCM进行加密，这是一种经过广泛验证的、安全的认证加密模式，既能保证机密性，也能保证完整性。
4. 安全实践：
   • 盐值（Salt）：每个用户的密钥派生都使用唯一的随机盐值，防止彩虹表攻击。
   • 自动清空剪贴板：防止敏感信息在剪贴板中长时间驻留。
   • 锁定策略：防止暴力破解图形解锁。
   • 恢复密钥：为用户提供了一种在忘记图形时恢复数据的途径，但恢复密钥本身也经过了二次加密保护。

依赖分析

项目的主要依赖项在requirements.txt和README.md中有明确说明。

• PySide6: 用于构建跨平台的桌面GUI应用。
• cryptography: 提供了AESGCM等核心加密原语。
• argon2-cffi: 提供了Argon2id密钥派生函数的Python绑定。
• platformdirs: 用于确定用户数据目录（如data/）在不同操作系统上的标准位置。

使用与部署

快速开始（开发运行）

1. 安装依赖：pip install -r requirements.txt
2. 启动应用：python run.py
3. 首次运行：按照向导设置5×5图形解锁，并妥善保存生成的恢复密钥。

打包

项目提供了打包脚本（如packaging/build_windows.bat），使用PyInstaller将Python应用打包成独立的可执行文件，方便分发。