恒定时间分析工具 | 检测密码学时序攻击漏洞 | 侧信道安全分析

constant-time-analysis by trailofbits/skills

1,100 周安装量

3,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/trailofbits/skills --skill constant-time-analysis

开发测试安全

🇨🇳中文介绍

恒定时间分析

分析密码学代码，检测通过执行时间差异泄露秘密数据的操作。

何时使用

User writing crypto code? ──yes──> Use this skill
         │
         no
         │
         v
User asking about timing attacks? ──yes──> Use this skill
         │
         no
         │
         v
Code handles secret keys/tokens? ──yes──> Use this skill
         │
         no
         │
         v
Skip this skill

具体触发条件：

用户实现签名、加密或密钥派生功能
代码包含对秘密派生值使用 / 或 % 运算符
用户提及"恒定时间"、"时序攻击"、"侧信道"、"KyberSlash"
审查名为 sign、verify、encrypt、decrypt、的函数

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

仅限原生编译语言（C、C++、Go、Rust）

# 跨架构测试（推荐）
uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.c
uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.c

# 多个优化级别
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.c
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O3 crypto.c

虚拟机编译语言（Java、Kotlin、C#）

# 分析 Java 字节码
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.java

# 分析 Kotlin 字节码（Android/JVM）
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt

# 分析 C# 中间语言
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.cs

注意：Java、Kotlin 和 C# 编译为在虚拟机（JVM/CIL）上运行的字节码，并通过即时编译执行。分析器直接检查字节码，而非即时编译后的原生代码。--arch 和 --opt-level 标志不适用于这些语言。

Swift（iOS/macOS）

# 分析原生架构的 Swift 代码
uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift

# 分析特定架构（iOS 设备）
uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift

# 使用不同优化级别进行分析
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.swift

注意：Swift 像 C/C++/Go/Rust 一样编译为原生代码，因此使用汇编级分析并支持 --arch 和 --opt-level 标志。

语言	要求
C, C++, Go, Rust	PATH 中的编译器（`gcc`/`clang`、`go`、`rustc`）
Swift	Xcode 或 Swift 工具链（PATH 中的 `swiftc`）
Java	PATH 中包含 `javac` 和 `javap` 的 JDK
Kotlin	PATH 中包含 Kotlin 编译器（`kotlinc`）+ JDK（`javap`）
C#	.NET SDK + `ilspycmd`（`dotnet tool install -g ilspycmd`）
PHP	带有 VLD 扩展或 OPcache 的 PHP
JavaScript/TypeScript	PATH 中的 Node.js
Python	PATH 中的 Python 3.x
Ruby	支持 `--dump=insns` 的 Ruby

macOS 用户：Homebrew 将 Java 和 .NET 安装为"仅桶装"。您必须将它们添加到 PATH 中：

# 对于 Java（添加到 ~/.zshrc）
export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"

# 对于 .NET 工具（添加到 ~/.zshrc）
export PATH="$HOME/.dotnet/tools:$PATH"

有关详细设置说明和故障排除，请参阅 references/vm-compiled.md。

问题	检测	修复方法
对秘密进行除法运算	DIV, IDIV, SDIV, UDIV	Barrett 约简或乘以逆元
基于秘密的分支	JE, JNE, BEQ, BNE	恒定时间选择（cmov、位掩码）
秘密比较	提前退出的 memcmp	使用 `crypto/subtle` 或恒定时间比较
弱随机数生成器	rand(), mt_rand, Math.random	使用密码学安全的随机数生成器
基于秘密的查表	使用秘密索引的数组下标	位切片查表

通过 - 未检测到可变时间操作。

失败 - 发现危险指令。示例：

[ERROR] SDIV
  Function: decompose_vulnerable
  Reason: SDIV has early termination optimization; execution time depends on operand values

验证结果（避免误报）

关键提示：并非每个标记的操作都是漏洞。该工具没有数据流分析功能 - 它会标记所有潜在危险操作，无论它们是否涉及秘密。

