wcdb-key-tool README

The project's README from github.com/TANGandXUE/wcdb-key-tool. As one markdown file: README.md.

wcdb-key-tool

微信数据库（WCDB / SQLCipher4）密钥提取工具，覆盖 Linux / macOS / Windows 三个平台。

Extract WeChat (WCDB/SQLCipher4) database encryption keys — Linux, macOS and Windows.

本仓库只做一件事：把从微信自己的进程里，合法地取出自己账号数据库密钥这件事的 思路和代码公开出来，不做采集、不做批量、不接触任何服务器通信。

背景 / Background

微信 4.1+ 版本不再在进程内存中缓存明文数据库密钥（raw key），而是只保留一个 passphrase，真正的加密密钥需要再做一轮很慢的密码学运算才能算出来。这导致所有 基于内存模式扫描（x'<hex>'）的老工具全部失效。

WeChat 4.1+ no longer caches the raw database encryption key in process memory — only a passphrase remains, from which the real key must be derived. This breaks every existing tool that relies on x'<hex>' memory pattern scanning.

兼容性 / Compatibility

平台 微信 4.0.x（老版本） 微信 4.1+（新版本）
Linux ✅ 内存扫描 ✅ GDB 断点 + PBKDF2 派生（已验证）
macOS ✅ 内存扫描 ✅ LLDB 断点 + PBKDF2 派生（已验证）
Windows ✅ 内存扫描 ✅ 运行时 Config.Cipher 只读扫描 + PBKDF2（已验证）

核心原理 / How It Works

三个平台最终都是同一套密码学逻辑，只是"怎么从微信进程里把原料弄出来"这一步不同：

  1. 拿到密钥原料（三条路线，按微信版本二选一）

    • 老版本：微信自己把 raw key + salt 拼成十六进制字符串，明文缓存在进程内存里， 直接内存扫描就能拿到。
    • 新版本：内存里只剩 passphrase，拿不到直接能用的密钥，得走第 2 步。
    • 新版本的 passphrase 只在微信登录时做一次计算，之后就常驻内存不会重复计算， 所以要抓这一刻，得用调试器在这次计算发生的地方下断点，逼用户退出登录再重新 登录来触发一次新的计算，从函数参数寄存器里把 passphrase 读出来。
      • Linux：微信 Linux 二进制没有暴露可用的系统符号，只能用 ELF 静态分析（在 .rodata 里找 WCDB 特征字符串，顺着交叉引用找到处理密钥的函数入口）， 再用 GDB 在这个地址上断点。（elf_analyzer.py + gdb_capture.py，已在 真机验证）
      • macOS：微信直接调用了苹果系统自带的 CommonCrypto 库做密钥派生，这是一个 公开的系统符号，不需要逆向微信自己的二进制，直接用 LLDB 断在 CCKeyDerivationPBKDF 上就行。（lldb_capture.py，已在真机验证 18/18）
    • Windows：主路径是只读运行时扫描。微信 4.1+ 会把可用的 Config.Cipher 相关对象留在进程内存里，脚本先定位这个对象，再解码候选 x'<64hex key><32hex salt>' 片段并用 HMAC 校验；老版本继续走内存扫描。 capture-experimental 仍保留为研究性备用路线，不是主路径。

  2. PBKDF2 派生每个库的真实密钥：拿到 passphrase 后，对每个数据库文件，用它 自己的 16 字节 salt 做 PBKDF2-HMAC-SHA512（256,000 轮迭代），算出这个库专属 的 32 字节 AES-256 密钥。

  3. HMAC 校验：派生出密钥后不能直接信，要用密钥对数据库第一页做 HMAC-SHA512 校验，跟数据库自己存的 HMAC 对上了，才说明这把密钥真的对。 这一步是三个平台通用的"防止抓错"的安全网，也是判断运行时扫描或备用方案 有没有真的成功的唯一标准——命中了不代表读到的就是对的东西，HMAC 校验通过 才算数。

  4. AES-256-CBC 逐页解密：还原出标准 SQLite 文件。

安装 / Install

单文件即可运行，无需 pip install 任何第三方库（三个平台都是直接调用系统自带的 加密库：Linux 走 OpenSSL、macOS 走 CommonCrypto、Windows 走 CNG）。

# Linux
sudo apt install gdb

# macOS
xcode-select --install   # 提供 lldb

# Windows
# 老版本内存扫描 / 新版 runtime 扫描都不需要额外依赖
# capture-experimental 只在你要测试研究性路线时需要 cdb.exe

使用 / Usage

# Linux
sudo python3 wcdb_key_tool.py extract --decrypt

# macOS（首次需要先对微信重签名去掉 Hardened Runtime，见脚本内 Prerequisite）
sudo codesign --force --deep --sign - /Applications/WeChat.app
sudo python3 wcdb_key_tool_macos.py extract --decrypt

# Windows（优先：新版 runtime 扫描；老版本会自动回退到内存扫描）
python3 wcdb_key_tool_windows.py extract --decrypt

# Windows（研究性备用路线，非主路径）
python3 wcdb_key_tool_windows.py capture-experimental

首次提取都需要在微信里退出登录再重新登录一次（这是为了触发密钥的重新计算， 断点才有机会命中）；抓到的 passphrase 会缓存下来，之后就不用重复这一步了。

