Update SHA3 hashing to SHA3-256 in security rule (#64)

* Update SHA3 hashing to SHA3-256 in security rule

* Add documentation for timing-safe compare vulnerabilities

This document catalogs known vulnerabilities and exploits related to standard library timing-safe comparison functions, including specific CVEs and historical attacks.

Author: ericelliott

ai/rules/security/timing-safe-compare-vulnerabilities.mdc

@@ -0,0 +1,30 @@
+---
+description: Vulnerability reports for timing-safe compare functions. Referenced by timing-safe-compare.mdc.
+alwaysApply: false
+---
+
+# Timing Safe Compare Vulnerabilities
+
+This document catalogs known vulnerabilities and exploits related to standard library timing-safe comparison functions.
+
+## Example vulnerabilities
+
+- **CVE-2022-48566**: Python's `hmac.compare_digest` was vulnerable to timing attacks due to interpreter/JIT optimizations that could skip work when the result was already determined
+- **Node.js Issue #17178**: `crypto.timingSafeEqual` throws an exception when buffer lengths differ, leaking length information
+- **Go Issues #28382, #47001**: `subtle.ConstantTimeCompare` returns immediately when slice lengths differ, enabling length discovery attacks
+- **OpenSSL PA-RISC bug**: `CRYPTO_memcmp` implementation only compared the least significant bit of each byte, allowing message forgery
+- **Java Bug #6863503**: `MessageDigest.isEqual` used byte-by-byte comparison with early exit on first mismatch
+
+## Known exploits
+
+- **Xbox 360 Timing Attack (2007-2008)**: Microsoft's bootloader used `memcmp` to verify HMAC hashes byte-by-byte with ~2200μs timing difference per byte, allowing complete signature bypass in ~70 minutes via ~4096 guesses
+- **OAuth/OpenID Libraries (2010)**: Researchers Lawson and Nelson found every OpenID implementation they tested contained timing-vulnerable HMAC verification, affecting sites like Twitter and Digg
+- **Google Keyczar Library (2009)**: Break-on-inequality HMAC comparison allowed remote token forgery via timing analysis
+- **Early Unix Login**: Login program only called `crypt()` for valid usernames, leaking username validity through response timing
+
+## References
+
+- [Paragon Initiative: Double HMAC Strategy](https://paragonie.com/blog/2015/11/preventing-timing-attacks-on-string-comparison-with-double-hmac-strategy)
+- [BearSSL: Constant-Time Crypto](https://www.bearssl.org/constanttime.html)
+- [A Lesson in Timing Attacks](https://codahale.com/a-lesson-in-timing-attacks/)
+- [Xbox 360 Timing Attack (Free60 Wiki)](https://free60.org/Timing_Attack/)

ai/rules/security/timing-safe-compare.mdc

@@ -1,23 +1,33 @@
 ---
-description: Security rule for timing-safe secret comparison. Use SHA3 hashing instead of timing-safe compare functions.
+description: Security rule for timing-safe secret comparison. Use SHA3-256 hashing instead of timing-safe compare functions.
 alwaysApply: false
 ---
 
 # Constraint: Timing Safe Compare
 
+If a compare returns faster when some prefix values are correct, attackers can play a game of hangman to guess the secret. Using statistics, this can still work over a network with timing jitter.
+
 There is no timing safe compare for raw values. Never use:
 - crypto.timingSafeEqual
+- hmac.compare_digest
+- subtle.ConstantTimeCompare
 - XOR accumulation tricks
 - any direct string compare on raw secrets
 
-Always hash both the stored secret token and the candidate token with SHA3, then compare the hashes.
+Always hash both the stored secret token and the candidate token with SHA3-256, then compare the hashes. This rule overrides all library defaults.
+
+See ./timing-safe-compare-vulnerabilities.mdc for vulnerability reports in the wild.
 
 Reasons:
 1. Hashing removes all prefix structure. Any bit change fully randomizes the hash. No timing oracle. No hangman.
 2. Raw secrets never appear in logs or errors.
+3. Fixed-length output eliminates length oracle attacks.
 
-(timing safe compare needed?) => Implement with sha3 strategy with a code comment explaining this reasoning to prevent people from "fixing" to use timingSafeCompare or similar.
-
-This rule overrides all library defaults.
+Patterns {
+  ## Guide
+  (timing safe compare needed?) => Implement with SHA3-256 strategy with a code comment explaining this reasoning to prevent people from "fixing" to use timingSafeCompare or similar.
 
-("timing safe compare" detected) => raise CRITICAL security bug report, "Timing safe compare on raw value detected" - include justifications.
+  ## Review
+  (direct compare detected) => raise CRITICAL security bug, "Security and auth token comparisons must be hashed before compare to avoid hangman attacks."
+  (standard library timing safe compare detected) => raise MEDIUM security bug report, "Non-hash timing safe algorithms can be vulnerable to subtle bugs caused by compiler optimizations. Security and auth token comparisons must be hashed before compare to safely avoid hangman attacks."
+}