恒定时间分析
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
[ERROR] SDIV
Function: decompose_vulnerable
Reason: SDIV has early termination optimization; execution time depends on operand values
# Constant-Time Analysis
Compile the code, inspect the emitted assembly or bytecode for variable-time instructions, then decide which of the flagged operations actually touch secrets. The compilation step is mechanical; the triage step is the work.
## When to Use
- Implementing or reviewing a signature, encryption, KEM, or key derivation routine
- Code applies `/` or `%` to a value derived from a key, plaintext, nonce, or token
- The user mentions "constant-time", "timing attack", "side-channel", or "KyberSlash"
- Reviewing functions named `sign`, `verify`, `encrypt`, `decrypt`, `derive_key`
## When NOT to Use
- **Measuring** timing variance on a running binary — use the `constant-time-testing` skill from the `testing-handbook-skills` plugin, which covers dudect and statistical approaches and may not be installed. This skill inspects compiler output statically and never executes the code under test.
- Non-cryptographic code, or crypto code where every input is public
- High-level API usage where a vetted library owns the constant-time guarantees
- Cache and other microarchitectural side channels — the assembly view cannot see them
## Language Routing
Read the guide for the target language before interpreting any findings; each one lists that language's dangerous instructions and the idiomatic constant-time replacements.
| Guide | Languages |
| ----- | --------- |
| [references/compiled.md](references/compiled.md) | C, C++, Go, Rust |
| [references/swift.md](references/swift.md) | Swift |
| [references/vm-compiled.md](references/vm-compiled.md) | Java, C# |
| [references/kotlin.md](references/kotlin.md) | Kotlin |
| [references/php.md](references/php.md) | PHP |
| [references/javascript.md](references/javascript.md) | JavaScript, TypeScript |
| [references/python.md](references/python.md) | Python |
| [references/ruby.md](references/ruby.md) | Ruby |
## Running the Analyzer
The analyzer takes one file and detects the language from its extension. **Always pass `--warnings`:**
```bash
uv run {baseDir}/ct_analyzer/analyzer.py --warnings <source_file>
```
Without it the analyzer reports only error-severity findings, which means division, modulo and weak RNG. Four detector families are warning severity and stay silent: secret-dependent branches, early-exit comparison (`memcmp`, `strcmp`, `.equals`, `==`), table lookups indexed by a secret, and variable-time encoding. Early-exit comparison of an authentication tag is the most common timing bug in real code — Lucky Thirteen was exactly that — so a default run is quiet about the finding you are most likely to have.
| Flag | Effect |
| ---- | ------ |
| `--warnings` | Add the four warning-severity families above. Pass it every time |
| `--func <regex>` | Restrict output to function names matching the regex |
| `--json` | Machine-readable output |
| `--github` | GitHub Actions annotations |
| `--arch <target>` | Target architecture (`x86_64`, `arm64`, `riscv64`, ...) — native languages only |
| `--opt-level <level>` | Optimization level (`O0` through `O3`, `Os`, `Oz`) — native languages only |
| `--compiler <name>` | Override compiler choice (`gcc`, `clang`, `go`, `rustc`, `swiftc`) |
Narrow a large file to the routines that handle secrets with a regex, for example `--func 'sign|verify'`.
**Run natively compiled code (C, C++, Go, Rust, Swift) at more than one `--arch` and `--opt-level`.** Division timing and branch lowering are architecture- and optimization-dependent: x86_64 `IDIV` and arm64 `SDIV` differ, and a `cmov` at `-O2` can become a branch at `-O0`. A single clean run proves one configuration safe, not the code.
**How `--arch` crosses depends on the toolchain.** clang crosses with `--target` and needs no second compiler, but any source that includes libc headers also needs that target's C library headers — `libc6-dev-riscv64-cross` and friends — or it fails with `bits/libc-header-start.h file not found`. Go cross-builds through `GOARCH`, though `go tool objdump` has no riscv64 disassembler. A GNU cross toolchain is a *separate binary*, so gcc needs it named explicitly — `--compiler x86_64-linux-gnu-gcc`, `--compiler riscv64-linux-gnu-gcc` — and nothing is substituted for you, so the report always names the binary that ran. rustc needs the target's standard library (`rustup target add`), and Swift on Linux targets only the host. Compare against the toolchain that builds your product, not whichever cross build a distribution packages.
**Re-run the whole sweep on the fix, across compilers, targets and every level including `Os` and `Oz`.** Any fix that works by handing the compiler a constant divisor to strength-reduce is a fix only where the compiler chooses to cooperate, and that choice varies more than it looks. Replacing `key_coef / (2 * gamma2)` with a `#define`d divisor still emits a real divide here:
| Toolchain | Levels that emit a division |
| --------- | --------------------------- |
| gcc riscv64 | `O0` through `Oz` — every level |
| gcc arm64, gcc x86_64 | `Os`, `Oz` |
| clang arm64 | `O0`, `Oz` |
Strength reduction is an optimizer courtesy, not a language guarantee. Prefer an explicit multiply-shift, and verify it against the original expression over the full input range rather than on sampled values — an off-by-a-power-of-two reciprocal matches for millions of inputs before it diverges.
Java, Kotlin, and C# compile to JVM/CIL bytecode. The analyzer reads that bytecode, so `--arch` and `--opt-level` do not apply and the JIT may still introduce variable-time native code the analyzer cannot see.
### Per-language coverage limits
Coverage is not uniform, and the gaps change what a clean report means:
| Language | What the report does not cover |
| -------- | ------------------------------ |
| Go | Only symbols from the analyzed file. `go build` links the runtime in, and its divisions — all on public data — would otherwise dominate the findings |
| JavaScript, TypeScript | Bytecode findings are restricted to functions the file declares by name, because V8 dumps node's internals the same way it dumps yours. Anonymous callbacks fall to the source scan. For TypeScript, bytecode findings name the function but carry no line, since V8's positions index the transpiled output |
| Python, Ruby, PHP | Bytecode reflects the interpreter that ran, not a JIT'd or alternative runtime |
| Rust | Analyzed as a library unless the file declares `fn main`; private functions with no caller may be optimized away before analysis |
| Swift | Targets the host platform on Linux; iOS and macOS triples need an Apple toolchain |
Since findings and silence both depend on the configuration, say which compiler, architecture, and optimization level produced a result when reporting it.
To sweep a directory, loop in the shell — the analyzer is a deterministic script, one invocation per file:
```bash
for f in src/crypto/*.c; do uv run {baseDir}/ct_analyzer/analyzer.py --warnings --json "$f"; done
```
### Prerequisites
| Language | Requirement |
| -------- | ----------- |
| C, C++, Go, Rust | `gcc`/`clang`, `go`, `rustc` in PATH |
| Swift | Xcode or Swift toolchain (`swiftc`) |
| Java / Kotlin | JDK (`javac`, `javap`); Kotlin also needs `kotlinc` |
| C# | .NET SDK plus `ilspycmd` (`dotnet tool install -g ilspycmd`) |
| PHP | PHP with the VLD extension or OPcache |
| JavaScript / TypeScript | Node.js |
| Python | Python 3.x |
| Ruby | Ruby with `--dump=insns` support |
On a "toolchain not found" error, see [references/vm-compiled.md](references/vm-compiled.md) for JVM and .NET installation, macOS keg-only PATH configuration, and troubleshooting.
## Interpreting Results
**PASSED** — no *error*-severity finding for the configuration you ran. Warnings do not affect it, so `Result: PASSED` alongside `Warnings: 6` is normal and is not a clean result. Read the warning list before concluding anything.
**FAILED** — dangerous instructions found, reported per function:
```text
[ERROR] SDIV
Function: decompose_vulnerable
Reason: SDIV has early termination optimization; execution time depends on operand values
```
## Triaging Findings
**The analyzer has no data flow analysis. It flags every dangerous instruction regardless of whether a secret reaches it, so a FAILED report is a worklist, not a verdict.** Reporting the raw output as a set of vulnerabilities is the primary failure mode of this skill.
For each flagged instruction, read the source and answer one question: **does an operand depend on secret data?** Trace from the instruction's function back to the caller's inputs, then classify:
```c
// FALSE POSITIVE: operands are a buffer length, already public from the ciphertext size
int num_blocks = data_len / 16;
// TRUE POSITIVE: dividend is a private-key coefficient; IDIV/SDIV leaks its magnitude
int32_t q = secret_coef / GAMMA2;
```
| Question | If yes |
| -------- | ------ |
| Is the operand a compile-time constant? | Likely false positive |
| Is the operand a public parameter — length, count, index bound? | Likely false positive |
| Is the operand derived from a key, plaintext, nonce, or token? | **True positive** |
| Can an attacker influence the operand's value? | **True positive** |
State the verdict and the data flow that justifies it for every flagged item. A finding you cannot trace to a secret is not a finding; say so explicitly rather than dropping it silently.
`{baseDir}/ct_analyzer/tests/triage_samples/` holds a known-answer case per language: each fixture pairs a true positive with a false positive that the analyzer reports identically, and `expectations.json` records which is which and why. `triage_c.c` is the shortest example — the analyzer flags the division in both `ct_high_bits` and `ct_block_count`, and correct triage confirms the first and clears the second.
**Weak-RNG and encoding findings ask a different question.** For `Math.random`, `mt_rand`, `random.randint`, `System.Random` and `base64_encode`, no operand is secret, so "does an operand depend on a secret?" does not resolve them. Ask instead what the result is used for: seeding a nonce or key is a true positive, jittering a retry delay is not. These are reported by a regex scan over the source rather than from bytecode, so they are attributed to `<source>` with a line number instead of to the enclosing function — except in PHP, where they carry the function.
**Comparison and lookup findings have their own question, and their own fix.** For an early-exit comparison, ask whether either side is secret: comparing an authentication tag, MAC, or password hash is a true positive, comparing a public protocol header is not. For a table lookup, ask whether the *index* is secret — the array's contents do not matter, only what selects the element. Both are exploitable as written, so a confirmed one needs the language's constant-time primitive rather than a rewrite of the loop:
| Language | Constant-time comparison |
| -------- | ------------------------ |
| C, C++ | `CRYPTO_memcmp` (OpenSSL) or `sodium_memcmp` |
| Go | `crypto/subtle.ConstantTimeCompare` |
| Rust | the `subtle` crate's `ConstantTimeEq` |
| Java, Kotlin | `MessageDigest.isEqual` |
| C# | `CryptographicOperations.FixedTimeEquals` |
| PHP | `hash_equals` |
| Python | `hmac.compare_digest` |
| Ruby | `OpenSSL.secure_compare` |
| JavaScript, TypeScript | `crypto.timingSafeEqual` |
A secret-indexed lookup has no drop-in replacement: it needs a bit-sliced or arithmetic formulation that touches every element, which is why AES S-box tables are the classic case. Encoding a secret through a table — `base64_encode`, `bin2hex`, `chr`/`ord` — is the same problem in a library, and `paragonie/constant_time_encoding` is the reference fix for PHP.
## Limitations
1. **Static only** — reads assembly and bytecode, never runtime behavior. Cache timing and other microarchitectural channels are invisible.
2. **No data flow analysis** — see triage above.
3. **Configuration-specific** — a different compiler, optimization level, architecture, or runtime version can emit different instructions from identical source.
## Real-World Impact
- **KyberSlash (2023)** — division instructions in 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](https://github.com/veorq/cryptocoding) — defensive coding for crypto
- [KyberSlash](https://kyberslash.cr.yp.to/) — division timing in post-quantum crypto
- [BearSSL Constant-Time](https://www.bearssl.org/constanttime.html) — practical constant-time techniques
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
语言路由
运行分析器
每种语言的覆盖范围限制
文件/命令 -> sign · verify · encrypt · decrypt · derive_key · constant-time-testing · testing-handbook-skills · --warnings
内容校验值 -> d528f15d9b97
当前原文的自动摘译,尚未人工审校。
何时使用
实现或审查签名、加密、KEM 或密钥派生例程 代码将
/或%应用于从密钥、明文、随机数或令牌派生的值 用户提及“恒定时间”、“定时攻击”、“旁道”或“KyberSlash” 审查名为sign、verify、encrypt、decrypt、derive_key何时不使用
测量正在运行的二进制文件上的时间方差 - 使用
testing-handbook-skills插件中的constant-time-testing技能,该插件涵盖了 dudect 和统计方法,可能不会安装。此技能静态检查编译器输出,并且从不执行被测代码。非加密代码,或加密代码,其中每个输入都是公共的高级 API 使用,其中经过审查的库拥有恒定时间保证语言路由
在解释任何发现之前,请阅读目标语言的指南;每一个都列出了该语言的危险指令和惯用的常量替换。指南 · 语言参考/compiled.md · C、C++、Go、Rust 参考/swift.md · Swift 参考/vm-compiled.md · Java、C#
运行分析器
分析器获取一个文件并从其扩展名中检测语言。始终通过
--warnings:没有它,分析器仅报告错误严重性结果,这意味着除法、模数和弱 RNG。四个检测器系列警告严重性并保持沉默:依赖秘密的分支、提前退出比较(memcmp、strcmp、.equals、==)、由秘密索引的表查找和可变时间编码。身份验证标签的提前退出比较是实际代码中最常见的计时错误 - 幸运十三正是如此 - 因此默认运行对于您最有可能拥有的发现是安静的。每种语言的覆盖范围限制
覆盖范围并不统一,这些差距改变了干净报告的含义: 语言 · 报告不涵盖的内容 · 仅分析文件中的符号。
go build链接运行时及其分区(全部在公共数据上),否则将主导结果 JavaScript、TypeScript · 字节码结果仅限于文件按名称声明的函数,因为 V8 转储节点内部的方式与转储节点内部的方式相同。匿名回调属于源扫描。对于 TypeScript,字节码结果会命名函数但不包含任何行,因为 V8 的位置索引了转译输出