constant-time-analysis

constant-time-analysis 快速入门

Trail of Bits 出品的密码学代码侧信道检测 Skill,帮 AI 在写加密代码时主动消除”时间差”暴露的密钥风险。

这是什么?解决什么问题?

constant-time-analysis 是 Trail of Bits skills 仓库中专门针对密码学侧信道(Side-Channel)的 Skill。它关注一个很具体的场景:即使你的加密算法逻辑上正确,只要代码执行时间随密钥/数据变化,攻击者就能通过计时差异反推出密钥。这正是 2018 年 Spectre/Meltdown 之后行业最关心的”恒定时间(Constant-Time)“编程范式。

这个 Skill 重点支持 C 与 Rust,内置了 RustCrypto 实战指引。对小白来说,它解决的是”我抄了一段 AES 代码,逻辑看着对,但时间上不安全”的尴尬。Skill 会扫描代码,提示你把分支、查表、内存访问都换成与输入无关的实现。

准备工作

• 支持 Agent:Claude Code(主推)。
• 运行环境:Rust 1.70+(分析 Rust 项目);GCC/Clang(分析 C 项目);可选工具 dudect、ctgrind。
• 目标项目:一个含加密代码的 Rust/C 仓库,比如用了 aes、chacha20poly1305、libsodium 绑定的项目。
• 理论基础:理解”时间侧信道”基本概念即可,不需要密码学博士。

3 步快速上手

第 1 步:获取 Skill

git clone https://github.com/trailofbits/skills.git
cp -r skills/constant-time-analysis ~/.claude/skills/

第 2 步:在 Claude Code 中调用

cd your-crypto-rs-project
claude

发起评审:

请用 constant-time-analysis Skill 审查 src/aes_gcm.rs,重点检查密钥比较、MAC 验证、查表访问是否恒定时间。

AI 会按 Trail of Bits 的 constant-time 编程规范逐条评估,并指出具体行号与修改建议(比如把 if a == b 换成 subtle::ConstantTimeEq)。

第 3 步:本地工具二次验证

# 用 dudect 跑统计性侧信道测试
cargo install dudect-bencher
cargo test

把 AI 给的”应该恒定时间”的函数喂给 dudect 跑一下,获得量化数据。

常见踩坑

1. 编译器优化”洗掉”了恒定时间:-O0 编译下看似恒定,-O2 后被优化成早退分支。用 ctgrind 或 valgrind --tool=memcheck 验证。
2. 误用 == 比较密钥或 MAC:mem::eq 不一定恒定时间,必须用 subtle::ConstantTimeEq 或 crypto_secretbox_open。
3. 依赖第三方 crate 但不查其安全性:aes crate 自身是恒定时间的,但你外面包一层 if first_block { ... } 就不安全了。Skill 会揪出这类”组合漏洞”。
4. 忽略 cache 命中差异:即使代码层面无分支,数组索引随 key 变化也会导致 cache 命中时间不同,这种深层问题需要 dudect 这类工具验证。
5. 把”逻辑正确”等同于”安全”:密码学代码要双重检查,Skill 就是做这层检查的。
6. 没启用栈清零:Skill 还会顺带提示敏感数据在用完后是否清零,配合 zeroize-audit Skill 使用更佳。

初级用法

• 新增加密函数前评审:写完 verify_tag、decrypt 这类函数,跑一次 Skill 评审。
• 代码 review checklist:把 Skill 输出整理成团队 review checklist,每次 PR 必查。
• 学习范式:阅读 Skill 内置的 examples/ 目录,看正确/错误对比,快速建立肌肉记忆。

高级玩法

• CI 卡门禁:把 Skill 评审 + dudect 接入 GitHub Actions,发现非恒定时间代码直接 fail PR。
• 自建规则集:在 Skill 基础上扩展,把团队”禁用 API 列表”(如 memcmp)固化为额外检查项。
• 配合 zeroize-audit:两个 Skill 联动,既防时间泄漏又防内存残留,覆盖密码学代码完整生命周期。

