hkdf/
lib.rs

Help
1//! An implementation of HKDF, the [HMAC-based Extract-and-Expand Key Derivation Function][1].
2//!
3//! # Usage
4//!
5//! The most common way to use HKDF is as follows: you provide the Initial Key
6//! Material (IKM) and an optional salt, then you expand it (perhaps multiple times)
7//! into some Output Key Material (OKM) bound to an "info" context string.
8//!
9//! ```rust
10//! use sha2::Sha256;
11//! use hkdf::Hkdf;
12//! use hex_literal::hex;
13//!
14//! let ikm = hex!("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b");
15//! let salt = hex!("000102030405060708090a0b0c");
16//! let info = hex!("f0f1f2f3f4f5f6f7f8f9");
17//!
18//! let hk = Hkdf::<Sha256>::new(Some(&salt[..]), &ikm);
19//! let mut okm = [0u8; 42];
20//! hk.expand(&info, &mut okm)
21//!     .expect("42 is a valid length for Sha256 to output");
22//!
23//! let expected = hex!("
24//!     3cb25f25faacd57a90434f64d0362f2a
25//!     2d2d0a90cf1a5a4c5db02d56ecc4c5bf
26//!     34007208d5b887185865
27//! ");
28//! assert_eq!(okm[..], expected[..]);
29//! ```
30//!
31//! Normally the PRK (Pseudo-Random Key) remains hidden within the HKDF
32//! object, but if you need to access it, use [`Hkdf::extract`] instead of
33//! [`Hkdf::new`].
34//!
35//! ```rust
36//! # use sha2::Sha256;
37//! # use hkdf::Hkdf;
38//! # use hex_literal::hex;
39//! # let ikm = hex!("0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b");
40//! # let salt = hex!("000102030405060708090a0b0c");
41//!
42//! let (prk, hk) = Hkdf::<Sha256>::extract(Some(&salt[..]), &ikm);
43//! let expected = hex!("
44//!     077709362c2e32df0ddc3f0dc47bba63
45//!     90b6c73bb50f9c3122ec844ad7c2b3e5
46//! ");
47//! assert_eq!(prk[..], expected[..]);
48//! ```
49//!
50//! If you already have a strong key to work from (uniformly-distributed and
51//! long enough), you can save a tiny amount of time by skipping the extract
52//! step. In this case, you pass a Pseudo-Random Key (PRK) into the
53//! [`Hkdf::from_prk`] constructor, then use the resulting [`Hkdf`] object
54//! as usual.
55//!
56//! ```rust
57//! # use sha2::Sha256;
58//! # use hkdf::Hkdf;
59//! # use hex_literal::hex;
60//! # let salt = hex!("000102030405060708090a0b0c");
61//! # let info = hex!("f0f1f2f3f4f5f6f7f8f9");
62//! let prk = hex!("
63//!     077709362c2e32df0ddc3f0dc47bba63
64//!     90b6c73bb50f9c3122ec844ad7c2b3e5
65//! ");
66//!
67//! let hk = Hkdf::<Sha256>::from_prk(&prk).expect("PRK should be large enough");
68//! let mut okm = [0u8; 42];
69//! hk.expand(&info, &mut okm)
70//!     .expect("42 is a valid length for Sha256 to output");
71//!
72//! let expected = hex!("
73//!     3cb25f25faacd57a90434f64d0362f2a
74//!     2d2d0a90cf1a5a4c5db02d56ecc4c5bf
75//!     34007208d5b887185865
76//! ");
77//! assert_eq!(okm[..], expected[..]);
78//! ```
79//!
80//! [1]: https://tools.ietf.org/html/rfc5869
81
82#![no_std]
83#![doc(
84    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
85    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
86    html_root_url = "https://docs.rs/hkdf/0.12.3"
87)]
88#![cfg_attr(docsrs, feature(doc_cfg))]
89#![forbid(unsafe_code)]
90#![warn(missing_docs, rust_2018_idioms)]
91
92#[cfg(feature = "std")]
93extern crate std;
94
95pub use hmac;
96
97use core::fmt;
98use core::marker::PhantomData;
99use hmac::digest::{
100    crypto_common::AlgorithmName, generic_array::typenum::Unsigned, Output, OutputSizeUser,
101};
102use hmac::{Hmac, SimpleHmac};
103
104mod errors;
105mod sealed;
106
107pub use errors::{InvalidLength, InvalidPrkLength};
108
109/// [`HkdfExtract`] variant which uses [`SimpleHmac`] for underlying HMAC
110/// implementation.
111pub type SimpleHkdfExtract<H> = HkdfExtract<H, SimpleHmac<H>>;
112/// [`Hkdf`] variant which uses [`SimpleHmac`] for underlying HMAC
113/// implementation.
114pub type SimpleHkdf<H> = Hkdf<H, SimpleHmac<H>>;
115
116/// Structure representing the streaming context of an HKDF-Extract operation
117/// ```rust
118/// # use hkdf::{Hkdf, HkdfExtract};
119/// # use sha2::Sha256;
120/// let mut extract_ctx = HkdfExtract::<Sha256>::new(Some(b"mysalt"));
121/// extract_ctx.input_ikm(b"hello");
122/// extract_ctx.input_ikm(b" world");
123/// let (streamed_res, _) = extract_ctx.finalize();
124///
125/// let (oneshot_res, _) = Hkdf::<Sha256>::extract(Some(b"mysalt"), b"hello world");
126/// assert_eq!(streamed_res, oneshot_res);
127/// ```
128#[derive(Clone)]
129pub struct HkdfExtract<H, I = Hmac<H>>
130where
131    H: OutputSizeUser,
132    I: HmacImpl<H>,
133{
134    hmac: I,
135    _pd: PhantomData<H>,
136}
137
138impl<H, I> HkdfExtract<H, I>
139where
140    H: OutputSizeUser,
141    I: HmacImpl<H>,
142{
143    /// Initiates the HKDF-Extract context with the given optional salt
144    pub fn new(salt: Option<&[u8]>) -> Self {
145        let default_salt = Output::<H>::default();
146        let salt = salt.unwrap_or(&default_salt);
147        Self {
148            hmac: I::new_from_slice(salt),
149            _pd: PhantomData,
150        }
151    }
152
153    /// Feeds in additional input key material to the HKDF-Extract context
154    pub fn input_ikm(&mut self, ikm: &[u8]) {
155        self.hmac.update(ikm);
156    }
157
158    /// Completes the HKDF-Extract operation, returning both the generated pseudorandom key and
159    /// `Hkdf` struct for expanding.
160    pub fn finalize(self) -> (Output<H>, Hkdf<H, I>) {
161        let prk = self.hmac.finalize();
162        let hkdf = Hkdf::from_prk(&prk).expect("PRK size is correct");
163        (prk, hkdf)
164    }
165}
166
167impl<H, I> fmt::Debug for HkdfExtract<H, I>
168where
169    H: OutputSizeUser + AlgorithmName,
170    I: HmacImpl<H>,
171{
172    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
173        f.write_str("HkdfExtract<")?;
174        <H as AlgorithmName>::write_alg_name(f)?;
175        f.write_str("> { ... }")
176    }
177}
178
179/// Structure representing the HKDF, capable of HKDF-Expand and HKDF-Extract operations.
180#[derive(Clone)]
181pub struct Hkdf<H: OutputSizeUser, I: HmacImpl<H> = Hmac<H>> {
182    hmac: I::Core,
183    _pd: PhantomData<H>,
184}
185
186impl<H: OutputSizeUser, I: HmacImpl<H>> Hkdf<H, I> {
187    /// Convenience method for [`extract`][Hkdf::extract] when the generated
188    /// pseudorandom key can be ignored and only HKDF-Expand operation is needed. This is the most
189    /// common constructor.
190    pub fn new(salt: Option<&[u8]>, ikm: &[u8]) -> Self {
191        let (_, hkdf) = Self::extract(salt, ikm);
192        hkdf
193    }
194
195    /// Create `Hkdf` from an already cryptographically strong pseudorandom key
196    /// as per section 3.3 from RFC5869.
197    pub fn from_prk(prk: &[u8]) -> Result<Self, InvalidPrkLength> {
198        // section 2.3 specifies that prk must be "at least HashLen octets"
199        if prk.len() < <H as OutputSizeUser>::OutputSize::to_usize() {
200            return Err(InvalidPrkLength);
201        }
202        Ok(Self {
203            hmac: I::new_core(prk),
204            _pd: PhantomData,
205        })
206    }
207
208    /// The RFC5869 HKDF-Extract operation returning both the generated
209    /// pseudorandom key and `Hkdf` struct for expanding.
210    pub fn extract(salt: Option<&[u8]>, ikm: &[u8]) -> (Output<H>, Self) {
211        let mut extract_ctx = HkdfExtract::new(salt);
212        extract_ctx.input_ikm(ikm);
213        extract_ctx.finalize()
214    }
215
216    /// The RFC5869 HKDF-Expand operation. This is equivalent to calling
217    /// [`expand`][Hkdf::extract] with the `info` argument set equal to the
218    /// concatenation of all the elements of `info_components`.
219    pub fn expand_multi_info(
220        &self,
221        info_components: &[&[u8]],
222        okm: &mut [u8],
223    ) -> Result<(), InvalidLength> {
224        let mut prev: Option<Output<H>> = None;
225
226        let chunk_len = <H as OutputSizeUser>::OutputSize::USIZE;
227        if okm.len() > chunk_len * 255 {
228            return Err(InvalidLength);
229        }
230
231        for (block_n, block) in okm.chunks_mut(chunk_len).enumerate() {
232            let mut hmac = I::from_core(&self.hmac);
233
234            if let Some(ref prev) = prev {
235                hmac.update(prev)
236            };
237
238            // Feed in the info components in sequence. This is equivalent to feeding in the
239            // concatenation of all the info components
240            for info in info_components {
241                hmac.update(info);
242            }
243
244            hmac.update(&[block_n as u8 + 1]);
245
246            let output = hmac.finalize();
247
248            let block_len = block.len();
249            block.copy_from_slice(&output[..block_len]);
250
251            prev = Some(output);
252        }
253
254        Ok(())
255    }
256
257    /// The RFC5869 HKDF-Expand operation
258    ///
259    /// If you don't have any `info` to pass, use an empty slice.
260    pub fn expand(&self, info: &[u8], okm: &mut [u8]) -> Result<(), InvalidLength> {
261        self.expand_multi_info(&[info], okm)
262    }
263}
264
265impl<H, I> fmt::Debug for Hkdf<H, I>
266where
267    H: OutputSizeUser + AlgorithmName,
268    I: HmacImpl<H>,
269{
270    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
271        f.write_str("Hkdf<")?;
272        <H as AlgorithmName>::write_alg_name(f)?;
273        f.write_str("> { ... }")
274    }
275}
276
277/// Sealed trait implemented for [`Hmac`] and [`SimpleHmac`].
278pub trait HmacImpl<H: OutputSizeUser>: sealed::Sealed<H> {}
279
280impl<H: OutputSizeUser, T: sealed::Sealed<H>> HmacImpl<H> for T {}
hkdf/lib.rs

hkdf/
lib.rs