Windows 新版：runtime Config.Cipher 扫描

Windows 4.1+ 的主路径已经改成只读运行时扫描，不再依赖实验性断点猜测。脚本先在 进程里定位 com.Tencent.WCDB.Config.Cipher 相关对象，解码出候选 x'<key><salt>' 片段，再用数据库 HMAC 验证；若扫不到，再自动回退到老版本 内存扫描。

capture-experimental 仍保留为研究性备用命令，默认不影响 extract。

安全说明 / Security Notes

FAQ

Q: 会不会封号？ A: 不会。工具只在密钥计算瞬间读一次内存/寄存器值，整个过程很短，不修改任何程序 行为，不接触微信服务器通信。

Q: passphrase 存在哪里？ A: 存储在 ~/.wcdb-key-tool/wechat-passphrase.json（权限 600），仅当前用户可读， 三个平台通用这一个路径。

Q: 为什么 Linux/macOS 需要 sudo？ A: GDB / LLDB 需要 ptrace（macOS 上是 task_for_pid）权限来附加到其他进程的 内存空间。Linux 也可以用 echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope 临时放开权限（重启后恢复），不用每次都 sudo。

Q: 微信更新后还能用吗？ A: Linux 大概率可以——ELF 静态分析通过字符串交叉引用定位函数，只要微信继续使用 WCDB 的 com.Tencent.WCDB.Config.Cipher 字符串，就能自动适配。macOS 断的是苹果 系统函数，跟微信自己的版本无关，理论上更稳定，但微信升级后可能需要重新对 App 执行一次重签名（Hardened Runtime 被系统还原后 task_for_pid 会失败）。

致谢 / Credits

License

MIT — see LICENSE

wcdb-key-tool (TANGandXUE/wcdb-key-tool)

Searching Database…

651 ·GitHub
Wcdb-key-tool
这是干什么的？一个功能单一的 Python 小工具，能在 Linux、macOS 和 Windows 上从微信本地的 WCDB/SQLCipher4 聊天数据库里提取密钥，这样你就可以解密自己的聊天记录。
这是图形界面程序还是命令行脚本？只有命令行：三个独立的 Python 脚本，每个平台一个——Linux 用 wcdbkeytool.py，macOS 和 Windows 分别用 wcdbkeytoolmacos.py 和 wcdbkeytoolwindows.py。
怎么把它跑起来？下载适合你系统的脚本，用 Python 3 运行就行——没有安装步骤，也不用 pip 装任何东西。
除了 Python 之外还需要装别的东西吗？不需要任何第三方库：脚本直接调用各系统自带的加密组件——Linux 上是 OpenSSL，macOS 上是 CommonCrypto，Windows 上是 CNG。
它对最新版的微信也好使吗，还是有什么坑？新旧版微信都能对付，但 4.1 及以上版本需要先退出登录再重新登录一次，好让调试器捕捉到口令的推导过程；另外在 Linux/macOS 上为了获得 ptrace 权限，还得用 sudo 运行。
支持哪些平台？Linux、macOS 和 Windows。每个平台都有针对微信 4.0.x 的路径（内存扫描）和针对 4.1+ 的路径（GDB、LLDB 或运行时扫描加 PBKDF2），都标注为已在真实机器上验证过。
微信更新以后它还能继续用吗？这正是它最大的卖点：在 Linux 上通过分析二进制文件的 ELF 静态结构来重新定位密钥函数；macOS 上直接在苹果自己的 CCKeyDerivationPBKDF 上设断点，所以跟微信的版本无关；Windows 则回退到传统的内存扫描——不过 macOS 升级之后，应用可能需要重新签名。
拿到口令之后，它实际做了什么？对每个数据库，它用文件自带的 16 字节盐值跑 256,000 次迭代的 PBKDF2-HMAC-SHA512，得到一个 32 字节的 AES-256 密钥，再用 HMAC 校验第一页来验证密钥是否正确，然后逐页解密 AES-256-CBC，最后生成一个标准的 SQLite 文件。
为什么 Linux 上要做 ELF 静态分析？因为 Linux 版微信的二进制文件里没有可用的符号，所以工具只能在 .rodata 段里搜索 com.Tencent.WCDB.Config.Cipher 这类 WCDB 特征字符串，顺着交叉引用找到处理密钥的函数，然后在那里下一个 GDB 断点。
为什么以前那些微信密钥工具都用不了了？微信 4.1 及以上版本不再把原始密钥缓存在进程内存里，只剩下口令，所以传统的内存特征扫描什么都找不到。这个工具改成了在口令推导的那一刻把它截获，再用 PBKDF2 推导出真正的密钥。
What are similar projects?awesome-reverse-engineering, reverse-engineering, ghidra-mcp, pwndbg, vol-rs, ablation, Detect-It-Easy, binwalk
Which topics is it in?forensics, data-extraction, binary-analysis, cryptography, low-level, messaging, wechat, debugging, static-analysis, reverse-engineering, encryption, security-tools
Creator
TANGandXUE
Size
<0.1 MB
Stars
651
Updated
CommitAug 04
Age
5mo
Commits · 90 Days