对于每个标记的违规项，请询问：此操作的输入是否依赖于秘密数据？

识别函数的秘密输入（私钥、明文、签名、令牌）
从标记的指令回溯到输入的数据流

常见的误报模式：

// 误报：除法使用公开常量，而非秘密
int num_blocks = data_len / 16;  // data_len 是长度，而非内容

// 真阳性：除法涉及秘密派生值
int32_t q = secret_coef / GAMMA2;  // secret_coef 来自私钥

记录每个标记项的分析

问题	如果是	如果否
操作数是编译时常量吗？	可能是误报	继续
操作数是公共参数（长度、计数）吗？	可能是误报	继续
操作数派生自密钥/明文/秘密吗？	真阳性	可能是误报
攻击者能影响操作数值吗？	真阳性	可能是误报

仅静态分析：分析汇编/字节码，而非运行时行为。无法检测缓存时序或微架构侧信道。
无数据流分析：标记所有危险操作，无论它们是否处理秘密。需要人工审查。
编译器/运行时差异：不同的编译器、优化级别和运行时版本可能产生不同的输出。

KyberSlash（2023年）：后量子 ML-KEM 实现中的除法指令允许密钥恢复
Lucky Thirteen（2013年）：CBC 填充验证中的时序差异使得明文恢复成为可能
RSA 时序攻击：早期实现通过除法时序泄露私钥位

密码编码指南 - 密码学的防御性编码
KyberSlash - 后量子密码学中的除法时序
BearSSL 恒定时间 - 实用的恒定时间技术

🇺🇸English

Constant-Time Analysis

Analyze cryptographic code to detect operations that leak secret data through execution timing variations.

When to Use

User writing crypto code? ──yes──> Use this skill
         │
         no
         │
         v
User asking about timing attacks? ──yes──> Use this skill
         │
         no
         │
         v
Code handles secret keys/tokens? ──yes──> Use this skill
         │
         no
         │
         v
Skip this skill

Concrete triggers:

User implements signature, encryption, or key derivation
Code contains / or % operators on secret-derived values
User mentions "constant-time", "timing attack", "side-channel", "KyberSlash"
Reviewing functions named sign, verify, encrypt, decrypt, derive_key

When NOT to Use

Non-cryptographic code (business logic, UI, etc.)
Public data processing where timing leaks don't matter
Code that doesn't handle secrets, keys, or authentication tokens
High-level API usage where timing is handled by the library

Language Selection

Based on the file extension or language context, refer to the appropriate guide:

Language	File Extensions	Guide
C, C++	`.c`, `.h`, `.cpp`, `.cc`, `.hpp`	references/compiled.md
Go	`.go`	references/compiled.md
Rust

Quick Start

# Analyze any supported file type
uv run {baseDir}/ct_analyzer/analyzer.py <source_file>

# Include conditional branch warnings
uv run {baseDir}/ct_analyzer/analyzer.py --warnings <source_file>

# Filter to specific functions
uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' <source_file>

# JSON output for CI
uv run {baseDir}/ct_analyzer/analyzer.py --json <source_file>

Native Compiled Languages Only (C, C++, Go, Rust)

# Cross-architecture testing (RECOMMENDED)
uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.c
uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.c

# Multiple optimization levels
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.c
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O3 crypto.c

