| name | constant-time-analysis |
| description | Detects timing side-channel vulnerabilities in cryptographic code. Use when implementing or reviewing crypto code, encountering division on secrets, secret-dependent branches, or constant-time programming questions in C, C++, Go, Rust, Swift, Java, Kotlin, C#, PHP, JavaScript, TypeScript, Python, or Ruby. |
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:
Quick Start
uv run {baseDir}/ct_analyzer/analyzer.py <source_file>
uv run {baseDir}/ct_analyzer/analyzer.py --warnings <source_file>
uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' <source_file>
uv run {baseDir}/ct_analyzer/analyzer.py --json <source_file>
Native Compiled Languages Only (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
VM-Compiled Languages (Java, Kotlin, C#)
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.java
uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt
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)
uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift
uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift
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 (javap) in PATH |
| C# | .NET SDK + ilspycmd (dotnet tool install -g ilspycmd) |
| PHP | PHP with VLD extension or OPcache |
| JavaScript/TypeScript | Node.js in PATH |
| Python | Python 3.x in PATH |
| Ruby | Ruby with --dump=insns support |
macOS users: Homebrew installs Java and .NET as "keg-only". You must add them to your PATH:
export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
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:
int num_blocks = data_len / 16;
int32_t q = secret_coef / GAMMA2;
-
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
