kdf/
lib.rs

1#![no_std]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![doc = include_str!("../README.md")]
4#![doc(
5    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
6    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
7)]
8#![forbid(unsafe_code)]
9#![warn(missing_docs, unused_qualifications)]
10
11use core::fmt;
12
13/// Key Derivation Function.
14///
15/// These functions deterministically produce uniformly random outputs suitable as key material.
16///
17/// It is recommended for types which implement this trait to also implement [`Default`] whenever
18/// possible.
19pub trait Kdf {
20    /// Writes uniformly random data suitable as key material into the entire length of `out`,
21    /// derived from the following inputs:
22    ///
23    /// - `secret`: this is typically a high-entropy input with at least 128-bits of symmetric
24    ///   strength/randomness, but does not have to be uniformly random (e.g. can be the output of
25    ///   a Diffie-Hellman exchange). For KDFs marked [`Pbkdf`], this parameter is allowed to be a
26    ///   password with a lower entropy, but consumers of these traits MUST bound on [`Pbkdf`]
27    ///   whenever they are expecting the input to be a password.
28    /// - `non_secret`: this value customizes/personalizes the output and can be used to generate
29    ///   multiple unrelated outputs from the same input. Its secrecy is irrelevant, and it can be
30    ///   published to the world if desired. It maps to an algorithm specific parameter which
31    ///   accomplishes this purpose, sometimes called "salt", "info", "context", or "customization".
32    ///   See algorithm-specific documentation for the specific input this maps to for the specific
33    ///   impls for a given algorithm. For KDFs marked [`Pbkdf`] this is always the salt.
34    fn derive_key(&self, secret: &[u8], non_secret: &[u8], out: &mut [u8]) -> Result<()>;
35}
36
37/// Password-Based Key Derivation Functions: KDFs where it's suitable for the input `secret` to be
38/// a user-specified password, which employ algorithms designed to be resistant to brute-force
39/// attacks.
40pub trait Pbkdf: Kdf {}
41
42/// Key derivation errors.
43#[derive(Clone, Copy, Debug, Eq, PartialEq)]
44pub struct Error;
45
46impl fmt::Display for Error {
47    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
48        f.write_str("KDF error")
49    }
50}
51
52impl core::error::Error for Error {}
53
54/// Result type with the `kdf` crate's [`Error`].
55pub type Result<T> = core::result::Result<T, Error>;
kdf/lib.rs

kdf/
lib.rs