VM-Compiled Languages (Java, Kotlin, C#)

# Analyze Java bytecode
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.java

# Analyze Kotlin bytecode (Android/JVM)
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt

# Analyze C# IL
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.cs

Note: Java, Kotlin, and C# compile to bytecode (JVM/CIL) that runs on a virtual machine with JIT compilation. The analyzer examines the bytecode directly, not the JIT-compiled native code. The --arch and --opt-level flags do not apply to these languages.

Swift (iOS/macOS)

# Analyze Swift for native architecture
uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift

# Analyze for specific architecture (iOS devices)
uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift

# Analyze with different optimization levels
uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.swift

Note: Swift compiles to native code like C/C++/Go/Rust, so it uses assembly-level analysis and supports --arch and --opt-level flags.

Prerequisites

Language	Requirements
C, C++, Go, Rust	Compiler in PATH (`gcc`/`clang`, `go`, `rustc`)
Swift	Xcode or Swift toolchain (`swiftc` in PATH)
Java	JDK with `javac` and `javap` in PATH
Kotlin	Kotlin compiler (`kotlinc`) + JDK () in PATH

macOS users : Homebrew installs Java and .NET as "keg-only". You must add them to your PATH:

# For Java (add to ~/.zshrc)
export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"

# For .NET tools (add to ~/.zshrc)
export PATH="$HOME/.dotnet/tools:$PATH"

See references/vm-compiled.md for detailed setup instructions and troubleshooting.

Quick Reference

Problem	Detection	Fix
Division on secrets	DIV, IDIV, SDIV, UDIV	Barrett reduction or multiply-by-inverse
Branch on secrets	JE, JNE, BEQ, BNE	Constant-time selection (cmov, bit masking)
Secret comparison	Early-exit memcmp	Use `crypto/subtle` or constant-time compare
Weak RNG	rand(), mt_rand, Math.random	Use crypto-secure RNG
Table lookup by secret	Array subscript on secret index	Bit-sliced lookups

Interpreting Results

PASSED - No variable-time operations detected.

FAILED - Dangerous instructions found. Example:

[ERROR] SDIV
  Function: decompose_vulnerable
  Reason: SDIV has early termination optimization; execution time depends on operand values

Verifying Results (Avoiding False Positives)

CRITICAL : Not every flagged operation is a vulnerability. The tool has no data flow analysis - it flags ALL potentially dangerous operations regardless of whether they involve secrets.

For each flagged violation, ask: Does this operation's input depend on secret data?

Identify the secret inputs to the function (private keys, plaintext, signatures, tokens)
Trace data flow from the flagged instruction back to inputs

Common false positive patterns :

// FALSE POSITIVE: Division uses public constant, not secret
int num_blocks = data_len / 16;  // data_len is length, not content

// TRUE POSITIVE: Division involves secret-derived value
int32_t q = secret_coef / GAMMA2;  // secret_coef from private key

Document your analysis for each flagged item

Quick Triage Questions

Question	If Yes	If No
Is the operand a compile-time constant?	Likely false positive	Continue
Is the operand a public parameter (length, count)?	Likely false positive	Continue
Is the operand derived from key/plaintext/secret?	TRUE POSITIVE	Likely false positive
Can an attacker influence the operand value?	TRUE POSITIVE	Likely false positive

Limitations

Static Analysis Only : Analyzes assembly/bytecode, not runtime behavior. Cannot detect cache timing or microarchitectural side-channels.
No Data Flow Analysis : Flags all dangerous operations regardless of whether they process secrets. Manual review required.
Compiler/Runtime Variations : Different compilers, optimization levels, and runtime versions may produce different output.

Real-World Impact

KyberSlash (2023) : Division instructions in post-quantum ML-KEM implementations allowed key recovery
Lucky Thirteen (2013) : Timing differences in CBC padding validation enabled plaintext recovery
RSA Timing Attacks : Early implementations leaked private key bits through division timing

References

Cryptocoding Guidelines - Defensive coding for crypto
KyberSlash - Division timing in post-quantum crypto
BearSSL Constant-Time - Practical constant-time techniques

Weekly Installs

1.1K

Repository

trailofbits/skills

GitHub Stars

3.9K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

claude-code974

opencode932

gemini-cli910

codex906

cursor880

github-copilot850

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

恒定时间分析工具 | 检测密码学时序攻击漏洞 | 侧信道安全分析

🇨🇳中文介绍

恒定时间分析

何时使用

相关 Skills

何时不应使用

语言选择

快速开始