--- name: constant-time-analysis description: "Analyze cryptographic code to detect operations that leak secret data through execution timing variations." risk: critical source: community date_added: "2026-03-06" --- ## Bundled upstream support Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes. # Constant-Time Analysis Analyze cryptographic code to detect operations that leak secret data through execution timing variations. ## When to Use ```text 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 | ## Runtime prerequisite and execution boundary This catalog bundles documentation only; `ct_analyzer/analyzer.py` is not included. The commands below and in the language references are illustrative upstream usage, not an instruction to resolve or execute missing code. Stop if a separately installed, reviewed analyzer is unavailable. Record its immutable source identity and inspect its complete runtime and locked dependencies before any separately authorized setup. Use only existing approved language tools; do not let `uv`, `npx`, PECL or a guide's bootstrap commands fetch a moving dependency. Review the selected analyzer's command construction and target-execution behavior before using it on untrusted code. For PHP, require VLD with `vld.execute=0`; refuse any analyzer that falls back to OPcache target execution. For compilation, bytecode inspection and all other language backends, use an isolated environment without unrelated credentials or network access. Do not treat disassembly as proof that a tool cannot execute target code. ## Quick Start ```bash # Analyze any supported file type uv run {baseDir}/ct_analyzer/analyzer.py # Include conditional branch warnings uv run {baseDir}/ct_analyzer/analyzer.py --warnings # Filter to specific functions uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' # JSON output for CI uv run {baseDir}/ct_analyzer/analyzer.py --json ``` ### Native Compiled Languages Only (C, C++, Go, Rust) ```bash # 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#) ```bash # 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) ```bash # 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 reviewed VLD extension, target execution disabled | | 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: ```bash # 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 configured patterns were detected in this analysis. This is not proof of constant-time execution. **FAILED** - Review candidates found; establish secret dependence and target CPU/runtime behavior before calling them vulnerabilities. Example: ```text [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?** 1. **Identify inputs that the threat model actually treats as secret** (for example private keys or tokens; signatures and lengths may be public). 2. **Trace data flow** from the flagged instruction back to inputs 3. **Common false positive patterns**: ```c // 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 ``` 4. **Document your analysis** for each flagged item ### Quick Triage Questions | Question | If Yes | If No | | ------------------------------------------------- | --------------------- | --------------------- | | Is the operand a compile-time constant? | Check the other operand too | 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? | Check secret-dependent interaction | Likely false positive | ## Limitations 1. **Static Analysis Only**: Analyzes assembly/bytecode, not runtime behavior. Cannot detect cache timing or microarchitectural side-channels. 2. **No Data Flow Analysis**: Flags all dangerous operations regardless of whether they process secrets. Manual review required. 3. **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](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