hkdf/
lib.rs

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

hkdf/
lib.rs