小技巧

• Skill 给的”修复建议”里如果推荐 subtle crate,记得加 subtle = "2" 到 Cargo.toml。
• 跑 dudect 时把样本量调到 10 万以上,小样本易误判。
• 编译器开 -O2 + ctgrind,比裸运行更能发现真实侧信道。
• 关注 Trail of Bits 博客的 “constant-time” 标签页,定期有新模式补充。
• 不要自己写底层 constant-time 原语,优先用经过审计的 crate(AES-GCM、ChaCha20-Poly1305)。

常见问题 FAQ

Q1: 这个 Skill 跟 constant-time-analysis 有什么关系?必须装吗? A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他? A: constant-time-analysis 来自 TrailOfBits,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗? A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了? A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗? A: constant-time-analysis 来自 trailofbits/skills 仓库,许可证为 CC-BY-SA-4.0。商用前请确认该许可证是否满足你的需求。

参考链接

• 官方仓库
• 该 Skill 目录
• Trail of Bits 博客
• dudect 工具
• RustCrypto 项目
• subtle crate

密码学侧信道的真实危害

时间侧信道听起来很学术,但在生产环境已经造成过多次真实事故。2018 年 Spectre 和 Meltdown 漏洞就是利用 CPU 推测执行的计时差异泄漏数据。RSA 密钥生成如果用了不恒定时间的代码,攻击者通过网络请求的响应时间就能反推出私钥。

恒定时间编程范式是密码学库作者的”基本功”,但很多业务开发者并不熟悉。Trail of Bits 这个 Skill 做的就是把这套规范普及给所有写加密代码的人。

进一步阅读

• Trail of Bits 博客有大量关于侧信道的文章,特别是 “Side-Channel Attacks” 标签页。
• dudect 工具(oreparaz/dudect)是学术界验证 constant-time 的标准工具,推荐集成到 CI。
• ctgrind 是 Valgrind 的扩展,能检测编译器优化带来的早退分支。
• RustCrypto 项目维护了 constant_time_eq crate,是 Rust 生态的标准做法。
• 著名的攻击案例:OpenSSL 的 Lucky 13 攻击、CVE-2013-0169,都是时间侧信道漏洞。

实战建议

1. 新增加密函数前必跑:写完 verify_tag、decrypt 这类函数,跑一次 Skill 评审。
2. 代码 review checklist:把 Skill 输出整理成团队 review checklist,每次 PR 必查。
3. 学习范式:阅读 Skill 内置的 examples/ 目录,看正确/错误对比,快速建立肌肉记忆。
4. CI 卡门禁:把 Skill 评审 + dudect 接入 GitHub Actions,发现非恒定时间代码直接 fail PR。
5. 自建规则集:在 Skill 基础上扩展,把团队”禁用 API 列表”(如 memcmp)固化为额外检查项。
6. 配合 zeroize-audit:两个 Skill 联动,既防时间泄漏又防内存残留,覆盖密码学代码完整生命周期。

产品特性

本 Skill 的核心能力可归纳为以下六个维度:

1. 恒定时间审计

   • 扫描分支、查表、内存访问三类侧信道
   • 识别密钥比较漏洞,建议 subtle::ConstantTimeEq

2. RustCrypto 指引

   • 内置 AES、ChaCha20 等原语的恒定时间写法
   • 覆盖 RustCrypto 生态最佳实践

3. 组合漏洞检测

   • 揪出”原语恒定但外层套 if”的组合漏洞
   • 弥补 dudect 运行时工具盲区

4. 多 Agent 兼容

   • Claude Code marketplace 协议原生支持
   • Codex 兼容层加载,Cursor/Windsurf 可用

5. CI 集成

   • pre-commit hook + GitHub Actions
   • PR 阶段拦截非恒定时间代码

6. 栈清零联动

   • 提示敏感数据用后清零
   • 配合 zeroize-audit 覆盖完整生命周期

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。