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 |
.rs |
references/compiled.md |
| Swift |
.swift |
references/swift.md |
| Java |
.java |
references/vm-compiled.md |
| Kotlin |
.kt, .kts |
references/kotlin.md |
| C# |
.cs |
references/vm-compiled.md |
| PHP |
.php |
references/php.md |
| JavaScript |
.js, .mjs, .cjs |
references/javascript.md |
| TypeScript |
.ts, .tsx |
references/javascript.md |
| Python |
.py |
references/python.md |
| Ruby |
.rb |
references/ruby.md |
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 (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:
# 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
1---
2name: constant-time-analysis
3description: 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,...
4risk: safe
5metadata:
6 source: https://skillmd.com/skills/kursku/constant-time-analysis
7---
8
9# Constant-Time Analysis
10
11Analyze cryptographic code to detect operations that leak secret data through execution timing variations.
12
13## When to Use
14
15```text
16User writing crypto code? ──yes──> Use this skill
17 │
18 no
19 │
20 v
21User asking about timing attacks? ──yes──> Use this skill
22 │
23 no
24 │
25 v
26Code handles secret keys/tokens? ──yes──> Use this skill
27 │
28 no
29 │
30 v
31Skip this skill
32```
33
34**Concrete triggers:**
35
36- User implements signature, encryption, or key derivation
37- Code contains `/` or `%` operators on secret-derived values
38- User mentions "constant-time", "timing attack", "side-channel", "KyberSlash"
39- Reviewing functions named `sign`, `verify`, `encrypt`, `decrypt`, `derive_key`
40
41## When NOT to Use
42
43- Non-cryptographic code (business logic, UI, etc.)
44- Public data processing where timing leaks don't matter
45- Code that doesn't handle secrets, keys, or authentication tokens
46- High-level API usage where timing is handled by the library
47
48## Language Selection
49
50Based on the file extension or language context, refer to the appropriate guide:
51
52| Language | File Extensions | Guide |
53| ---------- | --------------------------------- | -------------------------------------------------------- |
54| C, C++ | `.c`, `.h`, `.cpp`, `.cc`, `.hpp` | references/compiled.md |
55| Go | `.go` | references/compiled.md |
56| Rust | `.rs` | references/compiled.md |
57| Swift | `.swift` | references/swift.md |
58| Java | `.java` | references/vm-compiled.md |
59| Kotlin | `.kt`, `.kts` | references/kotlin.md |
60| C# | `.cs` | references/vm-compiled.md |
61| PHP | `.php` | references/php.md |
62| JavaScript | `.js`, `.mjs`, `.cjs` | references/javascript.md |
63| TypeScript | `.ts`, `.tsx` | references/javascript.md |
64| Python | `.py` | references/python.md |
65| Ruby | `.rb` | references/ruby.md |
66
67## Quick Start
68
69```bash
70# Analyze any supported file type
71uv run {baseDir}/ct_analyzer/analyzer.py <source_file>
72
73# Include conditional branch warnings
74uv run {baseDir}/ct_analyzer/analyzer.py --warnings <source_file>
75
76# Filter to specific functions
77uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' <source_file>
78
79# JSON output for CI
80uv run {baseDir}/ct_analyzer/analyzer.py --json <source_file>
81```
82
83### Native Compiled Languages Only (C, C++, Go, Rust)
84
85```bash
86# Cross-architecture testing (RECOMMENDED)
87uv run {baseDir}/ct_analyzer/analyzer.py --arch x86_64 crypto.c
88uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.c
89
90# Multiple optimization levels
91uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.c
92uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O3 crypto.c
93```
94
95### VM-Compiled Languages (Java, Kotlin, C#)
96
97```bash
98# Analyze Java bytecode
99uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.java
100
101# Analyze Kotlin bytecode (Android/JVM)
102uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt
103
104# Analyze C# IL
105uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.cs
106```
107
108Note: 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.
109
110### Swift (iOS/macOS)
111
112```bash
113# Analyze Swift for native architecture
114uv run {baseDir}/ct_analyzer/analyzer.py crypto.swift
115
116# Analyze for specific architecture (iOS devices)
117uv run {baseDir}/ct_analyzer/analyzer.py --arch arm64 crypto.swift
118
119# Analyze with different optimization levels
120uv run {baseDir}/ct_analyzer/analyzer.py --opt-level O0 crypto.swift
121```
122
123Note: Swift compiles to native code like C/C++/Go/Rust, so it uses assembly-level analysis and supports `--arch` and `--opt-level` flags.
124
125### Prerequisites
126
127| Language | Requirements |
128| ---------------------- | --------------------------------------------------------- |
129| C, C++, Go, Rust | Compiler in PATH (`gcc`/`clang`, `go`, `rustc`) |
130| Swift | Xcode or Swift toolchain (`swiftc` in PATH) |
131| Java | JDK with `javac` and `javap` in PATH |
132| Kotlin | Kotlin compiler (`kotlinc`) + JDK (`javap`) in PATH |
133| C# | .NET SDK + `ilspycmd` (`dotnet tool install -g ilspycmd`) |
134| PHP | PHP with VLD extension or OPcache |
135| JavaScript/TypeScript | Node.js in PATH |
136| Python | Python 3.x in PATH |
137| Ruby | Ruby with `--dump=insns` support |
138
139**macOS users**: Homebrew installs Java and .NET as "keg-only". You must add them to your PATH:
140
141```bash
142# For Java (add to ~/.zshrc)
143export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
144
145# For .NET tools (add to ~/.zshrc)
146export PATH="$HOME/.dotnet/tools:$PATH"
147```
148
149See references/vm-compiled.md for detailed setup instructions and troubleshooting.
150
151## Quick Reference
152
153| Problem | Detection | Fix |
154| ---------------------- | ------------------------------- | -------------------------------------------- |
155| Division on secrets | DIV, IDIV, SDIV, UDIV | Barrett reduction or multiply-by-inverse |
156| Branch on secrets | JE, JNE, BEQ, BNE | Constant-time selection (cmov, bit masking) |
157| Secret comparison | Early-exit memcmp | Use `crypto/subtle` or constant-time compare |
158| Weak RNG | rand(), mt_rand, Math.random | Use crypto-secure RNG |
159| Table lookup by secret | Array subscript on secret index | Bit-sliced lookups |
160
161## Interpreting Results
162
163**PASSED** - No variable-time operations detected.
164
165**FAILED** - Dangerous instructions found. Example:
166
167```text
168[ERROR] SDIV
169 Function: decompose_vulnerable
170 Reason: SDIV has early termination optimization; execution time depends on operand values
171```
172
173## Verifying Results (Avoiding False Positives)
174
175**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.
176
177For each flagged violation, ask: **Does this operation's input depend on secret data?**
178
1791. **Identify the secret inputs** to the function (private keys, plaintext, signatures, tokens)
180
1812. **Trace data flow** from the flagged instruction back to inputs
182
1833. **Common false positive patterns**:
184
185 ```c
186 // FALSE POSITIVE: Division uses public constant, not secret
187 int num_blocks = data_len / 16; // data_len is length, not content
188
189 // TRUE POSITIVE: Division involves secret-derived value
190 int32_t q = secret_coef / GAMMA2; // secret_coef from private key
191 ```
192
1934. **Document your analysis** for each flagged item
194
195### Quick Triage Questions
196
197| Question | If Yes | If No |
198| ------------------------------------------------- | --------------------- | --------------------- |
199| Is the operand a compile-time constant? | Likely false positive | Continue |
200| Is the operand a public parameter (length, count)?| Likely false positive | Continue |
201| Is the operand derived from key/plaintext/secret? | **TRUE POSITIVE** | Likely false positive |
202| Can an attacker influence the operand value? | **TRUE POSITIVE** | Likely false positive |
203
204## Limitations
205
2061. **Static Analysis Only**: Analyzes assembly/bytecode, not runtime behavior. Cannot detect cache timing or microarchitectural side-channels.
207
2082. **No Data Flow Analysis**: Flags all dangerous operations regardless of whether they process secrets. Manual review required.
209
2103. **Compiler/Runtime Variations**: Different compilers, optimization levels, and runtime versions may produce different output.
211
212## Real-World Impact
213
214- **KyberSlash (2023)**: Division instructions in post-quantum ML-KEM implementations allowed key recovery
215- **Lucky Thirteen (2013)**: Timing differences in CBC padding validation enabled plaintext recovery
216- **RSA Timing Attacks**: Early implementations leaked private key bits through division timing
217
218## References
219
220- [Cryptocoding Guidelines](https://github.com/veorq/cryptocoding) - Defensive coding for crypto
221- [KyberSlash](https://kyberslash.cr.yp.to/) - Division timing in post-quantum crypto
222- [BearSSL Constant-Time](https://www.bearssl.org/constanttime.html) - Practical constant-time techniques