From f7bf84eb3258120ea815140a2698305e35265b86 Mon Sep 17 00:00:00 2001 From: Ike McCreery Date: Mon, 22 Jan 2024 15:40:36 -0500 Subject: [PATCH] Add documentation about comparing secrets securely. See #245. --- src/lib.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 10a17be..d1dfa28 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -71,6 +71,20 @@ //! RE: std::error::Error + 'static //! ``` //! +//! # Comparing secrets securely +//! +//! OAuth flows require comparing secrets received from the provider servers. To do so securely +//! while avoiding [timing side-channels](https://en.wikipedia.org/wiki/Timing_attack), the +//! comparison must be done in constant time, either using a constant-time crate such as +//! [`constant_time_eq`] (which could break if a future compiler version decides to be overly smart +//! about its optimizations), or by first computing a cryptographically-secure hash (e.g., SHA-256) +//! of both values and then comparing the hashes using `==`. +//! +//! The `timing-resistant-secret-traits` feature flag adds a safe (but comparatively expensive) +//! [`PartialEq`] implementation to the secret types. Timing side-channels are why [`PartialEq`] is +//! not auto-derived for this crate's secret types, and the lack of [`PartialEq`] is intended to +//! prompt users to think more carefully about these comparisons. +//! //! # Getting started: Authorization Code Grant w/ PKCE //! //! This is the most common OAuth2 flow. PKCE is recommended whenever the OAuth2 client has no