From 40fce6307990d136df15c6fcf9f5aa7629f54619 Mon Sep 17 00:00:00 2001 From: Tony Arcieri Date: Tue, 20 Jan 2026 15:23:54 -0700 Subject: [PATCH 1/2] kdf: `Kdf` trait documentation improvements Expands documentation and renames the second parameter (not counting `self`) to the KDF from `salt` => `non_secret`. When impl'ing this trait for `hkdf` it became clear that, using the existing structs, `info` was the only parameter that made sense (something @newpavlov hinted at), as `salt` is the only one that can be statefully configured and accessed via `self`. So this renames it to a much more nonspecific `non_secret` and notes in the documentation that such a parameter goes by many different names that all generally serve the same function: customizing the outputs in a non-correlated/indistinguishable manner. It suggests consulting the algorithm-specific documentation for what parameter it actually maps to, except for `Kdf`s marked `Pbkdf` where it says it always maps to the salt. --- kdf/src/lib.rs | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/kdf/src/lib.rs b/kdf/src/lib.rs index e4df7e916..a0a7cd555 100644 --- a/kdf/src/lib.rs +++ b/kdf/src/lib.rs @@ -13,10 +13,24 @@ use core::fmt; /// Key Derivation Function. /// /// These functions deterministically produce uniformly random outputs suitable as key material. +/// +/// It is recommended for types which impls this trait to also impl [`Default`] whenever possible. pub trait Kdf { - /// Fills `out` with uniformly random data suitable as key material, derived from the input - /// `secret` and `salt` values, which map to algorithm-specific inputs. - fn derive_key(&self, secret: &[u8], salt: &[u8], out: &mut [u8]) -> Result<()>; + /// Writes uniformly random data suitable as key material into the entire length of `out`, + /// derived from the following inputs: + /// + /// - `secret`: this is typically a high-entropy input with at least 128-bits of symmetric + /// strength/randomness, but does not have to be uniformly random (e.g. can be the output of + /// a Diffie-Hellman exchange). For KDFs marked [`Pbkdf`], this parameter is allowed to be a + /// password with a lower entropy, but consumers of these traits MUST bound on [`Pbkdf`] + /// whenever they are expecting the input to be a password. + /// - `non_secret`: this value customizes/personalizes the output and can be used to generate + /// multiple unrelated outputs from the same input. Its secrecy is irrelevant, and it can be + /// published to the world if desired. It maps to an algorithm specific parameter which + /// accomplishes this purpose, sometimes called "salt", "info", "context", or "customization". + /// See algorithm-specific documentation for the specific input this maps to for the specific + /// impls for a given algorithm. For KDFs marked [`Pbkdf`] this is always the salt. + fn derive_key(&self, secret: &[u8], non_secret: &[u8], out: &mut [u8]) -> Result<()>; } /// Password-Based Key Derivation Functions: KDFs where it's suitable for the input `secret` to be From b0613cbea99b9cdca45184b44214f7eb7df9014e Mon Sep 17 00:00:00 2001 From: Tony Arcieri Date: Tue, 20 Jan 2026 15:49:34 -0700 Subject: [PATCH 2/2] impl => implement --- kdf/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/kdf/src/lib.rs b/kdf/src/lib.rs index a0a7cd555..2bdc76bc2 100644 --- a/kdf/src/lib.rs +++ b/kdf/src/lib.rs @@ -14,7 +14,8 @@ use core::fmt; /// /// These functions deterministically produce uniformly random outputs suitable as key material. /// -/// It is recommended for types which impls this trait to also impl [`Default`] whenever possible. +/// It is recommended for types which implement this trait to also implement [`Default`] whenever +/// possible. pub trait Kdf { /// Writes uniformly random data suitable as key material into the entire length of `out`, /// derived from the following inputs: