1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
// Copyright (c) 2025-2026 Kirky.XðŸŒ
// SPDX-License-Identifier: Apache-2.0
//! Constant-time string comparison helper
//!
//! Provides `constant_time_eq_str` to mitigate timing side-channel attacks
//! when comparing fixed-length secret-derived strings (e.g. SHA-256 hex
//! digests of API keys).
//!
//! # Security
//!
//! `==` on `&str` performs byte-by-byte comparison with short-circuit
//! semantics: it returns `false` on the first mismatched byte. An attacker
//! who can measure response time can recover the secret digest byte-by-byte
//! by sending crafted inputs and observing whether the comparison takes
//! slightly longer for the correct prefix.
//!
//! `constant_time_eq_str` uses [`subtle::ConstantTimeEq`] (`ct_eq`) which
//! guarantees every byte participates in the comparison before the result
//! is returned, regardless of where the first mismatch occurs. This removes
//! the timing signal exploited by the attack above.
//!
//! # Limitations
//!
//! - **Length check is NOT constant-time.** When `a.len != b.len` the
//! function returns `false` immediately. This is acceptable for the
//! current call sites because the expected length is fixed and publicly
//! known (SHA-256 hex digest = 64 ASCII chars); length is not a secret.
//! If you need constant-time comparison for variable-length secrets,
//! pad both inputs to a fixed length before calling this function.
//! - **Only `&[u8]` semantics.** The function compares the UTF-8 byte
//! representation of the input strings; normalization is the caller's
//! responsibility.
//! - **Not a replacement for `bcrypt::verify`.** For password / API key
//! verification against a bcrypt hash (`$2b$...`), use
//! [`crate::infrastructure::security::verify_api_key`] directly — bcrypt
//! already performs constant-time comparison internally.
//!
//! # When to use
//!
//! Use this helper only when comparing two fixed-length, secret-derived
//! strings (e.g. SHA-256 hex digests). For non-secret comparisons (URLs,
//! user IDs, configuration values), prefer `==` — the constant-time
//! overhead is unnecessary and reduces readability.
use ConstantTimeEq;
/// Constant-time comparison of two equal-length strings.
///
/// Returns `false` immediately if `a.len != b.len` (length is not a
/// secret — see module docs). Otherwise performs a constant-time byte
/// comparison via `subtle::ConstantTimeEq::ct_eq`.
///
/// # Security
///
/// Mitigates timing side-channel leakage of secret digest content during
/// equality comparison. See the module-level documentation for the full
/// security model and limitations.
///
/// # Arguments
///
/// * `a` - First string (typically the stored digest)
/// * `b` - Second string (typically the computed digest)
///
/// # Returns
///
/// * `true` if both strings have equal length and identical bytes
/// * `false` otherwise